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

selectarray<string>Required

A list of columns to return. See response schema for valid column identifiers.

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).

cited_domain: The domain of a page that was used to generate the response.
type: domain

cited_domain_subdomains: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match.
type: string

cited_url_exact: The URL of a page that was used to generate the response.
type: string

cited_url_prefix: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match.
type: string

question: The question asked by the user.
type: string

response (10 units): The response from the model.
type: string

search_queries: 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.
type: string

topic: The topic of the query.
type: string

limitinteger

The number of results to return.

Default:1000
datestring

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

countryarray<string>

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

Allowed values:adaeafagaialamaoarasatauawazbabbbdbebfbgbhbibjbnbobrbsbtbwbybzcacdcfcgchcickclcmcncocrcucvcyczdedjdkdmdodzeceeegesetfifjfmfofrgagbgdgegfggghgiglgmgngpgqgrgtgugyhkhnhrhthuidieiliminiqisitjejmjojpkekgkhkiknkrkwkykzlalblclilklsltlulvlymamcmdmemgmkmlmmmnmqmrmsmtmumvmwmxmymznancnengninlnonpnrnunzompapepfpgphpkplpnprpsptpyqarerorsrurwsasbscsesgshsiskslsmsnsosrstsvtdtgthtjtktltmtntotrtttwtzuaugusuyuzvcvevgvivnvuwsyeytzazmzw
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. Google models (google_ai_overviews, google_ai_mode) cannot be combined with each other or with non-Google models.

Allowed values:google_ai_overviewsgoogle_ai_modechatgptgeminiperplexitycopilot
marketarray<string>

A list of the niche markets of your brands.

competitorsarray<object>

A list of competitor names and websites to search for.

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>
targetstringrequired

The domain of the target

Example:ahrefs.com
scopestringrequired

Scope of the target.

Allowed values:urldomainsubdomains
brandsarray<object>

A list of brand names and websites to search for.

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>
targetstringrequired

The domain of the target

Example:ahrefs.com
scopestringrequired

Scope of the target.

Allowed values:urldomainsubdomains
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.

linksarray<object>

(10 units) The links used for the response.

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.