Topics

API + MCP

GET/v3/content-helper/topics

This endpoint consumes a base amount of 1000 units per request, plus 500 units if you request a URL to score.

The analysis runs on demand against the pages currently ranking for the keyword, so the first request for a keyword takes a few seconds. Results are cached, and repeat requests are served from the cache free of charge.

Only SERPs Ahrefs has already collected are used, and no new SERP is collected. If we have collected a SERP for the keyword and country in the last 90 days, the endpoint returns a 400 error and no units are consumed.

Parameter kueri

keywordstringWajib

The keyword to analyse the SERP for.

countrystringWajib

A two-letter country code (ISO 3166-1 alpha-2).

Nilai yang diizinkan:adaeafagaialamaoarasatauawazba…

top_competitorsinteger

How many of the top-ranking pages to analyse. Fewer pages make the analysis faster at the cost of breadth.

Default:10

target_urlstring (url)

(500 units) A page of your own to score against the same topics, for example a draft you are writing or a page you want to improve. The page is fetched live. Costs additional API units each time (its scoring is not cached).

outputstring

The output format.

Nilai yang diizinkan:jsonphp

Respons

topicsarray<object>

avg_scorenumber (float)

The mean coverage score of this topic, from 0 to 100, over the pages that could be analysed. A high value means the topic is thoroughly covered by the pages that already rank. Null when none of the pages could be analysed.

descriptionstring

What the core topic is about, as identified from the competing pages.

pagesarray<object>

Per-page coverage of this topic: a record with fields url, position (the page's SERP position), score (0-100) and extracts (passages from the page that cover the topic). score and extracts are null and empty for a page whose content could not be retrieved, which is distinct from a page that scored zero.

urlstring (url)

positioninteger

scoreinteger

extractsarray<string>

pages_coveringinteger

How many of the analysed pages cover this topic at all (a non-zero score).

serp_datestring (date)

When the analysed SERP was collected.

targetobject or null

How the page given as target_url covers this topic. Null when target_url was not given.

urlstring (url)

scoreinteger

extractsarray<string>

topicstring

The name of the core topic covered by the top-ranking pages.