Overview - Citations

API only

POST/v3/brand-radar/citations-overview

Requests to this endpoint consume API units based on the prompts parameter: requests returning only custom prompt data are free, while requests including Ahrefs prompt data follow standard API unit pricing.

Every entity provided in brands (and competitors, when applicable) must include at least one value in url_groups. Entities consisting only of names are not supported here because citations are matched against URL groups.

Request body

whereobject

The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the select parameter).

selectarray<string>Required

A list of fields to return.

Example:["field_a","field_b"]

tags_filterobject

A filter expression for prompt tags. Requires report_id. Uses filter syntax with the following restrictions: the only valid field name is "tag"; the only valid operator are: "eq", "neq", "substring", "isubstring", "phrase_match", "iphrase_match", "prefix", "suffix", "empty"; maximum nesting depth of and, or is 2.

Example:{"or":[{"field":"tag","is":["eq","branded"]},{"field":"tag","is":["eq","competitor"]}]}

search_volume_typestring

AI visibility reports are switching to AI adjusted volume. It better estimates demand for AI responses across chatbots and AI search surfaces. It is calculated by adjusting Google search volume for each AI platform’s estimated usage compared with Google. This param will be deprecated on August 31, 2026; all requests will use new AI adjusted volume.

Allowed values:ask_volumekeyword_volume

Default:ask_volume

countryarray<string>

A list of two-letter country codes (ISO 3166-1 alpha-2).

Allowed values:adaeafagaialamaoarasatauawazba…

Default:[]

report_idstring

The ID of the report to use. If one is given, other parameters are taken from the report (brand, competitors, market, country, filters). If country or filters are provided, they override the ones in the report. You can find it in the URL of your Brand Radar report in Ahrefs: https://app.ahrefs.com/brand-radar/reports/#report_id#/...

promptsstring

The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided.

Allowed values:ahrefscustom

data_sourcearray<string>Required

A list of chatbot models. All models can be combined with each other. claude module supports only custom prompts. The google_ai_overviews_keywords and google_ai_mode_keywords models report AI Overviews / AI Mode visibility derived from Google search queries (keywords) rather than prompts.

Allowed values:chatgptgoogle_ai_overviewsgoogle_ai_modegeminiperplexitycopilotclaudegrokgoogle_ai_overviews_keywordsgoogle_ai_mode_keywords

marketarray<string>

A list of the niche markets of your brands. Deprecated on 2026-05-18, this parameter will have no effect shortly after this date.

competitorsarray<object>

A list of competitor names and websites to search for.

Default:[]

At least one of names or url_groups is required

namesarray<string>

The names of the brand/competitor

Example:["ahrefs","ahrefs seo"]

url_groupsarray<object>

targetstring (domain)required

The domain of the target

Example:ahrefs.com

scopestringrequired

Scope of the target.

Allowed values:urlpathdomainsubdomains

brandsarray<object>

A list of brand names and websites to search for.

Default:[]

At least one of names or url_groups is required

namesarray<string>

The names of the brand/competitor

Example:["ahrefs","ahrefs seo"]

url_groupsarray<object>

targetstring (domain)required

The domain of the target

Example:ahrefs.com

scopestringrequired

Scope of the target.

Allowed values:urlpathdomainsubdomains

outputstring

The output format.

Allowed values:jsoncsvxmlphp

Responses

metricsarray<object>

brandstring

Brand name (either your brand or a competitor provided in the request).

no_tracked_brandsinteger

Estimated citations from responses related to the specified market that do not mention any provided brand URLs (value is zero when market is not specified).

only_competitors_brandsinteger

Estimated citations from responses mentioning only competitors' brand URLs.

only_target_brandinteger

Estimated citations from responses mentioning only your brand URLs.

target_and_competitors_brandsinteger

Estimated citations from responses mentioning both your and competitors' brand URLs.

totalinteger

Total estimated citations for your brand URLs (includes both only_target_brand and target_and_competitors_brands).

curl "https://api.ahrefs.com/v3/brand-radar/citations-overview" \ -X POST \ -H "Authorization: Bearer $AHREFS_API_KEY" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ --data-raw '{ "where": {}, "select": ["field_a","field_b"], "tags_filter": {"or":[{"field":"tag","is":["eq","branded"]},{"field":"tag","is":["eq","competitor"]}]}, "search_volume_type": "ask_volume", "country": ["ad"], "report_id": "string", "prompts": "ahrefs", "data_source": ["chatgpt"], "market": ["string"], "competitors": [ { "names": ["ahrefs","ahrefs seo"], "url_groups": [ { "target": "ahrefs.com", "scope": "url" } ] } ], "brands": [ { "names": ["ahrefs","ahrefs seo"], "url_groups": [ { "target": "ahrefs.com", "scope": "url" } ] } ], "output": "json" }'

{ "metrics": [ { "brand": "string", "no_tracked_brands": 0, "only_competitors_brands": 0, "only_target_brand": 0, "target_and_competitors_brands": 0, "total": 0 } ] }