AHahrefs
Brand Radar

AI Responses

Changed on

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.

post/brand-radar/ai-responses

Request

  • Base URL
    https://api.ahrefs.com/v3
  • URL
    https://api.ahrefs.com/v3/brand-radar/ai-responses
  • Auth
    HTTP bearer

Request body

selectstring[] required

A list of fields to return.

  • brand_sentiment
  • country
  • data_source
  • funnel_stage
  • intent
  • last_updated
  • links (10 units)
  • question
  • response
  • search_queries
  • status
  • tags
  • volume (10 units)
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. Note: the substring and isubstring operators are not supported on this field; use phrase_match or iphrase_match instead.
type: string

response (10 units): The response from the model. Note: the substring and isubstring operators are not supported on this field; use phrase_match or iphrase_match instead.
type: string

response_entity: An entity that the model recognized in its response. Note: the substring and isubstring operators are not supported on this field; use phrase_match or iphrase_match instead.
type: string

response_entity_organisation: An entity in the organisation category that the model recognized in its response. Note: the substring and isubstring operators are not supported on this field; use phrase_match or iphrase_match instead.
type: string

response_entity_person: An entity in the person category that the model recognized in its response. Note: the substring and isubstring operators are not supported on this field; use phrase_match or iphrase_match instead.
type: string

response_entity_product: An entity in the product category that the model recognized in its response. Note: the substring and isubstring operators are not supported on this field; use phrase_match or iphrase_match instead.
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. Note: the substring and isubstring operators are not supported on this field; use phrase_match or iphrase_match instead.
type: string

sponsored_advertiser: The advertiser name shown on a sponsored result.
type: string

sponsored_description: The description of a sponsored result.
type: string

sponsored_domain: The domain of a sponsored result.
type: domain

sponsored_domain_subdomains: The domain of a sponsored result, including any of its subdomains.
type: string

sponsored_kind: The sponsored result type. Allowed values: ad, product.
type: string

sponsored_result: Whether the response contains a sponsored result. This field only supports the empty operator and its negation.
type: string

sponsored_title: The title of a sponsored result.
type: string

sponsored_url_exact: The exact URL of a sponsored result.
type: string

sponsored_url_prefix: The URL prefix of a sponsored result.
type: string

topic: The topic of the query. Note: the substring and isubstring operators are not supported on this field; use phrase_match or iphrase_match instead.
type: string

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#/...

data_sourcestring[] 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.

countrystring[]

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

prompts'ahrefs' | 'custom'

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

limitinteger

The number of results to return.

datestring date

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

date_comparedstring date

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.

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.

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

sentiment_filterobject

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 from brands or competitors, with "eq".
  • sentiment (optional): positive, neutral, negative or mixed. 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. With not "empty", the brand is mentioned with some sentiment. Without sentiment, 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_support or general. Each rule is about one brand: one condition, or an and of conditions. To combine rules, put each one in its own and and join them with a top-level and or or.
opinions_firstboolean

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.

output'json' | 'php'

The output format.

Example request

{
  "select": [
    "field_a",
    "field_b"
  ],
  "brands": [
    {
      "names": [
        "ahrefs",
        "ahrefs seo"
      ],
      "url_groups": [
        {
          "target": "ahrefs.com"
        }
      ]
    }
  ],
  "competitors": [
    {
      "names": [
        "ahrefs",
        "ahrefs seo"
      ],
      "url_groups": [
        {
          "target": "ahrefs.com"
        }
      ]
    }
  ],
  "tags_filter": {
    "or": [
      {
        "field": "tag",
        "is": [
          "eq",
          "branded"
        ]
      },
      {
        "field": "tag",
        "is": [
          "eq",
          "competitor"
        ]
      }
    ]
  },
  "brand_filter": {
    "and": [
      {
        "field": "brand_name",
        "is": [
          "eq",
          "mentioned"
        ]
      },
      {
        "or": [
          {
            "field": "page_status",
            "is": [
              "eq",
              "cited"
            ]
          },
          {
            "field": "page_status",
            "is": [
              "eq",
              "found_but_not_cited"
            ]
          }
        ]
      }
    ]
  },
  "sentiment_filter": {
    "or": [
      {
        "and": [
          {
            "field": "brand",
            "is": [
              "eq",
              "Adidas"
            ]
          },
          {
            "field": "sentiment",
            "is": [
              "eq",
              "negative"
            ]
          }
        ]
      },
      {
        "and": [
          {
            "field": "brand",
            "is": [
              "eq",
              "Nike"
            ]
          },
          {
            "field": "sentiment",
            "is": [
              "eq",
              "positive"
            ]
          },
          {
            "field": "aspect",
            "is": [
              "eq",
              "price_value"
            ]
          }
        ]
      }
    ]
  }
}

Response

OK

Changes

  • 46cb9eb56b2bRevision changes
    • breaking

      removed the enum value relevance of the request property

    • breaking

      removed the enum value volume of the request property

    • breaking

      the request property type changed from string to no type

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added subschema #1 subschema #2 to the request property oneOf list

    • info

      added the optional property // to the response with the status (media type: application/json)

    • info

      added the optional property // to the response with the status (media type: application/xml)

  • 5cd2cfd947d0Revision changes
    • info

      added the optional property // to the response with the status (media type: application/json)

    • info

      added the optional property // to the response with the status (media type: application/xml)

    • info

      added the optional property // to the response with the status (media type: application/json)

    • info

      added the optional property // to the response with the status (media type: application/xml)