{
  "openapi": "3.2.0",
  "info": {
    "title": "Brand Radar",
    "description": "Brand radar.",
    "termsOfService": "https://ahrefs.com/terms",
    "contact": {
      "name": "Ahrefs",
      "url": "https://ahrefs.com/",
      "email": "support@ahrefs.com"
    },
    "version": "3.0.0"
  },
  "servers": [
    {
      "url": "https://api.ahrefs.com/v3/brand-radar",
      "description": "Ahrefs Brand Radar"
    }
  ],
  "paths": {
    "/ai-responses": {
      "get": {
        "tags": [ "AI visibility", "MCP" ],
        "summary": "AI Responses",
        "description": ">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.",
        "operationId": "ai-responses",
        "parameters": [
          {
            "description": "A comma-separated list of fields to return.\n\n- `brand_sentiment`\n- `country`\n- `data_source`\n- `funnel_stage`\n- `intent`\n- `last_updated`\n- `links` (10 units)\n- `question`\n- `response`\n- `search_queries`\n- `status`\n- `tags`\n- `volume` (10 units)",
            "required": true,
            "explode": false,
            "schema": { "type": "string" },
            "name": "select",
            "in": "query"
          },
          {
            "description": "The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter).\n\n**cited_domain**: The domain of a page that was used to generate the response.  \ntype: domain\n\n**cited_domain_subdomains**: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match.  \ntype: string\n\n**cited_url_exact**: The URL of a page that was used to generate the response.  \ntype: string\n\n**cited_url_prefix**: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match.  \ntype: string\n\n**inline_domain**: The domain of a page linked in the response text.  \ntype: domain\n\n**inline_domain_subdomains**: The domain of a page linked in the response text. Any subdomain of the given domain will also match.  \ntype: string\n\n**inline_url_exact**: The URL of a page linked in the response text.  \ntype: string\n\n**inline_url_prefix**: The URL of a page linked in the response text. Any URL that starts with this prefix will match.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**sponsored_advertiser**: The advertiser name shown on a sponsored result.  \ntype: string\n\n**sponsored_description**: The description of a sponsored result.  \ntype: string\n\n**sponsored_domain**: The domain of a sponsored result.  \ntype: domain\n\n**sponsored_domain_subdomains**: The domain of a sponsored result, including any of its subdomains.  \ntype: string\n\n**sponsored_kind**: The sponsored result type. Allowed values: `ad`, `product`.  \ntype: string\n\n**sponsored_result**: Whether the response contains a sponsored result. This field only supports the `empty` operator and its negation.  \ntype: string\n\n**sponsored_title**: The title of a sponsored result.  \ntype: string\n\n**sponsored_url_exact**: The exact URL of a sponsored result.  \ntype: string\n\n**sponsored_url_prefix**: The URL prefix of a sponsored result.  \ntype: string\n\n**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.  \ntype: string",
            "required": false,
            "explode": false,
            "schema": { "type": "string" },
            "name": "where",
            "in": "query"
          },
          {
            "description": "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#/...`",
            "required": false,
            "explode": false,
            "schema": { "type": "string" },
            "name": "report_id",
            "in": "query"
          },
          {
            "description": "A comma-separated list of brands to search for. At least one of brand, competitors, market or where should not be empty.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "default": "" },
            "name": "brand",
            "in": "query"
          },
          {
            "description": "A comma-separated list of competitors of your brands.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "default": "" },
            "name": "competitors",
            "in": "query"
          },
          {
            "description": "A comma-separated list of chatbot models. All models can be combined with each other. `claude` module supports only custom prompts.\nThe `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.",
            "required": true,
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "chatgpt", "google_ai_overviews", "google_ai_mode", "gemini",
                "perplexity", "copilot", "claude", "grok",
                "google_ai_overviews_keywords", "google_ai_mode_keywords"
              ],
              "examples": [ "chatgpt,perplexity" ]
            },
            "name": "data_source",
            "in": "query"
          },
          {
            "description": "A comma-separated list of two-letter country codes (ISO 3166-1 alpha-2).",
            "required": false,
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar", "as",
                "at", "au", "aw", "az", "ba", "bb", "bd", "be", "bf", "bg",
                "bh", "bi", "bj", "bn", "bo", "br", "bs", "bt", "bw", "by",
                "bz", "ca", "cd", "cf", "cg", "ch", "ci", "ck", "cl", "cm",
                "cn", "co", "cr", "cu", "cv", "cy", "cz", "de", "dj", "dk",
                "dm", "do", "dz", "ec", "ee", "eg", "es", "et", "fi", "fj",
                "fm", "fo", "fr", "ga", "gb", "gd", "ge", "gf", "gg", "gh",
                "gi", "gl", "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gy",
                "hk", "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in",
                "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg", "kh",
                "ki", "kn", "kr", "kw", "ky", "kz", "la", "lb", "lc", "li",
                "lk", "ls", "lt", "lu", "lv", "ly", "ma", "mc", "md", "me",
                "mg", "mk", "ml", "mm", "mn", "mq", "mr", "ms", "mt", "mu",
                "mv", "mw", "mx", "my", "mz", "na", "nc", "ne", "ng", "ni",
                "nl", "no", "np", "nr", "nu", "nz", "om", "pa", "pe", "pf",
                "pg", "ph", "pk", "pl", "pn", "pr", "ps", "pt", "py", "qa",
                "re", "ro", "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg",
                "sh", "si", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv",
                "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to", "tr",
                "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz", "vc", "ve",
                "vg", "vi", "vn", "vu", "ws", "ye", "yt", "za", "zm", "zw"
              ],
              "default": ""
            },
            "name": "country",
            "in": "query"
          },
          {
            "description": "The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "enum": [ "ahrefs", "custom" ] },
            "name": "prompts",
            "in": "query"
          },
          {
            "description": "The number of results to return.",
            "required": false,
            "explode": false,
            "schema": { "type": "integer", "default": 1000 },
            "name": "limit",
            "in": "query"
          },
          {
            "description": "The date to search for in YYYY-MM-DD format.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "format": "date" },
            "name": "date",
            "in": "query"
          },
          {
            "description": "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`.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "format": "date" },
            "name": "date_compared",
            "in": "query"
          },
          {
            "description": "A column to order the results by.",
            "required": false,
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [ "relevance", "volume" ],
              "default": "relevance"
            },
            "name": "order_by",
            "in": "query"
          },
          { "$ref": "#/components/parameters/output_json_php" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ai-responses" }
              },
              "application/xml": {
                "schema": { "$ref": "#/components/schemas/ai-responses" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      },
      "post": {
        "tags": [ "AI visibility", "MCP" ],
        "summary": "AI Responses",
        "description": ">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.",
        "operationId": "ai-responses",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "select": {
                    "items": { "type": "string" },
                    "type": "array",
                    "description": "A list of fields to return.\n\n- `brand_sentiment`\n- `country`\n- `data_source`\n- `funnel_stage`\n- `intent`\n- `last_updated`\n- `links` (10 units)\n- `question`\n- `response`\n- `search_queries`\n- `status`\n- `tags`\n- `volume` (10 units)",
                    "examples": [ [ "field_a", "field_b" ] ]
                  },
                  "where": {
                    "type": "object",
                    "description": "The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter).\n\n**cited_domain**: The domain of a page that was used to generate the response.  \ntype: domain\n\n**cited_domain_subdomains**: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match.  \ntype: string\n\n**cited_url_exact**: The URL of a page that was used to generate the response.  \ntype: string\n\n**cited_url_prefix**: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match.  \ntype: string\n\n**inline_domain**: The domain of a page linked in the response text.  \ntype: domain\n\n**inline_domain_subdomains**: The domain of a page linked in the response text. Any subdomain of the given domain will also match.  \ntype: string\n\n**inline_url_exact**: The URL of a page linked in the response text.  \ntype: string\n\n**inline_url_prefix**: The URL of a page linked in the response text. Any URL that starts with this prefix will match.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**sponsored_advertiser**: The advertiser name shown on a sponsored result.  \ntype: string\n\n**sponsored_description**: The description of a sponsored result.  \ntype: string\n\n**sponsored_domain**: The domain of a sponsored result.  \ntype: domain\n\n**sponsored_domain_subdomains**: The domain of a sponsored result, including any of its subdomains.  \ntype: string\n\n**sponsored_kind**: The sponsored result type. Allowed values: `ad`, `product`.  \ntype: string\n\n**sponsored_result**: Whether the response contains a sponsored result. This field only supports the `empty` operator and its negation.  \ntype: string\n\n**sponsored_title**: The title of a sponsored result.  \ntype: string\n\n**sponsored_url_exact**: The exact URL of a sponsored result.  \ntype: string\n\n**sponsored_url_prefix**: The URL prefix of a sponsored result.  \ntype: string\n\n**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.  \ntype: string"
                  },
                  "report_id": {
                    "type": "string",
                    "description": "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#/...`"
                  },
                  "brands": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of brand names and websites to search for.",
                    "default": []
                  },
                  "competitors": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of competitor names and websites to search for.",
                    "default": []
                  },
                  "content_filter": {
                    "properties": {
                      "include": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Only show results containing at least one of these exact phrases."
                      },
                      "exclude": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Hide results containing any of these exact phrases."
                      }
                    },
                    "type": "object",
                    "description": "Optional phrases used to include or exclude results based on their content."
                  },
                  "data_source": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "chatgpt", "google_ai_overviews", "google_ai_mode",
                        "gemini", "perplexity", "copilot", "claude", "grok",
                        "google_ai_overviews_keywords",
                        "google_ai_mode_keywords"
                      ]
                    },
                    "type": "array",
                    "description": "A list of chatbot models. All models can be combined with each other. `claude` module supports only custom prompts.\nThe `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."
                  },
                  "country": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar",
                        "as", "at", "au", "aw", "az", "ba", "bb", "bd", "be",
                        "bf", "bg", "bh", "bi", "bj", "bn", "bo", "br", "bs",
                        "bt", "bw", "by", "bz", "ca", "cd", "cf", "cg", "ch",
                        "ci", "ck", "cl", "cm", "cn", "co", "cr", "cu", "cv",
                        "cy", "cz", "de", "dj", "dk", "dm", "do", "dz", "ec",
                        "ee", "eg", "es", "et", "fi", "fj", "fm", "fo", "fr",
                        "ga", "gb", "gd", "ge", "gf", "gg", "gh", "gi", "gl",
                        "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gy", "hk",
                        "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in",
                        "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg",
                        "kh", "ki", "kn", "kr", "kw", "ky", "kz", "la", "lb",
                        "lc", "li", "lk", "ls", "lt", "lu", "lv", "ly", "ma",
                        "mc", "md", "me", "mg", "mk", "ml", "mm", "mn", "mq",
                        "mr", "ms", "mt", "mu", "mv", "mw", "mx", "my", "mz",
                        "na", "nc", "ne", "ng", "ni", "nl", "no", "np", "nr",
                        "nu", "nz", "om", "pa", "pe", "pf", "pg", "ph", "pk",
                        "pl", "pn", "pr", "ps", "pt", "py", "qa", "re", "ro",
                        "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg", "sh",
                        "si", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv",
                        "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to",
                        "tr", "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz",
                        "vc", "ve", "vg", "vi", "vn", "vu", "ws", "ye", "yt",
                        "za", "zm", "zw"
                      ]
                    },
                    "type": "array",
                    "description": "A list of two-letter country codes (ISO 3166-1 alpha-2).",
                    "default": []
                  },
                  "prompts": {
                    "type": "string",
                    "enum": [ "ahrefs", "custom" ],
                    "description": "The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided."
                  },
                  "limit": {
                    "type": "integer",
                    "description": "The number of results to return.",
                    "default": 1000
                  },
                  "date": {
                    "type": "string",
                    "format": "date",
                    "description": "The date to search for in YYYY-MM-DD format."
                  },
                  "date_compared": {
                    "type": "string",
                    "format": "date",
                    "description": "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`."
                  },
                  "order_by": {
                    "oneOf": [
                      {
                        "type": "string",
                        "enum": [ "relevance", "volume" ],
                        "description": "A column to order the results by."
                      },
                      {
                        "properties": {
                          "direction": {
                            "type": "string",
                            "enum": [ "most_negative", "most_positive" ],
                            "description": "Whether the most negative or the most positive responses come first."
                          },
                          "brand": {
                            "type": "string",
                            "description": "The brand to order by: a name from `brands` or `competitors`."
                          },
                          "aspect": {
                            "type": "string",
                            "enum": [
                              "features_specs", "performance_effectiveness",
                              "price_value", "reputation_popularity",
                              "quality_reliability", "design_comfort",
                              "usability_compatibility",
                              "availability_delivery", "safety_health",
                              "service_support", "general"
                            ],
                            "description": "Only read the mentions about this aspect."
                          }
                        },
                        "type": "object",
                        "required": [ "direction", "brand" ],
                        "description": "The responses most negative (or most positive) about one brand first, then the rest by relevance."
                      }
                    ],
                    "description": "How to order the results: a column, or how the responses talk about one brand, as the Sentiment page in Brand Radar can.",
                    "default": "relevance"
                  },
                  "tags_filter": {
                    "properties": {},
                    "type": "object",
                    "description": "A filter expression for prompt tags. Requires `report_id`. Uses [filter syntax](https://docs.ahrefs.com/api/docs/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.",
                    "examples": [
                      {
                        "or": [
                          { "field": "tag", "is": [ "eq", "branded" ] },
                          { "field": "tag", "is": [ "eq", "competitor" ] }
                        ]
                      }
                    ]
                  },
                  "brand_filter": {
                    "properties": {},
                    "type": "object",
                    "description": "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). \nUses [filter syntax](https://docs.ahrefs.com/api/docs/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).",
                    "examples": [
                      {
                        "and": [
                          {
                            "field": "brand_name",
                            "is": [ "eq", "mentioned" ]
                          },
                          {
                            "or": [
                              {
                                "field": "page_status",
                                "is": [ "eq", "cited" ]
                              },
                              {
                                "field": "page_status",
                                "is": [ "eq", "found_but_not_cited" ]
                              }
                            ]
                          }
                        ]
                      }
                    ]
                  },
                  "volume_range": {
                    "properties": {
                      "from": { "type": "integer", "minimum": 0 },
                      "to": { "type": "integer", "minimum": 0 }
                    },
                    "type": "object",
                    "description": "The volume range to filter by."
                  },
                  "changes": {
                    "properties": {
                      "prompt": {
                        "items": {
                          "type": "string",
                          "enum": [ "new", "lost", "no_change" ]
                        },
                        "type": "array",
                        "description": "Keep prompts that were answered on only one of the two dates (`new`, `lost`) or on both (`no_change`)."
                      },
                      "mentions": {
                        "items": {
                          "type": "string",
                          "enum": [ "new", "lost", "no_change" ]
                        },
                        "type": "array",
                        "description": "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."
                      },
                      "citations": {
                        "items": {
                          "type": "string",
                          "enum": [ "new", "lost", "no_change" ]
                        },
                        "type": "array",
                        "description": "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."
                      }
                    },
                    "type": "object",
                    "description": "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."
                  },
                  "sentiment_filter": {
                    "properties": {},
                    "type": "object",
                    "description": "A filter on how the responses talk about your brands and competitors, like the Sentiment filter in Brand Radar. Uses [filter syntax](https://docs.ahrefs.com/api/docs/filter-syntax) with three fields:\n- `brand` (required): a name from `brands` or `competitors`, with `\"eq\"`.\n- `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.\n- `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`.\nEach 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`.",
                    "examples": [
                      {
                        "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" ]
                              }
                            ]
                          }
                        ]
                      }
                    ]
                  },
                  "opinions_first": {
                    "type": "boolean",
                    "description": "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`.",
                    "default": false
                  },
                  "output": {
                    "type": "string",
                    "enum": [ "json", "php" ],
                    "description": "The output format."
                  }
                },
                "type": "object",
                "required": [ "select", "data_source" ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ai-responses" }
              },
              "application/xml": {
                "schema": { "$ref": "#/components/schemas/ai-responses" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      }
    },
    "/impressions-overview": {
      "get": {
        "tags": [ "Overview", "MCP" ],
        "summary": "Impressions",
        "description": ">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.",
        "operationId": "impressions-overview",
        "parameters": [
          {
            "description": "A comma-separated list of fields to return.\n\n- `brand`\n- `entity_type`\n- `no_tracked_brands`\n- `only_competitors_brands`\n- `only_target_brand`\n- `target_and_competitors_brands`\n- `total`",
            "required": true,
            "explode": false,
            "schema": { "type": "string" },
            "name": "select",
            "in": "query"
          },
          {
            "description": "The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter).\n\n**cited_domain**: The domain of a page that was used to generate the response.  \ntype: domain\n\n**cited_domain_subdomains**: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match.  \ntype: string\n\n**cited_url_exact**: The URL of a page that was used to generate the response.  \ntype: string\n\n**cited_url_prefix**: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match.  \ntype: string\n\n**inline_domain**: The domain of a page linked in the response text.  \ntype: domain\n\n**inline_domain_subdomains**: The domain of a page linked in the response text. Any subdomain of the given domain will also match.  \ntype: string\n\n**inline_url_exact**: The URL of a page linked in the response text.  \ntype: string\n\n**inline_url_prefix**: The URL of a page linked in the response text. Any URL that starts with this prefix will match.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**sponsored_advertiser**: The advertiser name shown on a sponsored result.  \ntype: string\n\n**sponsored_description**: The description of a sponsored result.  \ntype: string\n\n**sponsored_domain**: The domain of a sponsored result.  \ntype: domain\n\n**sponsored_domain_subdomains**: The domain of a sponsored result, including any of its subdomains.  \ntype: string\n\n**sponsored_kind**: The sponsored result type. Allowed values: `ad`, `product`.  \ntype: string\n\n**sponsored_result**: Whether the response contains a sponsored result. This field only supports the `empty` operator and its negation.  \ntype: string\n\n**sponsored_title**: The title of a sponsored result.  \ntype: string\n\n**sponsored_url_exact**: The exact URL of a sponsored result.  \ntype: string\n\n**sponsored_url_prefix**: The URL prefix of a sponsored result.  \ntype: string\n\n**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.  \ntype: string",
            "required": false,
            "explode": false,
            "schema": { "type": "string" },
            "name": "where",
            "in": "query"
          },
          {
            "description": "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#/...`",
            "required": false,
            "explode": false,
            "schema": { "type": "string" },
            "name": "report_id",
            "in": "query"
          },
          {
            "description": "A comma-separated list of brands to search for. At least one of brand, competitors, market or where should not be empty.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "default": "" },
            "name": "brand",
            "in": "query"
          },
          {
            "description": "A comma-separated list of competitors of your brands.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "default": "" },
            "name": "competitors",
            "in": "query"
          },
          {
            "description": "A comma-separated list of chatbot models. All models can be combined with each other. `claude` module supports only custom prompts.\nThe `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.",
            "required": true,
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "chatgpt", "google_ai_overviews", "google_ai_mode", "gemini",
                "perplexity", "copilot", "claude", "grok",
                "google_ai_overviews_keywords", "google_ai_mode_keywords"
              ],
              "examples": [ "chatgpt,perplexity" ]
            },
            "name": "data_source",
            "in": "query"
          },
          {
            "description": "A comma-separated list of two-letter country codes (ISO 3166-1 alpha-2).",
            "required": false,
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar", "as",
                "at", "au", "aw", "az", "ba", "bb", "bd", "be", "bf", "bg",
                "bh", "bi", "bj", "bn", "bo", "br", "bs", "bt", "bw", "by",
                "bz", "ca", "cd", "cf", "cg", "ch", "ci", "ck", "cl", "cm",
                "cn", "co", "cr", "cu", "cv", "cy", "cz", "de", "dj", "dk",
                "dm", "do", "dz", "ec", "ee", "eg", "es", "et", "fi", "fj",
                "fm", "fo", "fr", "ga", "gb", "gd", "ge", "gf", "gg", "gh",
                "gi", "gl", "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gy",
                "hk", "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in",
                "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg", "kh",
                "ki", "kn", "kr", "kw", "ky", "kz", "la", "lb", "lc", "li",
                "lk", "ls", "lt", "lu", "lv", "ly", "ma", "mc", "md", "me",
                "mg", "mk", "ml", "mm", "mn", "mq", "mr", "ms", "mt", "mu",
                "mv", "mw", "mx", "my", "mz", "na", "nc", "ne", "ng", "ni",
                "nl", "no", "np", "nr", "nu", "nz", "om", "pa", "pe", "pf",
                "pg", "ph", "pk", "pl", "pn", "pr", "ps", "pt", "py", "qa",
                "re", "ro", "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg",
                "sh", "si", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv",
                "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to", "tr",
                "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz", "vc", "ve",
                "vg", "vi", "vn", "vu", "ws", "ye", "yt", "za", "zm", "zw"
              ],
              "default": ""
            },
            "name": "country",
            "in": "query"
          },
          {
            "description": "The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "enum": [ "ahrefs", "custom" ] },
            "name": "prompts",
            "in": "query"
          },
          { "$ref": "#/components/parameters/output" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/impressions-overview"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/impressions-overview"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      },
      "post": {
        "tags": [ "Overview", "MCP" ],
        "summary": "Impressions",
        "description": ">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.",
        "operationId": "impressions-overview",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "select": {
                    "items": { "type": "string" },
                    "type": "array",
                    "description": "A list of fields to return.\n\n- `brand`\n- `entity_type`\n- `no_tracked_brands`\n- `only_competitors_brands`\n- `only_target_brand`\n- `target_and_competitors_brands`\n- `total`",
                    "examples": [ [ "field_a", "field_b" ] ]
                  },
                  "where": {
                    "type": "object",
                    "description": "The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter).\n\n**cited_domain**: The domain of a page that was used to generate the response.  \ntype: domain\n\n**cited_domain_subdomains**: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match.  \ntype: string\n\n**cited_url_exact**: The URL of a page that was used to generate the response.  \ntype: string\n\n**cited_url_prefix**: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match.  \ntype: string\n\n**inline_domain**: The domain of a page linked in the response text.  \ntype: domain\n\n**inline_domain_subdomains**: The domain of a page linked in the response text. Any subdomain of the given domain will also match.  \ntype: string\n\n**inline_url_exact**: The URL of a page linked in the response text.  \ntype: string\n\n**inline_url_prefix**: The URL of a page linked in the response text. Any URL that starts with this prefix will match.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**sponsored_advertiser**: The advertiser name shown on a sponsored result.  \ntype: string\n\n**sponsored_description**: The description of a sponsored result.  \ntype: string\n\n**sponsored_domain**: The domain of a sponsored result.  \ntype: domain\n\n**sponsored_domain_subdomains**: The domain of a sponsored result, including any of its subdomains.  \ntype: string\n\n**sponsored_kind**: The sponsored result type. Allowed values: `ad`, `product`.  \ntype: string\n\n**sponsored_result**: Whether the response contains a sponsored result. This field only supports the `empty` operator and its negation.  \ntype: string\n\n**sponsored_title**: The title of a sponsored result.  \ntype: string\n\n**sponsored_url_exact**: The exact URL of a sponsored result.  \ntype: string\n\n**sponsored_url_prefix**: The URL prefix of a sponsored result.  \ntype: string\n\n**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.  \ntype: string"
                  },
                  "report_id": {
                    "type": "string",
                    "description": "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#/...`"
                  },
                  "brands": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of brand names and websites to search for.",
                    "default": []
                  },
                  "competitors": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of competitor names and websites to search for.",
                    "default": []
                  },
                  "content_filter": {
                    "properties": {
                      "include": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Only show results containing at least one of these exact phrases."
                      },
                      "exclude": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Hide results containing any of these exact phrases."
                      }
                    },
                    "type": "object",
                    "description": "Optional phrases used to include or exclude results based on their content."
                  },
                  "data_source": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "chatgpt", "google_ai_overviews", "google_ai_mode",
                        "gemini", "perplexity", "copilot", "claude", "grok",
                        "google_ai_overviews_keywords",
                        "google_ai_mode_keywords"
                      ]
                    },
                    "type": "array",
                    "description": "A list of chatbot models. All models can be combined with each other. `claude` module supports only custom prompts.\nThe `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."
                  },
                  "country": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar",
                        "as", "at", "au", "aw", "az", "ba", "bb", "bd", "be",
                        "bf", "bg", "bh", "bi", "bj", "bn", "bo", "br", "bs",
                        "bt", "bw", "by", "bz", "ca", "cd", "cf", "cg", "ch",
                        "ci", "ck", "cl", "cm", "cn", "co", "cr", "cu", "cv",
                        "cy", "cz", "de", "dj", "dk", "dm", "do", "dz", "ec",
                        "ee", "eg", "es", "et", "fi", "fj", "fm", "fo", "fr",
                        "ga", "gb", "gd", "ge", "gf", "gg", "gh", "gi", "gl",
                        "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gy", "hk",
                        "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in",
                        "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg",
                        "kh", "ki", "kn", "kr", "kw", "ky", "kz", "la", "lb",
                        "lc", "li", "lk", "ls", "lt", "lu", "lv", "ly", "ma",
                        "mc", "md", "me", "mg", "mk", "ml", "mm", "mn", "mq",
                        "mr", "ms", "mt", "mu", "mv", "mw", "mx", "my", "mz",
                        "na", "nc", "ne", "ng", "ni", "nl", "no", "np", "nr",
                        "nu", "nz", "om", "pa", "pe", "pf", "pg", "ph", "pk",
                        "pl", "pn", "pr", "ps", "pt", "py", "qa", "re", "ro",
                        "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg", "sh",
                        "si", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv",
                        "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to",
                        "tr", "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz",
                        "vc", "ve", "vg", "vi", "vn", "vu", "ws", "ye", "yt",
                        "za", "zm", "zw"
                      ]
                    },
                    "type": "array",
                    "description": "A list of two-letter country codes (ISO 3166-1 alpha-2).",
                    "default": []
                  },
                  "prompts": {
                    "type": "string",
                    "enum": [ "ahrefs", "custom" ],
                    "description": "The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided."
                  },
                  "tags_filter": {
                    "properties": {},
                    "type": "object",
                    "description": "A filter expression for prompt tags. Requires `report_id`. Uses [filter syntax](https://docs.ahrefs.com/api/docs/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.",
                    "examples": [
                      {
                        "or": [
                          { "field": "tag", "is": [ "eq", "branded" ] },
                          { "field": "tag", "is": [ "eq", "competitor" ] }
                        ]
                      }
                    ]
                  },
                  "output": {
                    "type": "string",
                    "enum": [ "json", "csv", "xml", "php" ],
                    "description": "The output format."
                  }
                },
                "type": "object",
                "required": [ "select", "data_source" ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/impressions-overview"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/impressions-overview"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      }
    },
    "/citations-overview": {
      "post": {
        "tags": [ "Overview", "MCP" ],
        "summary": "Citations",
        "description": ">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.\n\nEvery 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.",
        "operationId": "citations-overview",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "select": {
                    "items": { "type": "string" },
                    "type": "array",
                    "description": "A list of fields to return.\n\n- `brand`\n- `entity_type`\n- `no_tracked_brands`\n- `only_competitors_brands`\n- `only_target_brand`\n- `target_and_competitors_brands`\n- `total`",
                    "examples": [ [ "field_a", "field_b" ] ]
                  },
                  "where": {
                    "type": "object",
                    "description": "The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter).\n\n**cited_domain**: The domain of a page that was used to generate the response.  \ntype: domain\n\n**cited_domain_subdomains**: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match.  \ntype: string\n\n**cited_url_exact**: The URL of a page that was used to generate the response.  \ntype: string\n\n**cited_url_prefix**: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match.  \ntype: string\n\n**inline_domain**: The domain of a page linked in the response text.  \ntype: domain\n\n**inline_domain_subdomains**: The domain of a page linked in the response text. Any subdomain of the given domain will also match.  \ntype: string\n\n**inline_url_exact**: The URL of a page linked in the response text.  \ntype: string\n\n**inline_url_prefix**: The URL of a page linked in the response text. Any URL that starts with this prefix will match.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**sponsored_advertiser**: The advertiser name shown on a sponsored result.  \ntype: string\n\n**sponsored_description**: The description of a sponsored result.  \ntype: string\n\n**sponsored_domain**: The domain of a sponsored result.  \ntype: domain\n\n**sponsored_domain_subdomains**: The domain of a sponsored result, including any of its subdomains.  \ntype: string\n\n**sponsored_kind**: The sponsored result type. Allowed values: `ad`, `product`.  \ntype: string\n\n**sponsored_result**: Whether the response contains a sponsored result. This field only supports the `empty` operator and its negation.  \ntype: string\n\n**sponsored_title**: The title of a sponsored result.  \ntype: string\n\n**sponsored_url_exact**: The exact URL of a sponsored result.  \ntype: string\n\n**sponsored_url_prefix**: The URL prefix of a sponsored result.  \ntype: string\n\n**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.  \ntype: string"
                  },
                  "report_id": {
                    "type": "string",
                    "description": "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#/...`"
                  },
                  "brands": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of brand names and websites to search for.",
                    "default": []
                  },
                  "competitors": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of competitor names and websites to search for.",
                    "default": []
                  },
                  "content_filter": {
                    "properties": {
                      "include": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Only show results containing at least one of these exact phrases."
                      },
                      "exclude": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Hide results containing any of these exact phrases."
                      }
                    },
                    "type": "object",
                    "description": "Optional phrases used to include or exclude results based on their content."
                  },
                  "data_source": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "chatgpt", "google_ai_overviews", "google_ai_mode",
                        "gemini", "perplexity", "copilot", "claude", "grok",
                        "google_ai_overviews_keywords",
                        "google_ai_mode_keywords"
                      ]
                    },
                    "type": "array",
                    "description": "A list of chatbot models. All models can be combined with each other. `claude` module supports only custom prompts.\nThe `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."
                  },
                  "country": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar",
                        "as", "at", "au", "aw", "az", "ba", "bb", "bd", "be",
                        "bf", "bg", "bh", "bi", "bj", "bn", "bo", "br", "bs",
                        "bt", "bw", "by", "bz", "ca", "cd", "cf", "cg", "ch",
                        "ci", "ck", "cl", "cm", "cn", "co", "cr", "cu", "cv",
                        "cy", "cz", "de", "dj", "dk", "dm", "do", "dz", "ec",
                        "ee", "eg", "es", "et", "fi", "fj", "fm", "fo", "fr",
                        "ga", "gb", "gd", "ge", "gf", "gg", "gh", "gi", "gl",
                        "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gy", "hk",
                        "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in",
                        "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg",
                        "kh", "ki", "kn", "kr", "kw", "ky", "kz", "la", "lb",
                        "lc", "li", "lk", "ls", "lt", "lu", "lv", "ly", "ma",
                        "mc", "md", "me", "mg", "mk", "ml", "mm", "mn", "mq",
                        "mr", "ms", "mt", "mu", "mv", "mw", "mx", "my", "mz",
                        "na", "nc", "ne", "ng", "ni", "nl", "no", "np", "nr",
                        "nu", "nz", "om", "pa", "pe", "pf", "pg", "ph", "pk",
                        "pl", "pn", "pr", "ps", "pt", "py", "qa", "re", "ro",
                        "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg", "sh",
                        "si", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv",
                        "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to",
                        "tr", "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz",
                        "vc", "ve", "vg", "vi", "vn", "vu", "ws", "ye", "yt",
                        "za", "zm", "zw"
                      ]
                    },
                    "type": "array",
                    "description": "A list of two-letter country codes (ISO 3166-1 alpha-2).",
                    "default": []
                  },
                  "prompts": {
                    "type": "string",
                    "enum": [ "ahrefs", "custom" ],
                    "description": "The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided."
                  },
                  "tags_filter": {
                    "properties": {},
                    "type": "object",
                    "description": "A filter expression for prompt tags. Requires `report_id`. Uses [filter syntax](https://docs.ahrefs.com/api/docs/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.",
                    "examples": [
                      {
                        "or": [
                          { "field": "tag", "is": [ "eq", "branded" ] },
                          { "field": "tag", "is": [ "eq", "competitor" ] }
                        ]
                      }
                    ]
                  },
                  "output": {
                    "type": "string",
                    "enum": [ "json", "csv", "xml", "php" ],
                    "description": "The output format."
                  }
                },
                "type": "object",
                "required": [ "select", "data_source" ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/citations-overview"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/citations-overview"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      }
    },
    "/mentions-overview": {
      "get": {
        "tags": [ "Overview", "MCP" ],
        "summary": "Mentions",
        "description": ">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.",
        "operationId": "mentions-overview",
        "parameters": [
          {
            "description": "A comma-separated list of fields to return.\n\n- `brand`\n- `entity_type`\n- `no_tracked_brands`\n- `only_competitors_brands`\n- `only_target_brand`\n- `target_and_competitors_brands`\n- `total`",
            "required": true,
            "explode": false,
            "schema": { "type": "string" },
            "name": "select",
            "in": "query"
          },
          {
            "description": "The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter).\n\n**cited_domain**: The domain of a page that was used to generate the response.  \ntype: domain\n\n**cited_domain_subdomains**: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match.  \ntype: string\n\n**cited_url_exact**: The URL of a page that was used to generate the response.  \ntype: string\n\n**cited_url_prefix**: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match.  \ntype: string\n\n**inline_domain**: The domain of a page linked in the response text.  \ntype: domain\n\n**inline_domain_subdomains**: The domain of a page linked in the response text. Any subdomain of the given domain will also match.  \ntype: string\n\n**inline_url_exact**: The URL of a page linked in the response text.  \ntype: string\n\n**inline_url_prefix**: The URL of a page linked in the response text. Any URL that starts with this prefix will match.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**sponsored_advertiser**: The advertiser name shown on a sponsored result.  \ntype: string\n\n**sponsored_description**: The description of a sponsored result.  \ntype: string\n\n**sponsored_domain**: The domain of a sponsored result.  \ntype: domain\n\n**sponsored_domain_subdomains**: The domain of a sponsored result, including any of its subdomains.  \ntype: string\n\n**sponsored_kind**: The sponsored result type. Allowed values: `ad`, `product`.  \ntype: string\n\n**sponsored_result**: Whether the response contains a sponsored result. This field only supports the `empty` operator and its negation.  \ntype: string\n\n**sponsored_title**: The title of a sponsored result.  \ntype: string\n\n**sponsored_url_exact**: The exact URL of a sponsored result.  \ntype: string\n\n**sponsored_url_prefix**: The URL prefix of a sponsored result.  \ntype: string\n\n**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.  \ntype: string",
            "required": false,
            "explode": false,
            "schema": { "type": "string" },
            "name": "where",
            "in": "query"
          },
          {
            "description": "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#/...`",
            "required": false,
            "explode": false,
            "schema": { "type": "string" },
            "name": "report_id",
            "in": "query"
          },
          {
            "description": "A comma-separated list of brands to search for. At least one of brand, competitors, market or where should not be empty.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "default": "" },
            "name": "brand",
            "in": "query"
          },
          {
            "description": "A comma-separated list of competitors of your brands.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "default": "" },
            "name": "competitors",
            "in": "query"
          },
          {
            "description": "A comma-separated list of chatbot models. All models can be combined with each other. `claude` module supports only custom prompts.\nThe `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.",
            "required": true,
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "chatgpt", "google_ai_overviews", "google_ai_mode", "gemini",
                "perplexity", "copilot", "claude", "grok",
                "google_ai_overviews_keywords", "google_ai_mode_keywords"
              ],
              "examples": [ "chatgpt,perplexity" ]
            },
            "name": "data_source",
            "in": "query"
          },
          {
            "description": "A comma-separated list of two-letter country codes (ISO 3166-1 alpha-2).",
            "required": false,
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar", "as",
                "at", "au", "aw", "az", "ba", "bb", "bd", "be", "bf", "bg",
                "bh", "bi", "bj", "bn", "bo", "br", "bs", "bt", "bw", "by",
                "bz", "ca", "cd", "cf", "cg", "ch", "ci", "ck", "cl", "cm",
                "cn", "co", "cr", "cu", "cv", "cy", "cz", "de", "dj", "dk",
                "dm", "do", "dz", "ec", "ee", "eg", "es", "et", "fi", "fj",
                "fm", "fo", "fr", "ga", "gb", "gd", "ge", "gf", "gg", "gh",
                "gi", "gl", "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gy",
                "hk", "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in",
                "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg", "kh",
                "ki", "kn", "kr", "kw", "ky", "kz", "la", "lb", "lc", "li",
                "lk", "ls", "lt", "lu", "lv", "ly", "ma", "mc", "md", "me",
                "mg", "mk", "ml", "mm", "mn", "mq", "mr", "ms", "mt", "mu",
                "mv", "mw", "mx", "my", "mz", "na", "nc", "ne", "ng", "ni",
                "nl", "no", "np", "nr", "nu", "nz", "om", "pa", "pe", "pf",
                "pg", "ph", "pk", "pl", "pn", "pr", "ps", "pt", "py", "qa",
                "re", "ro", "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg",
                "sh", "si", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv",
                "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to", "tr",
                "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz", "vc", "ve",
                "vg", "vi", "vn", "vu", "ws", "ye", "yt", "za", "zm", "zw"
              ],
              "default": ""
            },
            "name": "country",
            "in": "query"
          },
          {
            "description": "The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "enum": [ "ahrefs", "custom" ] },
            "name": "prompts",
            "in": "query"
          },
          { "$ref": "#/components/parameters/output" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/mentions-overview"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/mentions-overview"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      },
      "post": {
        "tags": [ "Overview", "MCP" ],
        "summary": "Mentions",
        "description": ">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.\n\nEvery entity provided in `brands` (and `competitors`, when applicable) must include at least one value in `names`. Entities consisting only of `url_groups` are not supported here because mentions are matched against brand names.",
        "operationId": "mentions-overview",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "select": {
                    "items": { "type": "string" },
                    "type": "array",
                    "description": "A list of fields to return.\n\n- `brand`\n- `entity_type`\n- `no_tracked_brands`\n- `only_competitors_brands`\n- `only_target_brand`\n- `target_and_competitors_brands`\n- `total`",
                    "examples": [ [ "field_a", "field_b" ] ]
                  },
                  "where": {
                    "type": "object",
                    "description": "The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter).\n\n**cited_domain**: The domain of a page that was used to generate the response.  \ntype: domain\n\n**cited_domain_subdomains**: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match.  \ntype: string\n\n**cited_url_exact**: The URL of a page that was used to generate the response.  \ntype: string\n\n**cited_url_prefix**: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match.  \ntype: string\n\n**inline_domain**: The domain of a page linked in the response text.  \ntype: domain\n\n**inline_domain_subdomains**: The domain of a page linked in the response text. Any subdomain of the given domain will also match.  \ntype: string\n\n**inline_url_exact**: The URL of a page linked in the response text.  \ntype: string\n\n**inline_url_prefix**: The URL of a page linked in the response text. Any URL that starts with this prefix will match.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**sponsored_advertiser**: The advertiser name shown on a sponsored result.  \ntype: string\n\n**sponsored_description**: The description of a sponsored result.  \ntype: string\n\n**sponsored_domain**: The domain of a sponsored result.  \ntype: domain\n\n**sponsored_domain_subdomains**: The domain of a sponsored result, including any of its subdomains.  \ntype: string\n\n**sponsored_kind**: The sponsored result type. Allowed values: `ad`, `product`.  \ntype: string\n\n**sponsored_result**: Whether the response contains a sponsored result. This field only supports the `empty` operator and its negation.  \ntype: string\n\n**sponsored_title**: The title of a sponsored result.  \ntype: string\n\n**sponsored_url_exact**: The exact URL of a sponsored result.  \ntype: string\n\n**sponsored_url_prefix**: The URL prefix of a sponsored result.  \ntype: string\n\n**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.  \ntype: string"
                  },
                  "report_id": {
                    "type": "string",
                    "description": "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#/...`"
                  },
                  "brands": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of brand names and websites to search for.",
                    "default": []
                  },
                  "competitors": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of competitor names and websites to search for.",
                    "default": []
                  },
                  "content_filter": {
                    "properties": {
                      "include": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Only show results containing at least one of these exact phrases."
                      },
                      "exclude": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Hide results containing any of these exact phrases."
                      }
                    },
                    "type": "object",
                    "description": "Optional phrases used to include or exclude results based on their content."
                  },
                  "data_source": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "chatgpt", "google_ai_overviews", "google_ai_mode",
                        "gemini", "perplexity", "copilot", "claude", "grok",
                        "google_ai_overviews_keywords",
                        "google_ai_mode_keywords"
                      ]
                    },
                    "type": "array",
                    "description": "A list of chatbot models. All models can be combined with each other. `claude` module supports only custom prompts.\nThe `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."
                  },
                  "country": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar",
                        "as", "at", "au", "aw", "az", "ba", "bb", "bd", "be",
                        "bf", "bg", "bh", "bi", "bj", "bn", "bo", "br", "bs",
                        "bt", "bw", "by", "bz", "ca", "cd", "cf", "cg", "ch",
                        "ci", "ck", "cl", "cm", "cn", "co", "cr", "cu", "cv",
                        "cy", "cz", "de", "dj", "dk", "dm", "do", "dz", "ec",
                        "ee", "eg", "es", "et", "fi", "fj", "fm", "fo", "fr",
                        "ga", "gb", "gd", "ge", "gf", "gg", "gh", "gi", "gl",
                        "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gy", "hk",
                        "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in",
                        "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg",
                        "kh", "ki", "kn", "kr", "kw", "ky", "kz", "la", "lb",
                        "lc", "li", "lk", "ls", "lt", "lu", "lv", "ly", "ma",
                        "mc", "md", "me", "mg", "mk", "ml", "mm", "mn", "mq",
                        "mr", "ms", "mt", "mu", "mv", "mw", "mx", "my", "mz",
                        "na", "nc", "ne", "ng", "ni", "nl", "no", "np", "nr",
                        "nu", "nz", "om", "pa", "pe", "pf", "pg", "ph", "pk",
                        "pl", "pn", "pr", "ps", "pt", "py", "qa", "re", "ro",
                        "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg", "sh",
                        "si", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv",
                        "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to",
                        "tr", "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz",
                        "vc", "ve", "vg", "vi", "vn", "vu", "ws", "ye", "yt",
                        "za", "zm", "zw"
                      ]
                    },
                    "type": "array",
                    "description": "A list of two-letter country codes (ISO 3166-1 alpha-2).",
                    "default": []
                  },
                  "prompts": {
                    "type": "string",
                    "enum": [ "ahrefs", "custom" ],
                    "description": "The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided."
                  },
                  "tags_filter": {
                    "properties": {},
                    "type": "object",
                    "description": "A filter expression for prompt tags. Requires `report_id`. Uses [filter syntax](https://docs.ahrefs.com/api/docs/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.",
                    "examples": [
                      {
                        "or": [
                          { "field": "tag", "is": [ "eq", "branded" ] },
                          { "field": "tag", "is": [ "eq", "competitor" ] }
                        ]
                      }
                    ]
                  },
                  "output": {
                    "type": "string",
                    "enum": [ "json", "csv", "xml", "php" ],
                    "description": "The output format."
                  }
                },
                "type": "object",
                "required": [ "select", "data_source" ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/mentions-overview"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/mentions-overview"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      }
    },
    "/sov-overview": {
      "get": {
        "tags": [ "Overview", "MCP" ],
        "summary": "Share of Voice",
        "description": ">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.",
        "operationId": "sov-overview",
        "parameters": [
          {
            "description": "The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter).\n\n**cited_domain**: The domain of a page that was used to generate the response.  \ntype: domain\n\n**cited_domain_subdomains**: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match.  \ntype: string\n\n**cited_url_exact**: The URL of a page that was used to generate the response.  \ntype: string\n\n**cited_url_prefix**: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match.  \ntype: string\n\n**inline_domain**: The domain of a page linked in the response text.  \ntype: domain\n\n**inline_domain_subdomains**: The domain of a page linked in the response text. Any subdomain of the given domain will also match.  \ntype: string\n\n**inline_url_exact**: The URL of a page linked in the response text.  \ntype: string\n\n**inline_url_prefix**: The URL of a page linked in the response text. Any URL that starts with this prefix will match.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**sponsored_advertiser**: The advertiser name shown on a sponsored result.  \ntype: string\n\n**sponsored_description**: The description of a sponsored result.  \ntype: string\n\n**sponsored_domain**: The domain of a sponsored result.  \ntype: domain\n\n**sponsored_domain_subdomains**: The domain of a sponsored result, including any of its subdomains.  \ntype: string\n\n**sponsored_kind**: The sponsored result type. Allowed values: `ad`, `product`.  \ntype: string\n\n**sponsored_result**: Whether the response contains a sponsored result. This field only supports the `empty` operator and its negation.  \ntype: string\n\n**sponsored_title**: The title of a sponsored result.  \ntype: string\n\n**sponsored_url_exact**: The exact URL of a sponsored result.  \ntype: string\n\n**sponsored_url_prefix**: The URL prefix of a sponsored result.  \ntype: string\n\n**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.  \ntype: string",
            "required": false,
            "explode": false,
            "schema": { "type": "string" },
            "name": "where",
            "in": "query"
          },
          {
            "description": "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#/...`",
            "required": false,
            "explode": false,
            "schema": { "type": "string" },
            "name": "report_id",
            "in": "query"
          },
          {
            "description": "A comma-separated list of brands to search for. At least one of brand, competitors, market or where should not be empty.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "default": "" },
            "name": "brand",
            "in": "query"
          },
          {
            "description": "A comma-separated list of competitors of your brands.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "default": "" },
            "name": "competitors",
            "in": "query"
          },
          {
            "description": "A comma-separated list of chatbot models. All models can be combined with each other. `claude` module supports only custom prompts.\nThe `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.",
            "required": true,
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "chatgpt", "google_ai_overviews", "google_ai_mode", "gemini",
                "perplexity", "copilot", "claude", "grok",
                "google_ai_overviews_keywords", "google_ai_mode_keywords"
              ],
              "examples": [ "chatgpt,perplexity" ]
            },
            "name": "data_source",
            "in": "query"
          },
          {
            "description": "A comma-separated list of two-letter country codes (ISO 3166-1 alpha-2).",
            "required": false,
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar", "as",
                "at", "au", "aw", "az", "ba", "bb", "bd", "be", "bf", "bg",
                "bh", "bi", "bj", "bn", "bo", "br", "bs", "bt", "bw", "by",
                "bz", "ca", "cd", "cf", "cg", "ch", "ci", "ck", "cl", "cm",
                "cn", "co", "cr", "cu", "cv", "cy", "cz", "de", "dj", "dk",
                "dm", "do", "dz", "ec", "ee", "eg", "es", "et", "fi", "fj",
                "fm", "fo", "fr", "ga", "gb", "gd", "ge", "gf", "gg", "gh",
                "gi", "gl", "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gy",
                "hk", "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in",
                "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg", "kh",
                "ki", "kn", "kr", "kw", "ky", "kz", "la", "lb", "lc", "li",
                "lk", "ls", "lt", "lu", "lv", "ly", "ma", "mc", "md", "me",
                "mg", "mk", "ml", "mm", "mn", "mq", "mr", "ms", "mt", "mu",
                "mv", "mw", "mx", "my", "mz", "na", "nc", "ne", "ng", "ni",
                "nl", "no", "np", "nr", "nu", "nz", "om", "pa", "pe", "pf",
                "pg", "ph", "pk", "pl", "pn", "pr", "ps", "pt", "py", "qa",
                "re", "ro", "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg",
                "sh", "si", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv",
                "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to", "tr",
                "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz", "vc", "ve",
                "vg", "vi", "vn", "vu", "ws", "ye", "yt", "za", "zm", "zw"
              ],
              "default": ""
            },
            "name": "country",
            "in": "query"
          },
          {
            "description": "The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "enum": [ "ahrefs", "custom" ] },
            "name": "prompts",
            "in": "query"
          },
          { "$ref": "#/components/parameters/output" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/sov-overview" }
              },
              "application/xml": {
                "schema": { "$ref": "#/components/schemas/sov-overview" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      },
      "post": {
        "tags": [ "Overview", "MCP" ],
        "summary": "Share of Voice",
        "description": ">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.",
        "operationId": "sov-overview",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "where": {
                    "type": "object",
                    "description": "The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter).\n\n**cited_domain**: The domain of a page that was used to generate the response.  \ntype: domain\n\n**cited_domain_subdomains**: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match.  \ntype: string\n\n**cited_url_exact**: The URL of a page that was used to generate the response.  \ntype: string\n\n**cited_url_prefix**: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match.  \ntype: string\n\n**inline_domain**: The domain of a page linked in the response text.  \ntype: domain\n\n**inline_domain_subdomains**: The domain of a page linked in the response text. Any subdomain of the given domain will also match.  \ntype: string\n\n**inline_url_exact**: The URL of a page linked in the response text.  \ntype: string\n\n**inline_url_prefix**: The URL of a page linked in the response text. Any URL that starts with this prefix will match.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**sponsored_advertiser**: The advertiser name shown on a sponsored result.  \ntype: string\n\n**sponsored_description**: The description of a sponsored result.  \ntype: string\n\n**sponsored_domain**: The domain of a sponsored result.  \ntype: domain\n\n**sponsored_domain_subdomains**: The domain of a sponsored result, including any of its subdomains.  \ntype: string\n\n**sponsored_kind**: The sponsored result type. Allowed values: `ad`, `product`.  \ntype: string\n\n**sponsored_result**: Whether the response contains a sponsored result. This field only supports the `empty` operator and its negation.  \ntype: string\n\n**sponsored_title**: The title of a sponsored result.  \ntype: string\n\n**sponsored_url_exact**: The exact URL of a sponsored result.  \ntype: string\n\n**sponsored_url_prefix**: The URL prefix of a sponsored result.  \ntype: string\n\n**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.  \ntype: string"
                  },
                  "report_id": {
                    "type": "string",
                    "description": "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#/...`"
                  },
                  "brands": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of brand names and websites to search for.",
                    "default": []
                  },
                  "competitors": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of competitor names and websites to search for.",
                    "default": []
                  },
                  "content_filter": {
                    "properties": {
                      "include": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Only show results containing at least one of these exact phrases."
                      },
                      "exclude": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Hide results containing any of these exact phrases."
                      }
                    },
                    "type": "object",
                    "description": "Optional phrases used to include or exclude results based on their content."
                  },
                  "data_source": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "chatgpt", "google_ai_overviews", "google_ai_mode",
                        "gemini", "perplexity", "copilot", "claude", "grok",
                        "google_ai_overviews_keywords",
                        "google_ai_mode_keywords"
                      ]
                    },
                    "type": "array",
                    "description": "A list of chatbot models. All models can be combined with each other. `claude` module supports only custom prompts.\nThe `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."
                  },
                  "country": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar",
                        "as", "at", "au", "aw", "az", "ba", "bb", "bd", "be",
                        "bf", "bg", "bh", "bi", "bj", "bn", "bo", "br", "bs",
                        "bt", "bw", "by", "bz", "ca", "cd", "cf", "cg", "ch",
                        "ci", "ck", "cl", "cm", "cn", "co", "cr", "cu", "cv",
                        "cy", "cz", "de", "dj", "dk", "dm", "do", "dz", "ec",
                        "ee", "eg", "es", "et", "fi", "fj", "fm", "fo", "fr",
                        "ga", "gb", "gd", "ge", "gf", "gg", "gh", "gi", "gl",
                        "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gy", "hk",
                        "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in",
                        "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg",
                        "kh", "ki", "kn", "kr", "kw", "ky", "kz", "la", "lb",
                        "lc", "li", "lk", "ls", "lt", "lu", "lv", "ly", "ma",
                        "mc", "md", "me", "mg", "mk", "ml", "mm", "mn", "mq",
                        "mr", "ms", "mt", "mu", "mv", "mw", "mx", "my", "mz",
                        "na", "nc", "ne", "ng", "ni", "nl", "no", "np", "nr",
                        "nu", "nz", "om", "pa", "pe", "pf", "pg", "ph", "pk",
                        "pl", "pn", "pr", "ps", "pt", "py", "qa", "re", "ro",
                        "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg", "sh",
                        "si", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv",
                        "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to",
                        "tr", "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz",
                        "vc", "ve", "vg", "vi", "vn", "vu", "ws", "ye", "yt",
                        "za", "zm", "zw"
                      ]
                    },
                    "type": "array",
                    "description": "A list of two-letter country codes (ISO 3166-1 alpha-2).",
                    "default": []
                  },
                  "prompts": {
                    "type": "string",
                    "enum": [ "ahrefs", "custom" ],
                    "description": "The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided."
                  },
                  "tags_filter": {
                    "properties": {},
                    "type": "object",
                    "description": "A filter expression for prompt tags. Requires `report_id`. Uses [filter syntax](https://docs.ahrefs.com/api/docs/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.",
                    "examples": [
                      {
                        "or": [
                          { "field": "tag", "is": [ "eq", "branded" ] },
                          { "field": "tag", "is": [ "eq", "competitor" ] }
                        ]
                      }
                    ]
                  },
                  "output": {
                    "type": "string",
                    "enum": [ "json", "csv", "xml", "php" ],
                    "description": "The output format."
                  }
                },
                "type": "object",
                "required": [ "data_source" ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/sov-overview" }
              },
              "application/xml": {
                "schema": { "$ref": "#/components/schemas/sov-overview" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      }
    },
    "/impressions-history": {
      "get": {
        "tags": [ "Overview history", "MCP" ],
        "summary": "Impressions",
        "description": ">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.",
        "operationId": "impressions-history",
        "parameters": [
          {
            "description": "The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter).\n\n**cited_domain**: The domain of a page that was used to generate the response.  \ntype: domain\n\n**cited_domain_subdomains**: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match.  \ntype: string\n\n**cited_url_exact**: The URL of a page that was used to generate the response.  \ntype: string\n\n**cited_url_prefix**: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match.  \ntype: string\n\n**inline_domain**: The domain of a page linked in the response text.  \ntype: domain\n\n**inline_domain_subdomains**: The domain of a page linked in the response text. Any subdomain of the given domain will also match.  \ntype: string\n\n**inline_url_exact**: The URL of a page linked in the response text.  \ntype: string\n\n**inline_url_prefix**: The URL of a page linked in the response text. Any URL that starts with this prefix will match.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**sponsored_advertiser**: The advertiser name shown on a sponsored result.  \ntype: string\n\n**sponsored_description**: The description of a sponsored result.  \ntype: string\n\n**sponsored_domain**: The domain of a sponsored result.  \ntype: domain\n\n**sponsored_domain_subdomains**: The domain of a sponsored result, including any of its subdomains.  \ntype: string\n\n**sponsored_kind**: The sponsored result type. Allowed values: `ad`, `product`.  \ntype: string\n\n**sponsored_result**: Whether the response contains a sponsored result. This field only supports the `empty` operator and its negation.  \ntype: string\n\n**sponsored_title**: The title of a sponsored result.  \ntype: string\n\n**sponsored_url_exact**: The exact URL of a sponsored result.  \ntype: string\n\n**sponsored_url_prefix**: The URL prefix of a sponsored result.  \ntype: string\n\n**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.  \ntype: string",
            "required": false,
            "explode": false,
            "schema": { "type": "string" },
            "name": "where",
            "in": "query"
          },
          {
            "description": "The ID of the report to use. If one is given, other parameters are taken from the report (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#/...`",
            "required": false,
            "explode": false,
            "schema": { "type": "string" },
            "name": "report_id",
            "in": "query"
          },
          {
            "description": "The brand to search for.",
            "required": true,
            "explode": false,
            "schema": { "type": "string" },
            "name": "brand",
            "in": "query"
          },
          {
            "description": "A comma-separated list of chatbot models. All models can be combined with each other. `claude` module supports only custom prompts.\nThe `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.",
            "required": true,
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "chatgpt", "google_ai_overviews", "google_ai_mode", "gemini",
                "perplexity", "copilot", "claude", "grok",
                "google_ai_overviews_keywords", "google_ai_mode_keywords"
              ],
              "examples": [ "chatgpt,perplexity" ]
            },
            "name": "data_source",
            "in": "query"
          },
          {
            "description": "A comma-separated list of two-letter country codes (ISO 3166-1 alpha-2).",
            "required": false,
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar", "as",
                "at", "au", "aw", "az", "ba", "bb", "bd", "be", "bf", "bg",
                "bh", "bi", "bj", "bn", "bo", "br", "bs", "bt", "bw", "by",
                "bz", "ca", "cd", "cf", "cg", "ch", "ci", "ck", "cl", "cm",
                "cn", "co", "cr", "cu", "cv", "cy", "cz", "de", "dj", "dk",
                "dm", "do", "dz", "ec", "ee", "eg", "es", "et", "fi", "fj",
                "fm", "fo", "fr", "ga", "gb", "gd", "ge", "gf", "gg", "gh",
                "gi", "gl", "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gy",
                "hk", "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in",
                "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg", "kh",
                "ki", "kn", "kr", "kw", "ky", "kz", "la", "lb", "lc", "li",
                "lk", "ls", "lt", "lu", "lv", "ly", "ma", "mc", "md", "me",
                "mg", "mk", "ml", "mm", "mn", "mq", "mr", "ms", "mt", "mu",
                "mv", "mw", "mx", "my", "mz", "na", "nc", "ne", "ng", "ni",
                "nl", "no", "np", "nr", "nu", "nz", "om", "pa", "pe", "pf",
                "pg", "ph", "pk", "pl", "pn", "pr", "ps", "pt", "py", "qa",
                "re", "ro", "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg",
                "sh", "si", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv",
                "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to", "tr",
                "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz", "vc", "ve",
                "vg", "vi", "vn", "vu", "ws", "ye", "yt", "za", "zm", "zw"
              ],
              "default": ""
            },
            "name": "country",
            "in": "query"
          },
          {
            "description": "The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "enum": [ "ahrefs", "custom" ] },
            "name": "prompts",
            "in": "query"
          },
          {
            "description": "The start date of the historical period in YYYY-MM-DD format.",
            "required": true,
            "explode": false,
            "schema": { "type": "string", "format": "date" },
            "name": "date_from",
            "in": "query"
          },
          {
            "description": "The end date of the historical period in YYYY-MM-DD format.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "format": "date" },
            "name": "date_to",
            "in": "query"
          },
          { "$ref": "#/components/parameters/output" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/impressions-history"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/impressions-history"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      },
      "post": {
        "tags": [ "Overview history", "MCP" ],
        "summary": "Impressions",
        "description": ">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.",
        "operationId": "impressions-history",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "where": {
                    "type": "object",
                    "description": "The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter).\n\n**cited_domain**: The domain of a page that was used to generate the response.  \ntype: domain\n\n**cited_domain_subdomains**: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match.  \ntype: string\n\n**cited_url_exact**: The URL of a page that was used to generate the response.  \ntype: string\n\n**cited_url_prefix**: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match.  \ntype: string\n\n**inline_domain**: The domain of a page linked in the response text.  \ntype: domain\n\n**inline_domain_subdomains**: The domain of a page linked in the response text. Any subdomain of the given domain will also match.  \ntype: string\n\n**inline_url_exact**: The URL of a page linked in the response text.  \ntype: string\n\n**inline_url_prefix**: The URL of a page linked in the response text. Any URL that starts with this prefix will match.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**sponsored_advertiser**: The advertiser name shown on a sponsored result.  \ntype: string\n\n**sponsored_description**: The description of a sponsored result.  \ntype: string\n\n**sponsored_domain**: The domain of a sponsored result.  \ntype: domain\n\n**sponsored_domain_subdomains**: The domain of a sponsored result, including any of its subdomains.  \ntype: string\n\n**sponsored_kind**: The sponsored result type. Allowed values: `ad`, `product`.  \ntype: string\n\n**sponsored_result**: Whether the response contains a sponsored result. This field only supports the `empty` operator and its negation.  \ntype: string\n\n**sponsored_title**: The title of a sponsored result.  \ntype: string\n\n**sponsored_url_exact**: The exact URL of a sponsored result.  \ntype: string\n\n**sponsored_url_prefix**: The URL prefix of a sponsored result.  \ntype: string\n\n**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.  \ntype: string"
                  },
                  "report_id": {
                    "type": "string",
                    "description": "The ID of the report to use. If one is given, other parameters are taken from the report (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#/...`"
                  },
                  "brands": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of brand names and websites to search for.",
                    "default": []
                  },
                  "content_filter": {
                    "properties": {
                      "include": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Only show results containing at least one of these exact phrases."
                      },
                      "exclude": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Hide results containing any of these exact phrases."
                      }
                    },
                    "type": "object",
                    "description": "Optional phrases used to include or exclude results based on their content."
                  },
                  "data_source": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "chatgpt", "google_ai_overviews", "google_ai_mode",
                        "gemini", "perplexity", "copilot", "claude", "grok",
                        "google_ai_overviews_keywords",
                        "google_ai_mode_keywords"
                      ]
                    },
                    "type": "array",
                    "description": "A list of chatbot models. All models can be combined with each other. `claude` module supports only custom prompts.\nThe `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."
                  },
                  "country": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar",
                        "as", "at", "au", "aw", "az", "ba", "bb", "bd", "be",
                        "bf", "bg", "bh", "bi", "bj", "bn", "bo", "br", "bs",
                        "bt", "bw", "by", "bz", "ca", "cd", "cf", "cg", "ch",
                        "ci", "ck", "cl", "cm", "cn", "co", "cr", "cu", "cv",
                        "cy", "cz", "de", "dj", "dk", "dm", "do", "dz", "ec",
                        "ee", "eg", "es", "et", "fi", "fj", "fm", "fo", "fr",
                        "ga", "gb", "gd", "ge", "gf", "gg", "gh", "gi", "gl",
                        "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gy", "hk",
                        "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in",
                        "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg",
                        "kh", "ki", "kn", "kr", "kw", "ky", "kz", "la", "lb",
                        "lc", "li", "lk", "ls", "lt", "lu", "lv", "ly", "ma",
                        "mc", "md", "me", "mg", "mk", "ml", "mm", "mn", "mq",
                        "mr", "ms", "mt", "mu", "mv", "mw", "mx", "my", "mz",
                        "na", "nc", "ne", "ng", "ni", "nl", "no", "np", "nr",
                        "nu", "nz", "om", "pa", "pe", "pf", "pg", "ph", "pk",
                        "pl", "pn", "pr", "ps", "pt", "py", "qa", "re", "ro",
                        "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg", "sh",
                        "si", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv",
                        "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to",
                        "tr", "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz",
                        "vc", "ve", "vg", "vi", "vn", "vu", "ws", "ye", "yt",
                        "za", "zm", "zw"
                      ]
                    },
                    "type": "array",
                    "description": "A list of two-letter country codes (ISO 3166-1 alpha-2).",
                    "default": []
                  },
                  "prompts": {
                    "type": "string",
                    "enum": [ "ahrefs", "custom" ],
                    "description": "The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided."
                  },
                  "date_from": {
                    "type": "string",
                    "format": "date",
                    "description": "The start date of the historical period in YYYY-MM-DD format."
                  },
                  "date_to": {
                    "type": "string",
                    "format": "date",
                    "description": "The end date of the historical period in YYYY-MM-DD format."
                  },
                  "tags_filter": {
                    "properties": {},
                    "type": "object",
                    "description": "A filter expression for prompt tags. Requires `report_id`. Uses [filter syntax](https://docs.ahrefs.com/api/docs/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.",
                    "examples": [
                      {
                        "or": [
                          { "field": "tag", "is": [ "eq", "branded" ] },
                          { "field": "tag", "is": [ "eq", "competitor" ] }
                        ]
                      }
                    ]
                  },
                  "output": {
                    "type": "string",
                    "enum": [ "json", "csv", "xml", "php" ],
                    "description": "The output format."
                  }
                },
                "type": "object",
                "required": [ "data_source", "date_from" ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/impressions-history"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/impressions-history"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      }
    },
    "/citations-history": {
      "post": {
        "tags": [ "Overview history", "MCP" ],
        "summary": "Citations",
        "description": ">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.\n\nEvery 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.",
        "operationId": "citations-history",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "where": {
                    "type": "object",
                    "description": "The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter).\n\n**cited_domain**: The domain of a page that was used to generate the response.  \ntype: domain\n\n**cited_domain_subdomains**: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match.  \ntype: string\n\n**cited_url_exact**: The URL of a page that was used to generate the response.  \ntype: string\n\n**cited_url_prefix**: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match.  \ntype: string\n\n**inline_domain**: The domain of a page linked in the response text.  \ntype: domain\n\n**inline_domain_subdomains**: The domain of a page linked in the response text. Any subdomain of the given domain will also match.  \ntype: string\n\n**inline_url_exact**: The URL of a page linked in the response text.  \ntype: string\n\n**inline_url_prefix**: The URL of a page linked in the response text. Any URL that starts with this prefix will match.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**sponsored_advertiser**: The advertiser name shown on a sponsored result.  \ntype: string\n\n**sponsored_description**: The description of a sponsored result.  \ntype: string\n\n**sponsored_domain**: The domain of a sponsored result.  \ntype: domain\n\n**sponsored_domain_subdomains**: The domain of a sponsored result, including any of its subdomains.  \ntype: string\n\n**sponsored_kind**: The sponsored result type. Allowed values: `ad`, `product`.  \ntype: string\n\n**sponsored_result**: Whether the response contains a sponsored result. This field only supports the `empty` operator and its negation.  \ntype: string\n\n**sponsored_title**: The title of a sponsored result.  \ntype: string\n\n**sponsored_url_exact**: The exact URL of a sponsored result.  \ntype: string\n\n**sponsored_url_prefix**: The URL prefix of a sponsored result.  \ntype: string\n\n**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.  \ntype: string"
                  },
                  "report_id": {
                    "type": "string",
                    "description": "The ID of the report to use. If one is given, other parameters are taken from the report (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#/...`"
                  },
                  "brands": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of brand names and websites to search for.",
                    "default": []
                  },
                  "content_filter": {
                    "properties": {
                      "include": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Only show results containing at least one of these exact phrases."
                      },
                      "exclude": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Hide results containing any of these exact phrases."
                      }
                    },
                    "type": "object",
                    "description": "Optional phrases used to include or exclude results based on their content."
                  },
                  "data_source": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "chatgpt", "google_ai_overviews", "google_ai_mode",
                        "gemini", "perplexity", "copilot", "claude", "grok",
                        "google_ai_overviews_keywords",
                        "google_ai_mode_keywords"
                      ]
                    },
                    "type": "array",
                    "description": "A list of chatbot models. All models can be combined with each other. `claude` module supports only custom prompts.\nThe `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."
                  },
                  "country": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar",
                        "as", "at", "au", "aw", "az", "ba", "bb", "bd", "be",
                        "bf", "bg", "bh", "bi", "bj", "bn", "bo", "br", "bs",
                        "bt", "bw", "by", "bz", "ca", "cd", "cf", "cg", "ch",
                        "ci", "ck", "cl", "cm", "cn", "co", "cr", "cu", "cv",
                        "cy", "cz", "de", "dj", "dk", "dm", "do", "dz", "ec",
                        "ee", "eg", "es", "et", "fi", "fj", "fm", "fo", "fr",
                        "ga", "gb", "gd", "ge", "gf", "gg", "gh", "gi", "gl",
                        "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gy", "hk",
                        "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in",
                        "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg",
                        "kh", "ki", "kn", "kr", "kw", "ky", "kz", "la", "lb",
                        "lc", "li", "lk", "ls", "lt", "lu", "lv", "ly", "ma",
                        "mc", "md", "me", "mg", "mk", "ml", "mm", "mn", "mq",
                        "mr", "ms", "mt", "mu", "mv", "mw", "mx", "my", "mz",
                        "na", "nc", "ne", "ng", "ni", "nl", "no", "np", "nr",
                        "nu", "nz", "om", "pa", "pe", "pf", "pg", "ph", "pk",
                        "pl", "pn", "pr", "ps", "pt", "py", "qa", "re", "ro",
                        "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg", "sh",
                        "si", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv",
                        "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to",
                        "tr", "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz",
                        "vc", "ve", "vg", "vi", "vn", "vu", "ws", "ye", "yt",
                        "za", "zm", "zw"
                      ]
                    },
                    "type": "array",
                    "description": "A list of two-letter country codes (ISO 3166-1 alpha-2).",
                    "default": []
                  },
                  "prompts": {
                    "type": "string",
                    "enum": [ "ahrefs", "custom" ],
                    "description": "The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided."
                  },
                  "date_from": {
                    "type": "string",
                    "format": "date",
                    "description": "The start date of the historical period in YYYY-MM-DD format."
                  },
                  "date_to": {
                    "type": "string",
                    "format": "date",
                    "description": "The end date of the historical period in YYYY-MM-DD format."
                  },
                  "tags_filter": {
                    "properties": {},
                    "type": "object",
                    "description": "A filter expression for prompt tags. Requires `report_id`. Uses [filter syntax](https://docs.ahrefs.com/api/docs/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.",
                    "examples": [
                      {
                        "or": [
                          { "field": "tag", "is": [ "eq", "branded" ] },
                          { "field": "tag", "is": [ "eq", "competitor" ] }
                        ]
                      }
                    ]
                  },
                  "output": {
                    "type": "string",
                    "enum": [ "json", "csv", "xml", "php" ],
                    "description": "The output format."
                  }
                },
                "type": "object",
                "required": [ "data_source", "date_from" ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/citations-history"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/citations-history"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      }
    },
    "/mentions-history": {
      "get": {
        "tags": [ "Overview history", "MCP" ],
        "summary": "Mentions",
        "description": ">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.",
        "operationId": "mentions-history",
        "parameters": [
          {
            "description": "The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter).\n\n**cited_domain**: The domain of a page that was used to generate the response.  \ntype: domain\n\n**cited_domain_subdomains**: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match.  \ntype: string\n\n**cited_url_exact**: The URL of a page that was used to generate the response.  \ntype: string\n\n**cited_url_prefix**: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match.  \ntype: string\n\n**inline_domain**: The domain of a page linked in the response text.  \ntype: domain\n\n**inline_domain_subdomains**: The domain of a page linked in the response text. Any subdomain of the given domain will also match.  \ntype: string\n\n**inline_url_exact**: The URL of a page linked in the response text.  \ntype: string\n\n**inline_url_prefix**: The URL of a page linked in the response text. Any URL that starts with this prefix will match.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**sponsored_advertiser**: The advertiser name shown on a sponsored result.  \ntype: string\n\n**sponsored_description**: The description of a sponsored result.  \ntype: string\n\n**sponsored_domain**: The domain of a sponsored result.  \ntype: domain\n\n**sponsored_domain_subdomains**: The domain of a sponsored result, including any of its subdomains.  \ntype: string\n\n**sponsored_kind**: The sponsored result type. Allowed values: `ad`, `product`.  \ntype: string\n\n**sponsored_result**: Whether the response contains a sponsored result. This field only supports the `empty` operator and its negation.  \ntype: string\n\n**sponsored_title**: The title of a sponsored result.  \ntype: string\n\n**sponsored_url_exact**: The exact URL of a sponsored result.  \ntype: string\n\n**sponsored_url_prefix**: The URL prefix of a sponsored result.  \ntype: string\n\n**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.  \ntype: string",
            "required": false,
            "explode": false,
            "schema": { "type": "string" },
            "name": "where",
            "in": "query"
          },
          {
            "description": "The ID of the report to use. If one is given, other parameters are taken from the report (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#/...`",
            "required": false,
            "explode": false,
            "schema": { "type": "string" },
            "name": "report_id",
            "in": "query"
          },
          {
            "description": "The brand to search for.",
            "required": true,
            "explode": false,
            "schema": { "type": "string" },
            "name": "brand",
            "in": "query"
          },
          {
            "description": "A comma-separated list of chatbot models. All models can be combined with each other. `claude` module supports only custom prompts.\nThe `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.",
            "required": true,
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "chatgpt", "google_ai_overviews", "google_ai_mode", "gemini",
                "perplexity", "copilot", "claude", "grok",
                "google_ai_overviews_keywords", "google_ai_mode_keywords"
              ],
              "examples": [ "chatgpt,perplexity" ]
            },
            "name": "data_source",
            "in": "query"
          },
          {
            "description": "A comma-separated list of two-letter country codes (ISO 3166-1 alpha-2).",
            "required": false,
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar", "as",
                "at", "au", "aw", "az", "ba", "bb", "bd", "be", "bf", "bg",
                "bh", "bi", "bj", "bn", "bo", "br", "bs", "bt", "bw", "by",
                "bz", "ca", "cd", "cf", "cg", "ch", "ci", "ck", "cl", "cm",
                "cn", "co", "cr", "cu", "cv", "cy", "cz", "de", "dj", "dk",
                "dm", "do", "dz", "ec", "ee", "eg", "es", "et", "fi", "fj",
                "fm", "fo", "fr", "ga", "gb", "gd", "ge", "gf", "gg", "gh",
                "gi", "gl", "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gy",
                "hk", "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in",
                "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg", "kh",
                "ki", "kn", "kr", "kw", "ky", "kz", "la", "lb", "lc", "li",
                "lk", "ls", "lt", "lu", "lv", "ly", "ma", "mc", "md", "me",
                "mg", "mk", "ml", "mm", "mn", "mq", "mr", "ms", "mt", "mu",
                "mv", "mw", "mx", "my", "mz", "na", "nc", "ne", "ng", "ni",
                "nl", "no", "np", "nr", "nu", "nz", "om", "pa", "pe", "pf",
                "pg", "ph", "pk", "pl", "pn", "pr", "ps", "pt", "py", "qa",
                "re", "ro", "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg",
                "sh", "si", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv",
                "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to", "tr",
                "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz", "vc", "ve",
                "vg", "vi", "vn", "vu", "ws", "ye", "yt", "za", "zm", "zw"
              ],
              "default": ""
            },
            "name": "country",
            "in": "query"
          },
          {
            "description": "The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "enum": [ "ahrefs", "custom" ] },
            "name": "prompts",
            "in": "query"
          },
          {
            "description": "The start date of the historical period in YYYY-MM-DD format.",
            "required": true,
            "explode": false,
            "schema": { "type": "string", "format": "date" },
            "name": "date_from",
            "in": "query"
          },
          {
            "description": "The end date of the historical period in YYYY-MM-DD format.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "format": "date" },
            "name": "date_to",
            "in": "query"
          },
          { "$ref": "#/components/parameters/output" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/mentions-history" }
              },
              "application/xml": {
                "schema": { "$ref": "#/components/schemas/mentions-history" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      },
      "post": {
        "tags": [ "Overview history", "MCP" ],
        "summary": "Mentions",
        "description": ">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.\n\nEvery entity provided in `brands` (and `competitors`, when applicable) must include at least one value in `names`. Entities consisting only of `url_groups` are not supported here because mentions are matched against brand names.",
        "operationId": "mentions-history",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "where": {
                    "type": "object",
                    "description": "The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter).\n\n**cited_domain**: The domain of a page that was used to generate the response.  \ntype: domain\n\n**cited_domain_subdomains**: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match.  \ntype: string\n\n**cited_url_exact**: The URL of a page that was used to generate the response.  \ntype: string\n\n**cited_url_prefix**: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match.  \ntype: string\n\n**inline_domain**: The domain of a page linked in the response text.  \ntype: domain\n\n**inline_domain_subdomains**: The domain of a page linked in the response text. Any subdomain of the given domain will also match.  \ntype: string\n\n**inline_url_exact**: The URL of a page linked in the response text.  \ntype: string\n\n**inline_url_prefix**: The URL of a page linked in the response text. Any URL that starts with this prefix will match.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**sponsored_advertiser**: The advertiser name shown on a sponsored result.  \ntype: string\n\n**sponsored_description**: The description of a sponsored result.  \ntype: string\n\n**sponsored_domain**: The domain of a sponsored result.  \ntype: domain\n\n**sponsored_domain_subdomains**: The domain of a sponsored result, including any of its subdomains.  \ntype: string\n\n**sponsored_kind**: The sponsored result type. Allowed values: `ad`, `product`.  \ntype: string\n\n**sponsored_result**: Whether the response contains a sponsored result. This field only supports the `empty` operator and its negation.  \ntype: string\n\n**sponsored_title**: The title of a sponsored result.  \ntype: string\n\n**sponsored_url_exact**: The exact URL of a sponsored result.  \ntype: string\n\n**sponsored_url_prefix**: The URL prefix of a sponsored result.  \ntype: string\n\n**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.  \ntype: string"
                  },
                  "report_id": {
                    "type": "string",
                    "description": "The ID of the report to use. If one is given, other parameters are taken from the report (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#/...`"
                  },
                  "brands": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of brand names and websites to search for.",
                    "default": []
                  },
                  "content_filter": {
                    "properties": {
                      "include": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Only show results containing at least one of these exact phrases."
                      },
                      "exclude": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Hide results containing any of these exact phrases."
                      }
                    },
                    "type": "object",
                    "description": "Optional phrases used to include or exclude results based on their content."
                  },
                  "data_source": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "chatgpt", "google_ai_overviews", "google_ai_mode",
                        "gemini", "perplexity", "copilot", "claude", "grok",
                        "google_ai_overviews_keywords",
                        "google_ai_mode_keywords"
                      ]
                    },
                    "type": "array",
                    "description": "A list of chatbot models. All models can be combined with each other. `claude` module supports only custom prompts.\nThe `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."
                  },
                  "country": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar",
                        "as", "at", "au", "aw", "az", "ba", "bb", "bd", "be",
                        "bf", "bg", "bh", "bi", "bj", "bn", "bo", "br", "bs",
                        "bt", "bw", "by", "bz", "ca", "cd", "cf", "cg", "ch",
                        "ci", "ck", "cl", "cm", "cn", "co", "cr", "cu", "cv",
                        "cy", "cz", "de", "dj", "dk", "dm", "do", "dz", "ec",
                        "ee", "eg", "es", "et", "fi", "fj", "fm", "fo", "fr",
                        "ga", "gb", "gd", "ge", "gf", "gg", "gh", "gi", "gl",
                        "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gy", "hk",
                        "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in",
                        "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg",
                        "kh", "ki", "kn", "kr", "kw", "ky", "kz", "la", "lb",
                        "lc", "li", "lk", "ls", "lt", "lu", "lv", "ly", "ma",
                        "mc", "md", "me", "mg", "mk", "ml", "mm", "mn", "mq",
                        "mr", "ms", "mt", "mu", "mv", "mw", "mx", "my", "mz",
                        "na", "nc", "ne", "ng", "ni", "nl", "no", "np", "nr",
                        "nu", "nz", "om", "pa", "pe", "pf", "pg", "ph", "pk",
                        "pl", "pn", "pr", "ps", "pt", "py", "qa", "re", "ro",
                        "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg", "sh",
                        "si", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv",
                        "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to",
                        "tr", "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz",
                        "vc", "ve", "vg", "vi", "vn", "vu", "ws", "ye", "yt",
                        "za", "zm", "zw"
                      ]
                    },
                    "type": "array",
                    "description": "A list of two-letter country codes (ISO 3166-1 alpha-2).",
                    "default": []
                  },
                  "prompts": {
                    "type": "string",
                    "enum": [ "ahrefs", "custom" ],
                    "description": "The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided."
                  },
                  "date_from": {
                    "type": "string",
                    "format": "date",
                    "description": "The start date of the historical period in YYYY-MM-DD format."
                  },
                  "date_to": {
                    "type": "string",
                    "format": "date",
                    "description": "The end date of the historical period in YYYY-MM-DD format."
                  },
                  "tags_filter": {
                    "properties": {},
                    "type": "object",
                    "description": "A filter expression for prompt tags. Requires `report_id`. Uses [filter syntax](https://docs.ahrefs.com/api/docs/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.",
                    "examples": [
                      {
                        "or": [
                          { "field": "tag", "is": [ "eq", "branded" ] },
                          { "field": "tag", "is": [ "eq", "competitor" ] }
                        ]
                      }
                    ]
                  },
                  "output": {
                    "type": "string",
                    "enum": [ "json", "csv", "xml", "php" ],
                    "description": "The output format."
                  }
                },
                "type": "object",
                "required": [ "data_source", "date_from" ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/mentions-history" }
              },
              "application/xml": {
                "schema": { "$ref": "#/components/schemas/mentions-history" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      }
    },
    "/sov-history": {
      "get": {
        "tags": [ "Overview history", "MCP" ],
        "summary": "Share of Voice",
        "description": ">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.",
        "operationId": "sov-history",
        "parameters": [
          {
            "description": "The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter).\n\n**cited_domain**: The domain of a page that was used to generate the response.  \ntype: domain\n\n**cited_domain_subdomains**: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match.  \ntype: string\n\n**cited_url_exact**: The URL of a page that was used to generate the response.  \ntype: string\n\n**cited_url_prefix**: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match.  \ntype: string\n\n**inline_domain**: The domain of a page linked in the response text.  \ntype: domain\n\n**inline_domain_subdomains**: The domain of a page linked in the response text. Any subdomain of the given domain will also match.  \ntype: string\n\n**inline_url_exact**: The URL of a page linked in the response text.  \ntype: string\n\n**inline_url_prefix**: The URL of a page linked in the response text. Any URL that starts with this prefix will match.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**sponsored_advertiser**: The advertiser name shown on a sponsored result.  \ntype: string\n\n**sponsored_description**: The description of a sponsored result.  \ntype: string\n\n**sponsored_domain**: The domain of a sponsored result.  \ntype: domain\n\n**sponsored_domain_subdomains**: The domain of a sponsored result, including any of its subdomains.  \ntype: string\n\n**sponsored_kind**: The sponsored result type. Allowed values: `ad`, `product`.  \ntype: string\n\n**sponsored_result**: Whether the response contains a sponsored result. This field only supports the `empty` operator and its negation.  \ntype: string\n\n**sponsored_title**: The title of a sponsored result.  \ntype: string\n\n**sponsored_url_exact**: The exact URL of a sponsored result.  \ntype: string\n\n**sponsored_url_prefix**: The URL prefix of a sponsored result.  \ntype: string\n\n**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.  \ntype: string",
            "required": false,
            "explode": false,
            "schema": { "type": "string" },
            "name": "where",
            "in": "query"
          },
          {
            "description": "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#/...`",
            "required": false,
            "explode": false,
            "schema": { "type": "string" },
            "name": "report_id",
            "in": "query"
          },
          {
            "description": "A comma-separated list of brands to search for. At least one of brand, competitors, market or where should not be empty.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "default": "" },
            "name": "brand",
            "in": "query"
          },
          {
            "description": "A comma-separated list of competitors of your brands.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "default": "" },
            "name": "competitors",
            "in": "query"
          },
          {
            "description": "A comma-separated list of chatbot models. All models can be combined with each other. `claude` module supports only custom prompts.\nThe `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.",
            "required": true,
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "chatgpt", "google_ai_overviews", "google_ai_mode", "gemini",
                "perplexity", "copilot", "claude", "grok",
                "google_ai_overviews_keywords", "google_ai_mode_keywords"
              ],
              "examples": [ "chatgpt,perplexity" ]
            },
            "name": "data_source",
            "in": "query"
          },
          {
            "description": "A comma-separated list of two-letter country codes (ISO 3166-1 alpha-2).",
            "required": false,
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar", "as",
                "at", "au", "aw", "az", "ba", "bb", "bd", "be", "bf", "bg",
                "bh", "bi", "bj", "bn", "bo", "br", "bs", "bt", "bw", "by",
                "bz", "ca", "cd", "cf", "cg", "ch", "ci", "ck", "cl", "cm",
                "cn", "co", "cr", "cu", "cv", "cy", "cz", "de", "dj", "dk",
                "dm", "do", "dz", "ec", "ee", "eg", "es", "et", "fi", "fj",
                "fm", "fo", "fr", "ga", "gb", "gd", "ge", "gf", "gg", "gh",
                "gi", "gl", "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gy",
                "hk", "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in",
                "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg", "kh",
                "ki", "kn", "kr", "kw", "ky", "kz", "la", "lb", "lc", "li",
                "lk", "ls", "lt", "lu", "lv", "ly", "ma", "mc", "md", "me",
                "mg", "mk", "ml", "mm", "mn", "mq", "mr", "ms", "mt", "mu",
                "mv", "mw", "mx", "my", "mz", "na", "nc", "ne", "ng", "ni",
                "nl", "no", "np", "nr", "nu", "nz", "om", "pa", "pe", "pf",
                "pg", "ph", "pk", "pl", "pn", "pr", "ps", "pt", "py", "qa",
                "re", "ro", "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg",
                "sh", "si", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv",
                "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to", "tr",
                "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz", "vc", "ve",
                "vg", "vi", "vn", "vu", "ws", "ye", "yt", "za", "zm", "zw"
              ],
              "default": ""
            },
            "name": "country",
            "in": "query"
          },
          {
            "description": "The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "enum": [ "ahrefs", "custom" ] },
            "name": "prompts",
            "in": "query"
          },
          {
            "description": "The start date of the historical period in YYYY-MM-DD format.",
            "required": true,
            "explode": false,
            "schema": { "type": "string", "format": "date" },
            "name": "date_from",
            "in": "query"
          },
          {
            "description": "The end date of the historical period in YYYY-MM-DD format.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "format": "date" },
            "name": "date_to",
            "in": "query"
          },
          { "$ref": "#/components/parameters/output_json_php" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/sov-history" }
              },
              "application/xml": {
                "schema": { "$ref": "#/components/schemas/sov-history" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      },
      "post": {
        "tags": [ "Overview history", "MCP" ],
        "summary": "Share of Voice",
        "description": ">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.",
        "operationId": "sov-history",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "where": {
                    "type": "object",
                    "description": "The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter).\n\n**cited_domain**: The domain of a page that was used to generate the response.  \ntype: domain\n\n**cited_domain_subdomains**: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match.  \ntype: string\n\n**cited_url_exact**: The URL of a page that was used to generate the response.  \ntype: string\n\n**cited_url_prefix**: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match.  \ntype: string\n\n**inline_domain**: The domain of a page linked in the response text.  \ntype: domain\n\n**inline_domain_subdomains**: The domain of a page linked in the response text. Any subdomain of the given domain will also match.  \ntype: string\n\n**inline_url_exact**: The URL of a page linked in the response text.  \ntype: string\n\n**inline_url_prefix**: The URL of a page linked in the response text. Any URL that starts with this prefix will match.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**sponsored_advertiser**: The advertiser name shown on a sponsored result.  \ntype: string\n\n**sponsored_description**: The description of a sponsored result.  \ntype: string\n\n**sponsored_domain**: The domain of a sponsored result.  \ntype: domain\n\n**sponsored_domain_subdomains**: The domain of a sponsored result, including any of its subdomains.  \ntype: string\n\n**sponsored_kind**: The sponsored result type. Allowed values: `ad`, `product`.  \ntype: string\n\n**sponsored_result**: Whether the response contains a sponsored result. This field only supports the `empty` operator and its negation.  \ntype: string\n\n**sponsored_title**: The title of a sponsored result.  \ntype: string\n\n**sponsored_url_exact**: The exact URL of a sponsored result.  \ntype: string\n\n**sponsored_url_prefix**: The URL prefix of a sponsored result.  \ntype: string\n\n**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.  \ntype: string"
                  },
                  "report_id": {
                    "type": "string",
                    "description": "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#/...`"
                  },
                  "brands": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of brand names and websites to search for.",
                    "default": []
                  },
                  "competitors": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of competitor names and websites to search for.",
                    "default": []
                  },
                  "content_filter": {
                    "properties": {
                      "include": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Only show results containing at least one of these exact phrases."
                      },
                      "exclude": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Hide results containing any of these exact phrases."
                      }
                    },
                    "type": "object",
                    "description": "Optional phrases used to include or exclude results based on their content."
                  },
                  "data_source": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "chatgpt", "google_ai_overviews", "google_ai_mode",
                        "gemini", "perplexity", "copilot", "claude", "grok",
                        "google_ai_overviews_keywords",
                        "google_ai_mode_keywords"
                      ]
                    },
                    "type": "array",
                    "description": "A list of chatbot models. All models can be combined with each other. `claude` module supports only custom prompts.\nThe `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."
                  },
                  "country": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar",
                        "as", "at", "au", "aw", "az", "ba", "bb", "bd", "be",
                        "bf", "bg", "bh", "bi", "bj", "bn", "bo", "br", "bs",
                        "bt", "bw", "by", "bz", "ca", "cd", "cf", "cg", "ch",
                        "ci", "ck", "cl", "cm", "cn", "co", "cr", "cu", "cv",
                        "cy", "cz", "de", "dj", "dk", "dm", "do", "dz", "ec",
                        "ee", "eg", "es", "et", "fi", "fj", "fm", "fo", "fr",
                        "ga", "gb", "gd", "ge", "gf", "gg", "gh", "gi", "gl",
                        "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gy", "hk",
                        "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in",
                        "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg",
                        "kh", "ki", "kn", "kr", "kw", "ky", "kz", "la", "lb",
                        "lc", "li", "lk", "ls", "lt", "lu", "lv", "ly", "ma",
                        "mc", "md", "me", "mg", "mk", "ml", "mm", "mn", "mq",
                        "mr", "ms", "mt", "mu", "mv", "mw", "mx", "my", "mz",
                        "na", "nc", "ne", "ng", "ni", "nl", "no", "np", "nr",
                        "nu", "nz", "om", "pa", "pe", "pf", "pg", "ph", "pk",
                        "pl", "pn", "pr", "ps", "pt", "py", "qa", "re", "ro",
                        "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg", "sh",
                        "si", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv",
                        "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to",
                        "tr", "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz",
                        "vc", "ve", "vg", "vi", "vn", "vu", "ws", "ye", "yt",
                        "za", "zm", "zw"
                      ]
                    },
                    "type": "array",
                    "description": "A list of two-letter country codes (ISO 3166-1 alpha-2).",
                    "default": []
                  },
                  "prompts": {
                    "type": "string",
                    "enum": [ "ahrefs", "custom" ],
                    "description": "The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided."
                  },
                  "date_from": {
                    "type": "string",
                    "format": "date",
                    "description": "The start date of the historical period in YYYY-MM-DD format."
                  },
                  "date_to": {
                    "type": "string",
                    "format": "date",
                    "description": "The end date of the historical period in YYYY-MM-DD format."
                  },
                  "tags_filter": {
                    "properties": {},
                    "type": "object",
                    "description": "A filter expression for prompt tags. Requires `report_id`. Uses [filter syntax](https://docs.ahrefs.com/api/docs/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.",
                    "examples": [
                      {
                        "or": [
                          { "field": "tag", "is": [ "eq", "branded" ] },
                          { "field": "tag", "is": [ "eq", "competitor" ] }
                        ]
                      }
                    ]
                  },
                  "output": {
                    "type": "string",
                    "enum": [ "json", "php" ],
                    "description": "The output format."
                  }
                },
                "type": "object",
                "required": [ "data_source", "date_from" ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/sov-history" }
              },
              "application/xml": {
                "schema": { "$ref": "#/components/schemas/sov-history" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      }
    },
    "/topics": {
      "post": {
        "tags": [ "AI visibility", "MCP", "Enterprise only" ],
        "summary": "Topics",
        "description": ">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.",
        "operationId": "topics",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "select": {
                    "items": { "type": "string" },
                    "type": "array",
                    "description": "A list of fields to return.\n\n- `country`\n- `mentions`\n- `responses`\n- `topic`\n- `volume`",
                    "examples": [ [ "field_a", "field_b" ] ]
                  },
                  "where": {
                    "type": "object",
                    "description": "The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter).\n\n**cited_domain**: The domain of a page that was used to generate the response.  \ntype: domain\n\n**cited_domain_subdomains**: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match.  \ntype: string\n\n**cited_url_exact**: The URL of a page that was used to generate the response.  \ntype: string\n\n**cited_url_prefix**: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match.  \ntype: string\n\n**inline_domain**: The domain of a page linked in the response text.  \ntype: domain\n\n**inline_domain_subdomains**: The domain of a page linked in the response text. Any subdomain of the given domain will also match.  \ntype: string\n\n**inline_url_exact**: The URL of a page linked in the response text.  \ntype: string\n\n**inline_url_prefix**: The URL of a page linked in the response text. Any URL that starts with this prefix will match.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**sponsored_advertiser**: The advertiser name shown on a sponsored result.  \ntype: string\n\n**sponsored_description**: The description of a sponsored result.  \ntype: string\n\n**sponsored_domain**: The domain of a sponsored result.  \ntype: domain\n\n**sponsored_domain_subdomains**: The domain of a sponsored result, including any of its subdomains.  \ntype: string\n\n**sponsored_kind**: The sponsored result type. Allowed values: `ad`, `product`.  \ntype: string\n\n**sponsored_result**: Whether the response contains a sponsored result. This field only supports the `empty` operator and its negation.  \ntype: string\n\n**sponsored_title**: The title of a sponsored result.  \ntype: string\n\n**sponsored_url_exact**: The exact URL of a sponsored result.  \ntype: string\n\n**sponsored_url_prefix**: The URL prefix of a sponsored result.  \ntype: string\n\n**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.  \ntype: string"
                  },
                  "report_id": {
                    "type": "string",
                    "description": "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#/...`"
                  },
                  "brands": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of brand names and websites to search for.",
                    "default": []
                  },
                  "competitors": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of competitor names and websites to search for.",
                    "default": []
                  },
                  "content_filter": {
                    "properties": {
                      "include": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Only show results containing at least one of these exact phrases."
                      },
                      "exclude": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Hide results containing any of these exact phrases."
                      }
                    },
                    "type": "object",
                    "description": "Optional phrases used to include or exclude results based on their content."
                  },
                  "data_source": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "chatgpt", "google_ai_overviews", "google_ai_mode",
                        "gemini", "perplexity", "copilot", "claude", "grok",
                        "google_ai_overviews_keywords",
                        "google_ai_mode_keywords"
                      ]
                    },
                    "type": "array",
                    "description": "A list of chatbot models. All models can be combined with each other. `claude` module supports only custom prompts.\nThe `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."
                  },
                  "country": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar",
                        "as", "at", "au", "aw", "az", "ba", "bb", "bd", "be",
                        "bf", "bg", "bh", "bi", "bj", "bn", "bo", "br", "bs",
                        "bt", "bw", "by", "bz", "ca", "cd", "cf", "cg", "ch",
                        "ci", "ck", "cl", "cm", "cn", "co", "cr", "cu", "cv",
                        "cy", "cz", "de", "dj", "dk", "dm", "do", "dz", "ec",
                        "ee", "eg", "es", "et", "fi", "fj", "fm", "fo", "fr",
                        "ga", "gb", "gd", "ge", "gf", "gg", "gh", "gi", "gl",
                        "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gy", "hk",
                        "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in",
                        "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg",
                        "kh", "ki", "kn", "kr", "kw", "ky", "kz", "la", "lb",
                        "lc", "li", "lk", "ls", "lt", "lu", "lv", "ly", "ma",
                        "mc", "md", "me", "mg", "mk", "ml", "mm", "mn", "mq",
                        "mr", "ms", "mt", "mu", "mv", "mw", "mx", "my", "mz",
                        "na", "nc", "ne", "ng", "ni", "nl", "no", "np", "nr",
                        "nu", "nz", "om", "pa", "pe", "pf", "pg", "ph", "pk",
                        "pl", "pn", "pr", "ps", "pt", "py", "qa", "re", "ro",
                        "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg", "sh",
                        "si", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv",
                        "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to",
                        "tr", "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz",
                        "vc", "ve", "vg", "vi", "vn", "vu", "ws", "ye", "yt",
                        "za", "zm", "zw"
                      ]
                    },
                    "type": "array",
                    "description": "A list of two-letter country codes (ISO 3166-1 alpha-2).",
                    "default": []
                  },
                  "prompts": {
                    "type": "string",
                    "enum": [ "ahrefs", "custom" ],
                    "description": "The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided."
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 2000,
                    "description": "The number of results to return.",
                    "default": 1000
                  },
                  "date": {
                    "type": "string",
                    "format": "date",
                    "description": "The date to search for in YYYY-MM-DD format."
                  },
                  "date_from": {
                    "type": "string",
                    "format": "date",
                    "description": "The start date of the historical period in YYYY-MM-DD format."
                  },
                  "date_to": {
                    "type": "string",
                    "format": "date",
                    "description": "The end date of the historical period in YYYY-MM-DD format."
                  },
                  "tags_filter": {
                    "properties": {},
                    "type": "object",
                    "description": "A filter expression for prompt tags. Requires `report_id`. Uses [filter syntax](https://docs.ahrefs.com/api/docs/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.",
                    "examples": [
                      {
                        "or": [
                          { "field": "tag", "is": [ "eq", "branded" ] },
                          { "field": "tag", "is": [ "eq", "competitor" ] }
                        ]
                      }
                    ]
                  },
                  "brand_filter": {
                    "properties": {},
                    "type": "object",
                    "description": "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). \nUses [filter syntax](https://docs.ahrefs.com/api/docs/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).",
                    "examples": [
                      {
                        "and": [
                          {
                            "field": "brand_name",
                            "is": [ "eq", "mentioned" ]
                          },
                          {
                            "or": [
                              {
                                "field": "page_status",
                                "is": [ "eq", "cited" ]
                              },
                              {
                                "field": "page_status",
                                "is": [ "eq", "found_but_not_cited" ]
                              }
                            ]
                          }
                        ]
                      }
                    ]
                  },
                  "volume_range": {
                    "properties": {
                      "from": { "type": "integer", "minimum": 0 },
                      "to": { "type": "integer", "minimum": 0 }
                    },
                    "type": "object",
                    "description": "The volume range to filter by."
                  },
                  "output": {
                    "type": "string",
                    "enum": [ "json", "php" ],
                    "description": "The output format."
                  }
                },
                "type": "object",
                "required": [ "select", "data_source" ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/topics" }
              },
              "application/xml": {
                "schema": { "$ref": "#/components/schemas/topics" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      }
    },
    "/cited-pages": {
      "get": {
        "tags": [ "AI visibility", "MCP" ],
        "summary": "Cited Pages",
        "description": ">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.",
        "operationId": "cited-pages",
        "parameters": [
          {
            "description": "A comma-separated list of fields to return.\n\n- `responses`\n- `title`\n- `url`",
            "required": true,
            "explode": false,
            "schema": { "type": "string" },
            "name": "select",
            "in": "query"
          },
          {
            "description": "The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter).\n\n**cited_domain**: The domain of a page that was used to generate the response.  \ntype: domain\n\n**cited_domain_subdomains**: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match.  \ntype: string\n\n**cited_url_exact**: The URL of a page that was used to generate the response.  \ntype: string\n\n**cited_url_prefix**: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match.  \ntype: string\n\n**inline_domain**: The domain of a page linked in the response text.  \ntype: domain\n\n**inline_domain_subdomains**: The domain of a page linked in the response text. Any subdomain of the given domain will also match.  \ntype: string\n\n**inline_url_exact**: The URL of a page linked in the response text.  \ntype: string\n\n**inline_url_prefix**: The URL of a page linked in the response text. Any URL that starts with this prefix will match.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**sponsored_advertiser**: The advertiser name shown on a sponsored result.  \ntype: string\n\n**sponsored_description**: The description of a sponsored result.  \ntype: string\n\n**sponsored_domain**: The domain of a sponsored result.  \ntype: domain\n\n**sponsored_domain_subdomains**: The domain of a sponsored result, including any of its subdomains.  \ntype: string\n\n**sponsored_kind**: The sponsored result type. Allowed values: `ad`, `product`.  \ntype: string\n\n**sponsored_result**: Whether the response contains a sponsored result. This field only supports the `empty` operator and its negation.  \ntype: string\n\n**sponsored_title**: The title of a sponsored result.  \ntype: string\n\n**sponsored_url_exact**: The exact URL of a sponsored result.  \ntype: string\n\n**sponsored_url_prefix**: The URL prefix of a sponsored result.  \ntype: string\n\n**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.  \ntype: string",
            "required": false,
            "explode": false,
            "schema": { "type": "string" },
            "name": "where",
            "in": "query"
          },
          {
            "description": "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#/...`",
            "required": false,
            "explode": false,
            "schema": { "type": "string" },
            "name": "report_id",
            "in": "query"
          },
          {
            "description": "A comma-separated list of brands to search for. At least one of brand, competitors, market or where should not be empty.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "default": "" },
            "name": "brand",
            "in": "query"
          },
          {
            "description": "A comma-separated list of competitors of your brands.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "default": "" },
            "name": "competitors",
            "in": "query"
          },
          {
            "description": "A comma-separated list of chatbot models. All models can be combined with each other. `claude` module supports only custom prompts.\nThe `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.",
            "required": true,
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "chatgpt", "google_ai_overviews", "google_ai_mode", "gemini",
                "perplexity", "copilot", "claude", "grok",
                "google_ai_overviews_keywords", "google_ai_mode_keywords"
              ],
              "examples": [ "chatgpt,perplexity" ]
            },
            "name": "data_source",
            "in": "query"
          },
          {
            "description": "A comma-separated list of two-letter country codes (ISO 3166-1 alpha-2).",
            "required": false,
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar", "as",
                "at", "au", "aw", "az", "ba", "bb", "bd", "be", "bf", "bg",
                "bh", "bi", "bj", "bn", "bo", "br", "bs", "bt", "bw", "by",
                "bz", "ca", "cd", "cf", "cg", "ch", "ci", "ck", "cl", "cm",
                "cn", "co", "cr", "cu", "cv", "cy", "cz", "de", "dj", "dk",
                "dm", "do", "dz", "ec", "ee", "eg", "es", "et", "fi", "fj",
                "fm", "fo", "fr", "ga", "gb", "gd", "ge", "gf", "gg", "gh",
                "gi", "gl", "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gy",
                "hk", "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in",
                "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg", "kh",
                "ki", "kn", "kr", "kw", "ky", "kz", "la", "lb", "lc", "li",
                "lk", "ls", "lt", "lu", "lv", "ly", "ma", "mc", "md", "me",
                "mg", "mk", "ml", "mm", "mn", "mq", "mr", "ms", "mt", "mu",
                "mv", "mw", "mx", "my", "mz", "na", "nc", "ne", "ng", "ni",
                "nl", "no", "np", "nr", "nu", "nz", "om", "pa", "pe", "pf",
                "pg", "ph", "pk", "pl", "pn", "pr", "ps", "pt", "py", "qa",
                "re", "ro", "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg",
                "sh", "si", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv",
                "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to", "tr",
                "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz", "vc", "ve",
                "vg", "vi", "vn", "vu", "ws", "ye", "yt", "za", "zm", "zw"
              ],
              "default": ""
            },
            "name": "country",
            "in": "query"
          },
          {
            "description": "The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "enum": [ "ahrefs", "custom" ] },
            "name": "prompts",
            "in": "query"
          },
          {
            "description": "The number of results to return.",
            "required": false,
            "explode": false,
            "schema": { "type": "integer", "default": 1000 },
            "name": "limit",
            "in": "query"
          },
          {
            "description": "The date to search for in YYYY-MM-DD format.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "format": "date" },
            "name": "date",
            "in": "query"
          },
          {
            "description": "A comma-separated list of tracked page URLs. When provided, the response includes rows with zero citations for any tracked URLs that have no data.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "default": "" },
            "name": "tracked_urls",
            "in": "query"
          },
          { "$ref": "#/components/parameters/output_json_php" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/cited-pages" }
              },
              "application/xml": {
                "schema": { "$ref": "#/components/schemas/cited-pages" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      },
      "post": {
        "tags": [ "AI visibility", "MCP" ],
        "summary": "Cited Pages",
        "description": ">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.",
        "operationId": "cited-pages",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "select": {
                    "items": { "type": "string" },
                    "type": "array",
                    "description": "A list of fields to return.\n\n- `responses`\n- `title`\n- `url`",
                    "examples": [ [ "field_a", "field_b" ] ]
                  },
                  "where": {
                    "type": "object",
                    "description": "The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter).\n\n**cited_domain**: The domain of a page that was used to generate the response.  \ntype: domain\n\n**cited_domain_subdomains**: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match.  \ntype: string\n\n**cited_url_exact**: The URL of a page that was used to generate the response.  \ntype: string\n\n**cited_url_prefix**: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match.  \ntype: string\n\n**inline_domain**: The domain of a page linked in the response text.  \ntype: domain\n\n**inline_domain_subdomains**: The domain of a page linked in the response text. Any subdomain of the given domain will also match.  \ntype: string\n\n**inline_url_exact**: The URL of a page linked in the response text.  \ntype: string\n\n**inline_url_prefix**: The URL of a page linked in the response text. Any URL that starts with this prefix will match.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**sponsored_advertiser**: The advertiser name shown on a sponsored result.  \ntype: string\n\n**sponsored_description**: The description of a sponsored result.  \ntype: string\n\n**sponsored_domain**: The domain of a sponsored result.  \ntype: domain\n\n**sponsored_domain_subdomains**: The domain of a sponsored result, including any of its subdomains.  \ntype: string\n\n**sponsored_kind**: The sponsored result type. Allowed values: `ad`, `product`.  \ntype: string\n\n**sponsored_result**: Whether the response contains a sponsored result. This field only supports the `empty` operator and its negation.  \ntype: string\n\n**sponsored_title**: The title of a sponsored result.  \ntype: string\n\n**sponsored_url_exact**: The exact URL of a sponsored result.  \ntype: string\n\n**sponsored_url_prefix**: The URL prefix of a sponsored result.  \ntype: string\n\n**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.  \ntype: string"
                  },
                  "report_id": {
                    "type": "string",
                    "description": "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#/...`"
                  },
                  "brands": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of brand names and websites to search for.",
                    "default": []
                  },
                  "competitors": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of competitor names and websites to search for.",
                    "default": []
                  },
                  "content_filter": {
                    "properties": {
                      "include": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Only show results containing at least one of these exact phrases."
                      },
                      "exclude": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Hide results containing any of these exact phrases."
                      }
                    },
                    "type": "object",
                    "description": "Optional phrases used to include or exclude results based on their content."
                  },
                  "data_source": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "chatgpt", "google_ai_overviews", "google_ai_mode",
                        "gemini", "perplexity", "copilot", "claude", "grok",
                        "google_ai_overviews_keywords",
                        "google_ai_mode_keywords"
                      ]
                    },
                    "type": "array",
                    "description": "A list of chatbot models. All models can be combined with each other. `claude` module supports only custom prompts.\nThe `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."
                  },
                  "country": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar",
                        "as", "at", "au", "aw", "az", "ba", "bb", "bd", "be",
                        "bf", "bg", "bh", "bi", "bj", "bn", "bo", "br", "bs",
                        "bt", "bw", "by", "bz", "ca", "cd", "cf", "cg", "ch",
                        "ci", "ck", "cl", "cm", "cn", "co", "cr", "cu", "cv",
                        "cy", "cz", "de", "dj", "dk", "dm", "do", "dz", "ec",
                        "ee", "eg", "es", "et", "fi", "fj", "fm", "fo", "fr",
                        "ga", "gb", "gd", "ge", "gf", "gg", "gh", "gi", "gl",
                        "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gy", "hk",
                        "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in",
                        "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg",
                        "kh", "ki", "kn", "kr", "kw", "ky", "kz", "la", "lb",
                        "lc", "li", "lk", "ls", "lt", "lu", "lv", "ly", "ma",
                        "mc", "md", "me", "mg", "mk", "ml", "mm", "mn", "mq",
                        "mr", "ms", "mt", "mu", "mv", "mw", "mx", "my", "mz",
                        "na", "nc", "ne", "ng", "ni", "nl", "no", "np", "nr",
                        "nu", "nz", "om", "pa", "pe", "pf", "pg", "ph", "pk",
                        "pl", "pn", "pr", "ps", "pt", "py", "qa", "re", "ro",
                        "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg", "sh",
                        "si", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv",
                        "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to",
                        "tr", "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz",
                        "vc", "ve", "vg", "vi", "vn", "vu", "ws", "ye", "yt",
                        "za", "zm", "zw"
                      ]
                    },
                    "type": "array",
                    "description": "A list of two-letter country codes (ISO 3166-1 alpha-2).",
                    "default": []
                  },
                  "prompts": {
                    "type": "string",
                    "enum": [ "ahrefs", "custom" ],
                    "description": "The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided."
                  },
                  "limit": {
                    "type": "integer",
                    "description": "The number of results to return.",
                    "default": 1000
                  },
                  "date": {
                    "type": "string",
                    "format": "date",
                    "description": "The date to search for in YYYY-MM-DD format."
                  },
                  "tracked_urls": {
                    "items": { "type": "string", "title": "tracked_urls" },
                    "type": "array",
                    "minItems": 1,
                    "description": "A list of tracked page URLs. When provided, the response includes rows with zero citations for any tracked URLs that have no data."
                  },
                  "tags_filter": {
                    "properties": {},
                    "type": "object",
                    "description": "A filter expression for prompt tags. Requires `report_id`. Uses [filter syntax](https://docs.ahrefs.com/api/docs/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.",
                    "examples": [
                      {
                        "or": [
                          { "field": "tag", "is": [ "eq", "branded" ] },
                          { "field": "tag", "is": [ "eq", "competitor" ] }
                        ]
                      }
                    ]
                  },
                  "brand_filter": {
                    "properties": {},
                    "type": "object",
                    "description": "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). \nUses [filter syntax](https://docs.ahrefs.com/api/docs/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).",
                    "examples": [
                      {
                        "and": [
                          {
                            "field": "brand_name",
                            "is": [ "eq", "mentioned" ]
                          },
                          {
                            "or": [
                              {
                                "field": "page_status",
                                "is": [ "eq", "cited" ]
                              },
                              {
                                "field": "page_status",
                                "is": [ "eq", "found_but_not_cited" ]
                              }
                            ]
                          }
                        ]
                      }
                    ]
                  },
                  "volume_range": {
                    "properties": {
                      "from": { "type": "integer", "minimum": 0 },
                      "to": { "type": "integer", "minimum": 0 }
                    },
                    "type": "object",
                    "description": "The volume range to filter by."
                  },
                  "output": {
                    "type": "string",
                    "enum": [ "json", "php" ],
                    "description": "The output format."
                  }
                },
                "type": "object",
                "required": [ "select", "data_source" ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/cited-pages" }
              },
              "application/xml": {
                "schema": { "$ref": "#/components/schemas/cited-pages" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      }
    },
    "/cited-domains": {
      "get": {
        "tags": [ "AI visibility", "MCP" ],
        "summary": "Cited Domains",
        "description": ">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.",
        "operationId": "cited-domains",
        "parameters": [
          {
            "description": "A comma-separated list of fields to return.\n\n- `domain`\n- `pages`\n- `responses`",
            "required": true,
            "explode": false,
            "schema": { "type": "string" },
            "name": "select",
            "in": "query"
          },
          {
            "description": "The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter).\n\n**cited_domain**: The domain of a page that was used to generate the response.  \ntype: domain\n\n**cited_domain_subdomains**: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match.  \ntype: string\n\n**cited_url_exact**: The URL of a page that was used to generate the response.  \ntype: string\n\n**cited_url_prefix**: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match.  \ntype: string\n\n**inline_domain**: The domain of a page linked in the response text.  \ntype: domain\n\n**inline_domain_subdomains**: The domain of a page linked in the response text. Any subdomain of the given domain will also match.  \ntype: string\n\n**inline_url_exact**: The URL of a page linked in the response text.  \ntype: string\n\n**inline_url_prefix**: The URL of a page linked in the response text. Any URL that starts with this prefix will match.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**sponsored_advertiser**: The advertiser name shown on a sponsored result.  \ntype: string\n\n**sponsored_description**: The description of a sponsored result.  \ntype: string\n\n**sponsored_domain**: The domain of a sponsored result.  \ntype: domain\n\n**sponsored_domain_subdomains**: The domain of a sponsored result, including any of its subdomains.  \ntype: string\n\n**sponsored_kind**: The sponsored result type. Allowed values: `ad`, `product`.  \ntype: string\n\n**sponsored_result**: Whether the response contains a sponsored result. This field only supports the `empty` operator and its negation.  \ntype: string\n\n**sponsored_title**: The title of a sponsored result.  \ntype: string\n\n**sponsored_url_exact**: The exact URL of a sponsored result.  \ntype: string\n\n**sponsored_url_prefix**: The URL prefix of a sponsored result.  \ntype: string\n\n**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.  \ntype: string",
            "required": false,
            "explode": false,
            "schema": { "type": "string" },
            "name": "where",
            "in": "query"
          },
          {
            "description": "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#/...`",
            "required": false,
            "explode": false,
            "schema": { "type": "string" },
            "name": "report_id",
            "in": "query"
          },
          {
            "description": "A comma-separated list of brands to search for. At least one of brand, competitors, market or where should not be empty.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "default": "" },
            "name": "brand",
            "in": "query"
          },
          {
            "description": "A comma-separated list of competitors of your brands.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "default": "" },
            "name": "competitors",
            "in": "query"
          },
          {
            "description": "A comma-separated list of chatbot models. All models can be combined with each other. `claude` module supports only custom prompts.\nThe `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.",
            "required": true,
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "chatgpt", "google_ai_overviews", "google_ai_mode", "gemini",
                "perplexity", "copilot", "claude", "grok",
                "google_ai_overviews_keywords", "google_ai_mode_keywords"
              ],
              "examples": [ "chatgpt,perplexity" ]
            },
            "name": "data_source",
            "in": "query"
          },
          {
            "description": "A comma-separated list of two-letter country codes (ISO 3166-1 alpha-2).",
            "required": false,
            "explode": false,
            "schema": {
              "type": "string",
              "enum": [
                "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar", "as",
                "at", "au", "aw", "az", "ba", "bb", "bd", "be", "bf", "bg",
                "bh", "bi", "bj", "bn", "bo", "br", "bs", "bt", "bw", "by",
                "bz", "ca", "cd", "cf", "cg", "ch", "ci", "ck", "cl", "cm",
                "cn", "co", "cr", "cu", "cv", "cy", "cz", "de", "dj", "dk",
                "dm", "do", "dz", "ec", "ee", "eg", "es", "et", "fi", "fj",
                "fm", "fo", "fr", "ga", "gb", "gd", "ge", "gf", "gg", "gh",
                "gi", "gl", "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gy",
                "hk", "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in",
                "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg", "kh",
                "ki", "kn", "kr", "kw", "ky", "kz", "la", "lb", "lc", "li",
                "lk", "ls", "lt", "lu", "lv", "ly", "ma", "mc", "md", "me",
                "mg", "mk", "ml", "mm", "mn", "mq", "mr", "ms", "mt", "mu",
                "mv", "mw", "mx", "my", "mz", "na", "nc", "ne", "ng", "ni",
                "nl", "no", "np", "nr", "nu", "nz", "om", "pa", "pe", "pf",
                "pg", "ph", "pk", "pl", "pn", "pr", "ps", "pt", "py", "qa",
                "re", "ro", "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg",
                "sh", "si", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv",
                "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to", "tr",
                "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz", "vc", "ve",
                "vg", "vi", "vn", "vu", "ws", "ye", "yt", "za", "zm", "zw"
              ],
              "default": ""
            },
            "name": "country",
            "in": "query"
          },
          {
            "description": "The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "enum": [ "ahrefs", "custom" ] },
            "name": "prompts",
            "in": "query"
          },
          {
            "description": "The number of results to return.",
            "required": false,
            "explode": false,
            "schema": { "type": "integer", "default": 1000 },
            "name": "limit",
            "in": "query"
          },
          {
            "description": "The date to search for in YYYY-MM-DD format.",
            "required": false,
            "explode": false,
            "schema": { "type": "string", "format": "date" },
            "name": "date",
            "in": "query"
          },
          { "$ref": "#/components/parameters/output_json_php" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/cited-domains" }
              },
              "application/xml": {
                "schema": { "$ref": "#/components/schemas/cited-domains" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      },
      "post": {
        "tags": [ "AI visibility", "MCP" ],
        "summary": "Cited Domains",
        "description": ">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.",
        "operationId": "cited-domains",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "select": {
                    "items": { "type": "string" },
                    "type": "array",
                    "description": "A list of fields to return.\n\n- `domain`\n- `pages`\n- `responses`",
                    "examples": [ [ "field_a", "field_b" ] ]
                  },
                  "where": {
                    "type": "object",
                    "description": "The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter).\n\n**cited_domain**: The domain of a page that was used to generate the response.  \ntype: domain\n\n**cited_domain_subdomains**: The domain of a page that was used to generate the response. Any subdomain of the given domain will also match.  \ntype: string\n\n**cited_url_exact**: The URL of a page that was used to generate the response.  \ntype: string\n\n**cited_url_prefix**: The URL of a page that was used to generate the response. Any URL that starts with this prefix will match.  \ntype: string\n\n**inline_domain**: The domain of a page linked in the response text.  \ntype: domain\n\n**inline_domain_subdomains**: The domain of a page linked in the response text. Any subdomain of the given domain will also match.  \ntype: string\n\n**inline_url_exact**: The URL of a page linked in the response text.  \ntype: string\n\n**inline_url_prefix**: The URL of a page linked in the response text. Any URL that starts with this prefix will match.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**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.  \ntype: string\n\n**sponsored_advertiser**: The advertiser name shown on a sponsored result.  \ntype: string\n\n**sponsored_description**: The description of a sponsored result.  \ntype: string\n\n**sponsored_domain**: The domain of a sponsored result.  \ntype: domain\n\n**sponsored_domain_subdomains**: The domain of a sponsored result, including any of its subdomains.  \ntype: string\n\n**sponsored_kind**: The sponsored result type. Allowed values: `ad`, `product`.  \ntype: string\n\n**sponsored_result**: Whether the response contains a sponsored result. This field only supports the `empty` operator and its negation.  \ntype: string\n\n**sponsored_title**: The title of a sponsored result.  \ntype: string\n\n**sponsored_url_exact**: The exact URL of a sponsored result.  \ntype: string\n\n**sponsored_url_prefix**: The URL prefix of a sponsored result.  \ntype: string\n\n**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.  \ntype: string"
                  },
                  "report_id": {
                    "type": "string",
                    "description": "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#/...`"
                  },
                  "brands": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of brand names and websites to search for.",
                    "default": []
                  },
                  "competitors": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of competitor names and websites to search for.",
                    "default": []
                  },
                  "content_filter": {
                    "properties": {
                      "include": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Only show results containing at least one of these exact phrases."
                      },
                      "exclude": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Hide results containing any of these exact phrases."
                      }
                    },
                    "type": "object",
                    "description": "Optional phrases used to include or exclude results based on their content."
                  },
                  "data_source": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "chatgpt", "google_ai_overviews", "google_ai_mode",
                        "gemini", "perplexity", "copilot", "claude", "grok",
                        "google_ai_overviews_keywords",
                        "google_ai_mode_keywords"
                      ]
                    },
                    "type": "array",
                    "description": "A list of chatbot models. All models can be combined with each other. `claude` module supports only custom prompts.\nThe `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."
                  },
                  "country": {
                    "items": {
                      "type": "string",
                      "enum": [
                        "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar",
                        "as", "at", "au", "aw", "az", "ba", "bb", "bd", "be",
                        "bf", "bg", "bh", "bi", "bj", "bn", "bo", "br", "bs",
                        "bt", "bw", "by", "bz", "ca", "cd", "cf", "cg", "ch",
                        "ci", "ck", "cl", "cm", "cn", "co", "cr", "cu", "cv",
                        "cy", "cz", "de", "dj", "dk", "dm", "do", "dz", "ec",
                        "ee", "eg", "es", "et", "fi", "fj", "fm", "fo", "fr",
                        "ga", "gb", "gd", "ge", "gf", "gg", "gh", "gi", "gl",
                        "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gy", "hk",
                        "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in",
                        "iq", "is", "it", "je", "jm", "jo", "jp", "ke", "kg",
                        "kh", "ki", "kn", "kr", "kw", "ky", "kz", "la", "lb",
                        "lc", "li", "lk", "ls", "lt", "lu", "lv", "ly", "ma",
                        "mc", "md", "me", "mg", "mk", "ml", "mm", "mn", "mq",
                        "mr", "ms", "mt", "mu", "mv", "mw", "mx", "my", "mz",
                        "na", "nc", "ne", "ng", "ni", "nl", "no", "np", "nr",
                        "nu", "nz", "om", "pa", "pe", "pf", "pg", "ph", "pk",
                        "pl", "pn", "pr", "ps", "pt", "py", "qa", "re", "ro",
                        "rs", "ru", "rw", "sa", "sb", "sc", "se", "sg", "sh",
                        "si", "sk", "sl", "sm", "sn", "so", "sr", "st", "sv",
                        "td", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to",
                        "tr", "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz",
                        "vc", "ve", "vg", "vi", "vn", "vu", "ws", "ye", "yt",
                        "za", "zm", "zw"
                      ]
                    },
                    "type": "array",
                    "description": "A list of two-letter country codes (ISO 3166-1 alpha-2).",
                    "default": []
                  },
                  "prompts": {
                    "type": "string",
                    "enum": [ "ahrefs", "custom" ],
                    "description": "The type of prompts to use. If not specified, both will be used. Custom prompts require a report_id to be provided."
                  },
                  "limit": {
                    "type": "integer",
                    "description": "The number of results to return.",
                    "default": 1000
                  },
                  "date": {
                    "type": "string",
                    "format": "date",
                    "description": "The date to search for in YYYY-MM-DD format."
                  },
                  "tags_filter": {
                    "properties": {},
                    "type": "object",
                    "description": "A filter expression for prompt tags. Requires `report_id`. Uses [filter syntax](https://docs.ahrefs.com/api/docs/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.",
                    "examples": [
                      {
                        "or": [
                          { "field": "tag", "is": [ "eq", "branded" ] },
                          { "field": "tag", "is": [ "eq", "competitor" ] }
                        ]
                      }
                    ]
                  },
                  "brand_filter": {
                    "properties": {},
                    "type": "object",
                    "description": "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). \nUses [filter syntax](https://docs.ahrefs.com/api/docs/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).",
                    "examples": [
                      {
                        "and": [
                          {
                            "field": "brand_name",
                            "is": [ "eq", "mentioned" ]
                          },
                          {
                            "or": [
                              {
                                "field": "page_status",
                                "is": [ "eq", "cited" ]
                              },
                              {
                                "field": "page_status",
                                "is": [ "eq", "found_but_not_cited" ]
                              }
                            ]
                          }
                        ]
                      }
                    ]
                  },
                  "volume_range": {
                    "properties": {
                      "from": { "type": "integer", "minimum": 0 },
                      "to": { "type": "integer", "minimum": 0 }
                    },
                    "type": "object",
                    "description": "The volume range to filter by."
                  },
                  "output": {
                    "type": "string",
                    "enum": [ "json", "php" ],
                    "description": "The output format."
                  }
                },
                "type": "object",
                "required": [ "select", "data_source" ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/cited-domains" }
              },
              "application/xml": {
                "schema": { "$ref": "#/components/schemas/cited-domains" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      }
    },
    "/web-pages": {
      "post": {
        "tags": [ "Web visibility", "MCP", "Enterprise only" ],
        "summary": "Web Pages",
        "description": "Returns web pages that mention the requested brands or competitors. Brand mentions are matched against page titles and content from Ahrefs' web index.",
        "operationId": "web-pages",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "select": {
                    "items": { "type": "string" },
                    "type": "array",
                    "description": "A list of fields to return.\n\n- `content`\n- `domain_rating`\n- `referring_domains`\n- `title`\n- `traffic`\n- `traffic_value`\n- `url`",
                    "examples": [ [ "field_a", "field_b" ] ]
                  },
                  "where": {
                    "type": "object",
                    "description": "The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the `select` parameter).\n\n**content**: An excerpt of the page content containing the mention.  \ntype: string\n\n**title**: The title of the page.  \ntype: string\n\n**url**: The URL of the page mentioning a requested brand or competitor.  \ntype: url"
                  },
                  "report_id": {
                    "type": "string",
                    "description": "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#/...`"
                  },
                  "brands": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of brand names and websites to find mentions of on web pages.",
                    "default": []
                  },
                  "competitors": {
                    "items": {
                      "anyOf": [
                        { "required": [ "names" ] },
                        { "required": [ "url_groups" ] }
                      ],
                      "properties": {
                        "names": {
                          "items": { "type": "string" },
                          "type": "array",
                          "description": "The names of the brand/competitor",
                          "examples": [ [ "ahrefs", "ahrefs seo" ] ]
                        },
                        "url_groups": {
                          "items": {
                            "properties": {
                              "target": {
                                "type": "string",
                                "format": "domain",
                                "description": "The domain of the target",
                                "examples": [ "ahrefs.com" ]
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "url", "path", "domain", "subdomains"
                                ],
                                "description": "Scope of the target."
                              }
                            },
                            "type": "object",
                            "required": [ "target", "scope" ]
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array",
                    "description": "A list of competitor names and websites to find mentions of on web pages.",
                    "default": []
                  },
                  "content_filter": {
                    "properties": {
                      "include": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Only show results containing at least one of these exact phrases."
                      },
                      "exclude": {
                        "items": { "type": "string" },
                        "type": "array",
                        "description": "Hide results containing any of these exact phrases."
                      }
                    },
                    "type": "object",
                    "description": "Optional phrases used to include or exclude results based on their content."
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1000,
                    "description": "The number of web pages to return.",
                    "default": 1000
                  },
                  "order_by": {
                    "type": "string",
                    "enum": [ "relevance", "traffic" ],
                    "description": "How to order the web pages.",
                    "default": "relevance"
                  },
                  "page_type": {
                    "type": "string",
                    "enum": [ "all_pages", "news" ],
                    "description": "Whether to return all web pages or only news pages.",
                    "default": "all_pages"
                  },
                  "publication_type": {
                    "type": "string",
                    "enum": [ "all", "published_once", "republished" ],
                    "description": "Whether to return all pages, pages published once, or republished pages.",
                    "default": "all"
                  },
                  "date_from": {
                    "type": "string",
                    "format": "date",
                    "description": "The start of the publication-date range, in YYYY-MM-DD format. Requires `date_to`."
                  },
                  "date_to": {
                    "type": "string",
                    "format": "date",
                    "description": "The inclusive end of the publication-date range, in YYYY-MM-DD format. Requires `date_from`."
                  },
                  "platform": {
                    "type": "string",
                    "enum": [
                      "all", "blogs", "wordpress", "ecommerce", "cms",
                      "message-boards", "wikis"
                    ],
                    "description": "The platform or technology used by the page.",
                    "default": "all"
                  },
                  "language": {
                    "type": "string",
                    "enum": [
                      "all", "en", "es", "ru", "zh-cn", "ja", "af", "sq",
                      "ar", "bn", "bg", "zh-tw", "hr", "cs", "da", "nl",
                      "et", "fa", "fi", "fr", "de", "el", "gu", "he", "hi",
                      "hu", "id", "it", "kn", "ko", "lv", "lt", "mk", "ml",
                      "mr", "ne", "no", "pa", "pl", "pt", "ro", "sk", "sl",
                      "so", "sw", "sv", "tl", "ta", "te", "th", "tr", "uk",
                      "ur", "vi"
                    ],
                    "description": "The language of the page.",
                    "default": "all"
                  },
                  "output": {
                    "type": "string",
                    "enum": [ "json", "csv", "xml", "php" ],
                    "description": "The output format."
                  }
                },
                "type": "object",
                "required": [ "select" ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/web-pages" }
              },
              "application/xml": {
                "schema": { "$ref": "#/components/schemas/web-pages" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/error_400" },
          "401": { "$ref": "#/components/responses/error_401" },
          "403": { "$ref": "#/components/responses/error_403" },
          "429": { "$ref": "#/components/responses/error_429" },
          "500": { "$ref": "#/components/responses/error_500" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error_response": {
        "properties": { "error": { "type": "string" } },
        "type": "object",
        "xml": { "name": "AhrefsApiResponse" }
      },
      "ai-responses": {
        "properties": {
          "ai_responses": {
            "items": {
              "properties": {
                "brand_sentiment": {
                  "items": {
                    "properties": {
                      "brand": {
                        "type": "string",
                        "description": "The tracked brand mentioned."
                      },
                      "sentiment": {
                        "type": [ "string", "null" ],
                        "enum": [
                          "positive", "neutral", "negative", "mixed", null
                        ],
                        "description": "How the response talks about the brand at this mention. Null when it isn't available."
                      },
                      "aspect": {
                        "type": [ "string", "null" ],
                        "enum": [
                          "features_specs", "performance_effectiveness",
                          "price_value", "reputation_popularity",
                          "quality_reliability", "design_comfort",
                          "usability_compatibility", "availability_delivery",
                          "safety_health", "service_support", "general", null
                        ],
                        "description": "What the mention is about, such as price or quality. Null when it isn't available."
                      },
                      "snippet": {
                        "type": [ "string", "null" ],
                        "description": "The sentence around the mention. Null when it can't be found in the response."
                      }
                    },
                    "type": "object"
                  },
                  "type": "array",
                  "title": "brand_sentiment",
                  "description": "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."
                },
                "country": {
                  "type": "string",
                  "title": "country",
                  "description": "The country of the question."
                },
                "data_source": {
                  "type": "string",
                  "title": "data_source",
                  "description": "The chatbot model that generated the response."
                },
                "funnel_stage": {
                  "type": [ "string", "null" ],
                  "enum": [
                    "awareness", "consideration", "decision", "unclear", null
                  ],
                  "title": "funnel_stage",
                  "description": "The prompt's funnel stage. Null when no funnel stage is available."
                },
                "intent": {
                  "items": {
                    "type": "string",
                    "enum": [
                      "informational", "navigational", "transactional",
                      "branded", "commercial", "comparison", "how_to",
                      "local", "opinion", "recommendation"
                    ]
                  },
                  "type": "array",
                  "title": "intent",
                  "description": "The prompt's intent labels, including its primary intent, subtypes, and branded/local attributes. An empty array means no intent labels are available."
                },
                "last_updated": {
                  "type": "string",
                  "format": "date",
                  "title": "last_updated",
                  "description": "The date when the data was last updated."
                },
                "links": {
                  "items": {
                    "properties": {
                      "url": { "type": "string" },
                      "title": { "type": [ "string", "null" ] }
                    },
                    "type": "object"
                  },
                  "type": "array",
                  "title": "links",
                  "description": "(10 units) The links used for the response."
                },
                "question": {
                  "type": "string",
                  "title": "question",
                  "description": "The question asked by the user."
                },
                "response": {
                  "type": "string",
                  "title": "response",
                  "description": "(10 units) The response from the model."
                },
                "search_queries": {
                  "items": { "type": "string" },
                  "type": "array",
                  "title": "search_queries",
                  "description": "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."
                },
                "status": {
                  "type": [ "string", "null" ],
                  "enum": [ "new", "lost", "no_change", null ],
                  "title": "status",
                  "description": "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": {
                  "items": { "type": "string" },
                  "type": "array",
                  "title": "tags",
                  "description": "Tags assigned to the query."
                },
                "volume": {
                  "type": "integer",
                  "title": "volume",
                  "description": "(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."
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object",
        "xml": { "name": "AhrefsApiResponse" }
      },
      "impressions-overview": {
        "properties": {
          "metrics": {
            "items": {
              "properties": {
                "brand": {
                  "type": "string",
                  "title": "brand",
                  "description": "Brand name (either your brand or a competitor provided in the request)."
                },
                "entity_type": {
                  "type": "string",
                  "enum": [ "aggregate", "target", "competitor" ],
                  "title": "entity_type",
                  "description": "Whether the row represents an aggregate, your target brand, or a competitor."
                },
                "no_tracked_brands": {
                  "type": "integer",
                  "title": "no_tracked_brands",
                  "description": "Estimated impressions from responses related to the specified market that do not mention any provided brands (value is zero when `market` is not specified)."
                },
                "only_competitors_brands": {
                  "type": "integer",
                  "title": "only_competitors_brands",
                  "description": "Estimated impressions from responses mentioning only competitor brands."
                },
                "only_target_brand": {
                  "type": "integer",
                  "title": "only_target_brand",
                  "description": "Estimated impressions from responses mentioning only your brand."
                },
                "target_and_competitors_brands": {
                  "type": "integer",
                  "title": "target_and_competitors_brands",
                  "description": "Estimated impressions from responses mentioning both your and competitor brands."
                },
                "total": {
                  "type": "integer",
                  "title": "total",
                  "description": "Total estimated impressions for your brand (includes both `only_target_brand` and `target_and_competitors_brands`)."
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object",
        "xml": { "name": "AhrefsApiResponse" }
      },
      "citations-overview": {
        "properties": {
          "metrics": {
            "items": {
              "properties": {
                "brand": {
                  "type": "string",
                  "title": "brand",
                  "description": "Brand name (either your brand or a competitor provided in the request)."
                },
                "entity_type": {
                  "type": "string",
                  "enum": [ "aggregate", "target", "competitor" ],
                  "title": "entity_type",
                  "description": "Whether the row represents an aggregate, your target brand, or a competitor."
                },
                "no_tracked_brands": {
                  "type": "integer",
                  "title": "no_tracked_brands",
                  "description": "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_brands": {
                  "type": "integer",
                  "title": "only_competitors_brands",
                  "description": "Estimated citations from responses mentioning only competitors' brand URLs."
                },
                "only_target_brand": {
                  "type": "integer",
                  "title": "only_target_brand",
                  "description": "Estimated citations from responses mentioning only your brand URLs."
                },
                "target_and_competitors_brands": {
                  "type": "integer",
                  "title": "target_and_competitors_brands",
                  "description": "Estimated citations from responses mentioning both your and competitors' brand URLs."
                },
                "total": {
                  "type": "integer",
                  "title": "total",
                  "description": "Total estimated citations for your brand URLs (includes both `only_target_brand` and `target_and_competitors_brands`)."
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object",
        "xml": { "name": "AhrefsApiResponse" }
      },
      "mentions-overview": {
        "properties": {
          "metrics": {
            "items": {
              "properties": {
                "brand": {
                  "type": "string",
                  "title": "brand",
                  "description": "Brand name (either your brand or a competitor provided in the request)."
                },
                "entity_type": {
                  "type": "string",
                  "enum": [ "aggregate", "target", "competitor" ],
                  "title": "entity_type",
                  "description": "Whether the row represents an aggregate, your target brand, or a competitor."
                },
                "no_tracked_brands": {
                  "type": "integer",
                  "title": "no_tracked_brands",
                  "description": "Estimated mentions from responses related to the specified market that do not mention any provided brands (value is zero when `market` is not specified)."
                },
                "only_competitors_brands": {
                  "type": "integer",
                  "title": "only_competitors_brands",
                  "description": "Estimated mentions from responses mentioning only competitor brands."
                },
                "only_target_brand": {
                  "type": "integer",
                  "title": "only_target_brand",
                  "description": "Estimated mentions from responses mentioning only your brand."
                },
                "target_and_competitors_brands": {
                  "type": "integer",
                  "title": "target_and_competitors_brands",
                  "description": "Estimated mentions from responses mentioning both your and competitor brands."
                },
                "total": {
                  "type": "integer",
                  "title": "total",
                  "description": "Total estimated mentions for your brand (includes both `only_target_brand` and `target_and_competitors_brands`)."
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object",
        "xml": { "name": "AhrefsApiResponse" }
      },
      "sov-overview": {
        "properties": {
          "metrics": {
            "items": {
              "properties": {
                "brand": {
                  "type": "string",
                  "title": "brand",
                  "description": "Brand name (either your brand or a competitor provided in the request)."
                },
                "entity_type": {
                  "type": "string",
                  "enum": [ "aggregate", "target", "competitor" ],
                  "title": "entity_type",
                  "description": "Whether the row represents an aggregate, your target brand, or a competitor."
                },
                "share_of_voice": {
                  "type": "number",
                  "format": "float",
                  "title": "share_of_voice",
                  "description": "Estimated share of voice for your brand."
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object",
        "xml": { "name": "AhrefsApiResponse" }
      },
      "impressions-history": {
        "properties": {
          "metrics": {
            "items": {
              "properties": {
                "date": {
                  "type": "string",
                  "format": "date",
                  "title": "date",
                  "description": ""
                },
                "impressions": {
                  "type": "integer",
                  "title": "impressions",
                  "description": "Estimated impressions from responses mentioning the brand."
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object",
        "xml": { "name": "AhrefsApiResponse" }
      },
      "citations-history": {
        "properties": {
          "metrics": {
            "items": {
              "properties": {
                "citations": {
                  "type": "integer",
                  "title": "citations",
                  "description": "Estimated citations from responses mentioning the brand URLs."
                },
                "date": {
                  "type": "string",
                  "format": "date",
                  "title": "date",
                  "description": ""
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object",
        "xml": { "name": "AhrefsApiResponse" }
      },
      "mentions-history": {
        "properties": {
          "metrics": {
            "items": {
              "properties": {
                "date": {
                  "type": "string",
                  "format": "date",
                  "title": "date",
                  "description": ""
                },
                "mentions": {
                  "type": "integer",
                  "title": "mentions",
                  "description": "Estimated mentions from responses mentioning the brand."
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object",
        "xml": { "name": "AhrefsApiResponse" }
      },
      "sov-history": {
        "properties": {
          "metrics": {
            "items": {
              "properties": {
                "date": {
                  "type": "string",
                  "format": "date",
                  "title": "date",
                  "description": ""
                },
                "share_of_voice": {
                  "items": {
                    "properties": {
                      "brand": { "type": "string" },
                      "entity_type": {
                        "type": "string",
                        "enum": [ "aggregate", "target", "competitor" ]
                      },
                      "share_of_voice": {
                        "type": "number",
                        "format": "float"
                      }
                    },
                    "type": "object"
                  },
                  "type": "array",
                  "title": "share_of_voice",
                  "description": "(1 unit per brand) Estimated share of voice for the brand."
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object",
        "xml": { "name": "AhrefsApiResponse" }
      },
      "topics": {
        "properties": {
          "topics": {
            "items": {
              "properties": {
                "country": {
                  "type": "string",
                  "title": "country",
                  "description": "The country associated with the topic. When no parent topic was identified, this is the only selected country, or `all` if multiple or all countries were selected."
                },
                "mentions": {
                  "items": {
                    "properties": {
                      "entity": {
                        "type": "string",
                        "description": "The tracked brand or competitor."
                      },
                      "responses": {
                        "type": "integer",
                        "description": "The number of AI responses that mention the entity."
                      }
                    },
                    "type": "object"
                  },
                  "type": "array",
                  "title": "mentions",
                  "description": "Response counts for the tracked brand and each competitor."
                },
                "responses": {
                  "type": "integer",
                  "title": "responses",
                  "description": "The number of AI responses associated with the topic."
                },
                "topic": {
                  "type": [ "string", "null" ],
                  "title": "topic",
                  "description": "The parent topic. Null when no parent topic was identified."
                },
                "volume": {
                  "type": [ "integer", "null" ],
                  "title": "volume",
                  "description": "The topic's estimated monthly search volume."
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object",
        "xml": { "name": "AhrefsApiResponse" }
      },
      "cited-pages": {
        "properties": {
          "pages": {
            "items": {
              "properties": {
                "mentions": {
                  "items": { "properties": {}, "type": "object" },
                  "type": "array",
                  "title": "mentions",
                  "description": "Deprecated on 2026-02-10."
                },
                "responses": {
                  "type": "integer",
                  "title": "responses",
                  "description": "The number of responses that cited the page."
                },
                "title": {
                  "type": [ "string", "null" ],
                  "title": "title",
                  "description": "The page title as shown in the AI response citation, or the crawled page title when no response recorded one. `null` if neither is known."
                },
                "url": {
                  "type": "string",
                  "title": "url",
                  "description": "The URL of the cited page."
                },
                "volume": {
                  "type": "integer",
                  "title": "volume",
                  "description": "Deprecated on 2026-03-24."
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object",
        "xml": { "name": "AhrefsApiResponse" }
      },
      "cited-domains": {
        "properties": {
          "domains": {
            "items": {
              "properties": {
                "domain": {
                  "type": "string",
                  "title": "domain",
                  "description": "The cited domain name."
                },
                "mentions": {
                  "items": { "properties": {}, "type": "object" },
                  "type": "array",
                  "title": "mentions",
                  "description": "Deprecated on 2026-02-10."
                },
                "pages": {
                  "type": "integer",
                  "title": "pages",
                  "description": "The number of unique pages from the domain that were cited in the responses."
                },
                "responses": {
                  "type": "integer",
                  "title": "responses",
                  "description": "The number of responses that cited the domain."
                },
                "volume": {
                  "type": "integer",
                  "title": "volume",
                  "description": "Deprecated on 2026-03-24."
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object",
        "xml": { "name": "AhrefsApiResponse" }
      },
      "web-pages": {
        "properties": {
          "pages": {
            "items": {
              "properties": {
                "content": {
                  "type": "string",
                  "title": "content",
                  "description": "An excerpt of the page content containing the mention."
                },
                "domain_rating": {
                  "type": "integer",
                  "title": "domain_rating",
                  "description": "The Domain Rating of the page's domain."
                },
                "referring_domains": {
                  "type": [ "integer", "null" ],
                  "title": "referring_domains",
                  "description": "The number of unique domains linking to the page."
                },
                "title": {
                  "type": "string",
                  "title": "title",
                  "description": "The title of the page."
                },
                "traffic": {
                  "type": [ "number", "null" ],
                  "format": "float",
                  "title": "traffic",
                  "description": "The page's estimated monthly organic search traffic."
                },
                "traffic_value": {
                  "type": "number",
                  "format": "float",
                  "title": "traffic_value",
                  "description": "The estimated monthly value of the page's organic search traffic, in USD."
                },
                "url": {
                  "type": "string",
                  "format": "url",
                  "title": "url",
                  "description": "The URL of the page mentioning a requested brand or competitor."
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object",
        "xml": { "name": "AhrefsApiResponse" }
      }
    },
    "responses": {
      "error_400": {
        "description": "Bad Request",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error_response" }
          },
          "application/xml": {
            "schema": { "$ref": "#/components/schemas/Error_response" }
          }
        }
      },
      "error_401": {
        "description": "Unauthorized",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error_response" }
          },
          "application/xml": {
            "schema": { "$ref": "#/components/schemas/Error_response" }
          }
        }
      },
      "error_403": {
        "description": "Forbidden",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error_response" }
          },
          "application/xml": {
            "schema": { "$ref": "#/components/schemas/Error_response" }
          }
        }
      },
      "error_429": {
        "description": "Too Many Requests",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error_response" }
          },
          "application/xml": {
            "schema": { "$ref": "#/components/schemas/Error_response" }
          }
        }
      },
      "error_500": {
        "description": "Internal Error",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error_response" }
          },
          "application/xml": {
            "schema": { "$ref": "#/components/schemas/Error_response" }
          }
        }
      }
    },
    "parameters": {
      "output_json_php": {
        "description": "The output format.",
        "required": false,
        "explode": false,
        "schema": { "type": "string", "enum": [ "json", "php" ] },
        "name": "output",
        "in": "query"
      },
      "output": {
        "description": "The output format.",
        "required": false,
        "explode": false,
        "schema": {
          "type": "string",
          "enum": [ "json", "csv", "xml", "php" ]
        },
        "name": "output",
        "in": "query"
      }
    },
    "examples": {},
    "requestBodies": {},
    "headers": {},
    "securitySchemes": { "http": { "type": "http", "scheme": "bearer" } },
    "links": {},
    "callbacks": {},
    "pathItems": {},
    "mediaTypes": {}
  },
  "security": [ { "http": [ "read" ] } ],
  "tags": [
    { "name": "AI visibility" },
    { "name": "Search demand" },
    { "name": "Web visibility" },
    { "name": "Overview" },
    { "name": "Overview history" }
  ],
  "externalDocs": {
    "description": "",
    "url": "https://docs.ahrefs.com/docs/api/v3/"
  }
}