AI Responses
API + MCPRequests to this endpoint consume API units based on the
promptsparameter: requests returning only custom prompt data are free, while requests including Ahrefs prompt data follow standard API unit pricing.
Request body
A list of fields to return.
The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the select parameter).
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#/...
A list of brand names and websites to search for.
names or url_groups is requiredThe names of the brand/competitor
The domain of the target
Scope of the target.
A list of competitor names and websites to search for.
names or url_groups is requiredThe names of the brand/competitor
The domain of the target
Scope of the target.
Optional phrases used to include or exclude results based on their content.
Only show results containing at least one of these exact phrases.
Hide results containing any of these exact phrases.
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.
A list of two-letter country codes (ISO 3166-1 alpha-2).
The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided.
The number of results to return.
The date to search for in YYYY-MM-DD format.
A date to compare date with, in YYYY-MM-DD format. Must be strictly earlier than date. When set, the report covers every prompt answered on either date and the status field reports how each one changed between them. A prompt answered only on date_compared is reported as lost, and the rest of its fields describe its date_compared response, since it has none on date.
How to order the results: a column, or how the responses talk about one brand, as the Sentiment page in Brand Radar can.
A column to order the results by.
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.
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).
The volume range to filter by.
Requires date_compared. Keeps only the prompts that changed in one of the ways selected here. The three columns are OR'd with each other, as are the values within each column, so an omitted or empty column adds nothing to the filter and an entirely empty object keeps every prompt.
Keep prompts that were answered on only one of the two dates (new, lost) or on both (no_change).
Keep prompts where the set of your own brands mentioned in the response gained a brand (new), lost one (lost), or is identical on both dates (no_change). Competitors are not considered.
Keep prompts where the set of your own domains cited by the response gained a domain (new), lost one (lost), or is identical on both dates (no_change). Competitors are not considered.
A filter on how the responses talk about your brands and competitors, like the Sentiment filter in Brand Radar. Uses filter syntax with three fields:
brand(required): a name frombrandsorcompetitors, with"eq".sentiment(optional):positive,neutral,negativeormixed. With"eq", the brand is mentioned with this sentiment. With"neq", the brand is mentioned with a sentiment, but never this one. With"empty", the brand is never mentioned with a sentiment, which includes responses that don't mention it. Withnot"empty", the brand is mentioned with some sentiment. Withoutsentiment, any response that mentions the brand matches.aspect(optional): what the sentiment is about, with"eq":features_specs,performance_effectiveness,price_value,reputation_popularity,quality_reliability,design_comfort,usability_compatibility,availability_delivery,safety_health,service_supportorgeneral.
Each rule is about one brand: one condition, or anandof conditions. To combine rules, put each one in its ownandand join them with a top-levelandoror.
Puts the responses with a positive, negative or mixed mention of a tracked brand before the others, each group by relevance, as the Sentiment page in Brand Radar lists them. Only with order_by relevance.
The output format.
Responses
Every mention of a tracked brand in the response, your brands first and then the competitors in their order, with how the response talks about it.
The tracked brand mentioned.
How the response talks about the brand at this mention. Null when it isn't available.
What the mention is about, such as price or quality. Null when it isn't available.
The sentence around the mention. Null when it can't be found in the response.
The country of the question.
The chatbot model that generated the response.
The prompt's funnel stage. Null when no funnel stage is available.
The prompt's intent labels, including its primary intent, subtypes, and branded/local attributes. An empty array means no intent labels are available.
The date when the data was last updated.
(10 units) The links used for the response.
The question asked by the user.
(10 units) The response from the model.
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.
How the prompt changed between date_compared and date. Null unless date_compared is set. new — answered on date but not on date_compared. lost — answered on date_compared but not on date; the rest of this row describes the date_compared response, as there is none on date. no_change — answered on both dates, which says nothing about whether the response itself, its mentions or its citations changed.
Tags assigned to the query.
(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.