Docs
Search docs...⌘K

AI Responses

API + MCP
POST/v3/brand-radar/ai-responses

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.

Request body

brand_filterobject

A filter expression for your brand's visibility, mirroring the "Your brand" filter. brand_name matches whether a response mentions your brand: "mentioned" or "not_mentioned". page_status matches how the AI used your pages: "cited" (the AI retrieved pages from your site and referenced them in the answer), "found_but_not_cited" (the AI retrieved pages from your site as potential sources but did not reference them in the final answer), or "not_found" (the AI did not retrieve any pages from your site).
Uses filter syntax with the following restrictions: the only valid operator is "eq"; each field is one section: give a single value, or combine several values of the same field with or; join the brand_name and page_status sections with a top-level and/or. Selecting every value of a field is rejected, since it matches everything (omit the field instead).

Example:{"and":[{"field":"brand_name","is":["eq","mentioned"]},{"or":[{"field":"page_status","is":["eq","cited"]},{"field":"page_status","is":["eq","found_but_not_cited"]}]}]}
volume_rangeobject

The volume range to filter by.

frominteger
tointeger
selectarray<string>Required

A list of fields to return.

Example:["field_a","field_b"]
whereobject

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

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"]}]}
limitinteger

The number of results to return.

Default:1000
datestring (date)

The date to search for in YYYY-MM-DD format.

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:[]
order_bystring

A column to order the results by.

Allowed values:relevancevolume
Default:relevance
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:jsonphp

Responses

ai_responsesarray<object>
countrystring

The country of the question.

data_sourcestring

The chatbot model that generated the response.

last_updatedstring (date)

The date when the data was last updated.

linksarray<object>

(10 units) The links used for the response.

urlstring
titlestring or null
questionstring

The question asked by the user.

responsestring

(10 units) The response from the model.

search_queriesarray<string>

The search query used by the chatbot to find information for the response. Note: if data_source does not include chatgpt or perplexity, this field will always be empty.

tagsarray<string>

Tags assigned to the query.

volumeinteger

(10 units) Estimated monthly searches. This is based on our estimates for Google, combining the search volumes of related keywords where this question appears in People Also Ask section.