{ "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- `country`\n- `data_source`\n- `last_updated`\n- `links` (10 units)\n- `question`\n- `response`\n- `search_queries`\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**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**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. \ntype: string\n\n**topic**: The topic of the query. \ntype: string", "required": false, "explode": false, "schema": { "type": "string" }, "name": "where", "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": "AI visibility reports are switching to AI adjusted volume. It better estimates demand for AI responses across chatbots and AI search surfaces. It is calculated by adjusting Google search volume for each AI platform’s estimated usage compared with Google. This param will be deprecated on August 31, 2026; all requests will use new AI adjusted volume.\n\n`ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform.\n\n`keyword_volume` - Previous calculation. Uses Google search volume without AI platform adjustment. Available until August 31, 2026.", "required": false, "explode": false, "schema": { "type": "string", "enum": [ "ask_volume", "keyword_volume" ], "default": "ask_volume" }, "name": "search_volume_type", "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": "A column to order the results by.", "required": false, "explode": false, "schema": { "type": "string", "enum": [ "relevance", "volume" ], "default": "relevance" }, "name": "order_by", "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": "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": "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 the niche markets of your brands. Deprecated on 2026-05-18, this parameter will have no effect shortly after this date.", "required": false, "explode": false, "schema": { "type": "string", "default": "" }, "name": "market", "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 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" }, { "$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": { "brand_filter": { "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" }, "to": { "type": "integer" } }, "type": "object", "description": "The volume range to filter by." }, "select": { "items": { "type": "string" }, "type": "array", "description": "A list of fields to return.\n\n- `country`\n- `data_source`\n- `last_updated`\n- `links` (10 units)\n- `question`\n- `response`\n- `search_queries`\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**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**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. \ntype: string\n\n**topic**: The topic of the query. \ntype: string" }, "tags_filter": { "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" ] } ] } ] }, "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." }, "search_volume_type": { "type": "string", "enum": [ "ask_volume", "keyword_volume" ], "description": "AI visibility reports are switching to AI adjusted volume. It better estimates demand for AI responses across chatbots and AI search surfaces. It is calculated by adjusting Google search volume for each AI platform’s estimated usage compared with Google. This param will be deprecated on August 31, 2026; all requests will use new AI adjusted volume.\n\n`ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform.\n\n`keyword_volume` - Previous calculation. Uses Google search volume without AI platform adjustment. Available until August 31, 2026.", "default": "ask_volume" }, "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": [] }, "order_by": { "type": "string", "enum": [ "relevance", "volume" ], "description": "A column to order the results by.", "default": "relevance" }, "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#/...`" }, "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." }, "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." }, "market": { "items": { "type": "string", "title": "markets" }, "type": "array", "minItems": 1, "description": "A list of the niche markets of your brands. Deprecated on 2026-05-18, this parameter will have no effect shortly after this date." }, "competitors": { "items": { "$ref": "#/components/schemas/entity" }, "type": "array", "description": "A list of competitor names and websites to search for.", "default": [] }, "brands": { "items": { "$ref": "#/components/schemas/entity" }, "type": "array", "description": "A list of brand names and websites to search for.", "default": [] }, "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": "Overview - 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": "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**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**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. \ntype: string\n\n**topic**: The topic of the query. \ntype: string", "required": false, "explode": false, "schema": { "type": "string" }, "name": "where", "in": "query" }, { "description": "A comma-separated list of fields to return.\n\n- `brand`\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": "AI visibility reports are switching to AI adjusted volume. It better estimates demand for AI responses across chatbots and AI search surfaces. It is calculated by adjusting Google search volume for each AI platform’s estimated usage compared with Google. This param will be deprecated on August 31, 2026; all requests will use new AI adjusted volume.\n\n`ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform.\n\n`keyword_volume` - Previous calculation. Uses Google search volume without AI platform adjustment. Available until August 31, 2026.", "required": false, "explode": false, "schema": { "type": "string", "enum": [ "ask_volume", "keyword_volume" ], "default": "ask_volume" }, "name": "search_volume_type", "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 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": "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": "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 the niche markets of your brands. Deprecated on 2026-05-18, this parameter will have no effect shortly after this date.", "required": false, "explode": false, "schema": { "type": "string", "default": "" }, "name": "market", "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 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" }, { "$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": "Overview - 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": { "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**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**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. \ntype: string\n\n**topic**: The topic of the query. \ntype: string" }, "select": { "items": { "type": "string" }, "type": "array", "description": "A list of fields to return.\n\n- `brand`\n- `no_tracked_brands`\n- `only_competitors_brands`\n- `only_target_brand`\n- `target_and_competitors_brands`\n- `total`", "examples": [ [ "field_a", "field_b" ] ] }, "tags_filter": { "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" ] } ] } ] }, "search_volume_type": { "type": "string", "enum": [ "ask_volume", "keyword_volume" ], "description": "AI visibility reports are switching to AI adjusted volume. It better estimates demand for AI responses across chatbots and AI search surfaces. It is calculated by adjusting Google search volume for each AI platform’s estimated usage compared with Google. This param will be deprecated on August 31, 2026; all requests will use new AI adjusted volume.\n\n`ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform.\n\n`keyword_volume` - Previous calculation. Uses Google search volume without AI platform adjustment. Available until August 31, 2026.", "default": "ask_volume" }, "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": [] }, "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#/...`" }, "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." }, "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." }, "market": { "items": { "type": "string", "title": "markets" }, "type": "array", "minItems": 1, "description": "A list of the niche markets of your brands. Deprecated on 2026-05-18, this parameter will have no effect shortly after this date." }, "competitors": { "items": { "$ref": "#/components/schemas/entity" }, "type": "array", "description": "A list of competitor names and websites to search for.", "default": [] }, "brands": { "items": { "$ref": "#/components/schemas/entity" }, "type": "array", "description": "A list of brand names and websites to search for.", "default": [] }, "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": "Overview - 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": { "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**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**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. \ntype: string\n\n**topic**: The topic of the query. \ntype: string" }, "select": { "items": { "type": "string" }, "type": "array", "description": "A list of fields to return.\n\n- `brand`\n- `no_tracked_brands`\n- `only_competitors_brands`\n- `only_target_brand`\n- `target_and_competitors_brands`\n- `total`", "examples": [ [ "field_a", "field_b" ] ] }, "tags_filter": { "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" ] } ] } ] }, "search_volume_type": { "type": "string", "enum": [ "ask_volume", "keyword_volume" ], "description": "AI visibility reports are switching to AI adjusted volume. It better estimates demand for AI responses across chatbots and AI search surfaces. It is calculated by adjusting Google search volume for each AI platform’s estimated usage compared with Google. This param will be deprecated on August 31, 2026; all requests will use new AI adjusted volume.\n\n`ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform.\n\n`keyword_volume` - Previous calculation. Uses Google search volume without AI platform adjustment. Available until August 31, 2026.", "default": "ask_volume" }, "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": [] }, "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#/...`" }, "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." }, "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." }, "market": { "items": { "type": "string", "title": "markets" }, "type": "array", "minItems": 1, "description": "A list of the niche markets of your brands. Deprecated on 2026-05-18, this parameter will have no effect shortly after this date." }, "competitors": { "items": { "$ref": "#/components/schemas/entity" }, "type": "array", "description": "A list of competitor names and websites to search for.", "default": [] }, "brands": { "items": { "$ref": "#/components/schemas/entity" }, "type": "array", "description": "A list of brand names and websites to search for.", "default": [] }, "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": "Overview - 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": "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**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**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. \ntype: string\n\n**topic**: The topic of the query. \ntype: string", "required": false, "explode": false, "schema": { "type": "string" }, "name": "where", "in": "query" }, { "description": "A comma-separated list of fields to return.\n\n- `brand`\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": "AI visibility reports are switching to AI adjusted volume. It better estimates demand for AI responses across chatbots and AI search surfaces. It is calculated by adjusting Google search volume for each AI platform’s estimated usage compared with Google. This param will be deprecated on August 31, 2026; all requests will use new AI adjusted volume.\n\n`ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform.\n\n`keyword_volume` - Previous calculation. Uses Google search volume without AI platform adjustment. Available until August 31, 2026.", "required": false, "explode": false, "schema": { "type": "string", "enum": [ "ask_volume", "keyword_volume" ], "default": "ask_volume" }, "name": "search_volume_type", "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 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": "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": "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 the niche markets of your brands. Deprecated on 2026-05-18, this parameter will have no effect shortly after this date.", "required": false, "explode": false, "schema": { "type": "string", "default": "" }, "name": "market", "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 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" }, { "$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": "Overview - 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": { "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**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**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. \ntype: string\n\n**topic**: The topic of the query. \ntype: string" }, "select": { "items": { "type": "string" }, "type": "array", "description": "A list of fields to return.\n\n- `brand`\n- `no_tracked_brands`\n- `only_competitors_brands`\n- `only_target_brand`\n- `target_and_competitors_brands`\n- `total`", "examples": [ [ "field_a", "field_b" ] ] }, "tags_filter": { "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" ] } ] } ] }, "search_volume_type": { "type": "string", "enum": [ "ask_volume", "keyword_volume" ], "description": "AI visibility reports are switching to AI adjusted volume. It better estimates demand for AI responses across chatbots and AI search surfaces. It is calculated by adjusting Google search volume for each AI platform’s estimated usage compared with Google. This param will be deprecated on August 31, 2026; all requests will use new AI adjusted volume.\n\n`ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform.\n\n`keyword_volume` - Previous calculation. Uses Google search volume without AI platform adjustment. Available until August 31, 2026.", "default": "ask_volume" }, "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": [] }, "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#/...`" }, "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." }, "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." }, "market": { "items": { "type": "string", "title": "markets" }, "type": "array", "minItems": 1, "description": "A list of the niche markets of your brands. Deprecated on 2026-05-18, this parameter will have no effect shortly after this date." }, "competitors": { "items": { "$ref": "#/components/schemas/entity" }, "type": "array", "description": "A list of competitor names and websites to search for.", "default": [] }, "brands": { "items": { "$ref": "#/components/schemas/entity" }, "type": "array", "description": "A list of brand names and websites to search for.", "default": [] }, "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": "Overview - 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**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**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. \ntype: string\n\n**topic**: The topic of the query. \ntype: string", "required": false, "explode": false, "schema": { "type": "string" }, "name": "where", "in": "query" }, { "description": "AI visibility reports are switching to AI adjusted volume. It better estimates demand for AI responses across chatbots and AI search surfaces. It is calculated by adjusting Google search volume for each AI platform’s estimated usage compared with Google. This param will be deprecated on August 31, 2026; all requests will use new AI adjusted volume.\n\n`ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform.\n\n`keyword_volume` - Previous calculation. Uses Google search volume without AI platform adjustment. Available until August 31, 2026.", "required": false, "explode": false, "schema": { "type": "string", "enum": [ "ask_volume", "keyword_volume" ], "default": "ask_volume" }, "name": "search_volume_type", "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 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": "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": "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 the niche markets of your brands. Deprecated on 2026-05-18, this parameter will have no effect shortly after this date.", "required": false, "explode": false, "schema": { "type": "string", "default": "" }, "name": "market", "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 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" }, { "$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": "Overview - 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**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**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. \ntype: string\n\n**topic**: The topic of the query. \ntype: string" }, "tags_filter": { "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" ] } ] } ] }, "search_volume_type": { "type": "string", "enum": [ "ask_volume", "keyword_volume" ], "description": "AI visibility reports are switching to AI adjusted volume. It better estimates demand for AI responses across chatbots and AI search surfaces. It is calculated by adjusting Google search volume for each AI platform’s estimated usage compared with Google. This param will be deprecated on August 31, 2026; all requests will use new AI adjusted volume.\n\n`ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform.\n\n`keyword_volume` - Previous calculation. Uses Google search volume without AI platform adjustment. Available until August 31, 2026.", "default": "ask_volume" }, "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": [] }, "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#/...`" }, "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." }, "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." }, "market": { "items": { "type": "string", "title": "markets" }, "type": "array", "minItems": 1, "description": "A list of the niche markets of your brands. Deprecated on 2026-05-18, this parameter will have no effect shortly after this date." }, "competitors": { "items": { "$ref": "#/components/schemas/entity" }, "type": "array", "description": "A list of competitor names and websites to search for.", "default": [] }, "brands": { "items": { "$ref": "#/components/schemas/entity" }, "type": "array", "description": "A list of brand names and websites to search for.", "default": [] }, "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": "Overview history - 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**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**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. \ntype: string\n\n**topic**: The topic of the query. \ntype: string", "required": false, "explode": false, "schema": { "type": "string" }, "name": "where", "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" }, { "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": "AI visibility reports are switching to AI adjusted volume. It better estimates demand for AI responses across chatbots and AI search surfaces. It is calculated by adjusting Google search volume for each AI platform’s estimated usage compared with Google. This param will be deprecated on August 31, 2026; all requests will use new AI adjusted volume.\n\n`ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform.\n\n`keyword_volume` - Previous calculation. Uses Google search volume without AI platform adjustment. Available until August 31, 2026.", "required": false, "explode": false, "schema": { "type": "string", "enum": [ "ask_volume", "keyword_volume" ], "default": "ask_volume" }, "name": "search_volume_type", "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 ID of the report to use. If one is given, other parameters are taken from the report (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": "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": "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 the niche markets of your brands. Deprecated on 2026-05-18, this parameter will have no effect shortly after this date.", "required": false, "explode": false, "schema": { "type": "string", "default": "" }, "name": "market", "in": "query" }, { "description": "The brand to search for.", "required": true, "explode": false, "schema": { "type": "string" }, "name": "brand", "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": "Overview history - 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**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**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. \ntype: string\n\n**topic**: The topic of the query. \ntype: string" }, "tags_filter": { "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" ] } ] } ] }, "date_to": { "type": "string", "format": "date", "description": "The end date of the historical period in YYYY-MM-DD format." }, "date_from": { "type": "string", "format": "date", "description": "The start date of the historical period in YYYY-MM-DD format." }, "search_volume_type": { "type": "string", "enum": [ "ask_volume", "keyword_volume" ], "description": "AI visibility reports are switching to AI adjusted volume. It better estimates demand for AI responses across chatbots and AI search surfaces. It is calculated by adjusting Google search volume for each AI platform’s estimated usage compared with Google. This param will be deprecated on August 31, 2026; all requests will use new AI adjusted volume.\n\n`ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform.\n\n`keyword_volume` - Previous calculation. Uses Google search volume without AI platform adjustment. Available until August 31, 2026.", "default": "ask_volume" }, "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": [] }, "report_id": { "type": "string", "description": "The ID of the report to use. If one is given, other parameters are taken from the report (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#/...`" }, "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." }, "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." }, "market": { "items": { "type": "string", "title": "markets" }, "type": "array", "minItems": 1, "description": "A list of the niche markets of your brands. Deprecated on 2026-05-18, this parameter will have no effect shortly after this date." }, "brands": { "items": { "$ref": "#/components/schemas/entity" }, "type": "array", "description": "A list of brand names and websites to search for.", "default": [] }, "output": { "type": "string", "enum": [ "json", "csv", "xml", "php" ], "description": "The output format." } }, "type": "object", "required": [ "date_from", "data_source" ] } } } }, "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": "Overview history - 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**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**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. \ntype: string\n\n**topic**: The topic of the query. \ntype: string" }, "tags_filter": { "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" ] } ] } ] }, "date_to": { "type": "string", "format": "date", "description": "The end date of the historical period in YYYY-MM-DD format." }, "date_from": { "type": "string", "format": "date", "description": "The start date of the historical period in YYYY-MM-DD format." }, "search_volume_type": { "type": "string", "enum": [ "ask_volume", "keyword_volume" ], "description": "AI visibility reports are switching to AI adjusted volume. It better estimates demand for AI responses across chatbots and AI search surfaces. It is calculated by adjusting Google search volume for each AI platform’s estimated usage compared with Google. This param will be deprecated on August 31, 2026; all requests will use new AI adjusted volume.\n\n`ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform.\n\n`keyword_volume` - Previous calculation. Uses Google search volume without AI platform adjustment. Available until August 31, 2026.", "default": "ask_volume" }, "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": [] }, "report_id": { "type": "string", "description": "The ID of the report to use. If one is given, other parameters are taken from the report (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#/...`" }, "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." }, "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." }, "market": { "items": { "type": "string", "title": "markets" }, "type": "array", "minItems": 1, "description": "A list of the niche markets of your brands. Deprecated on 2026-05-18, this parameter will have no effect shortly after this date." }, "brands": { "items": { "$ref": "#/components/schemas/entity" }, "type": "array", "description": "A list of brand names and websites to search for.", "default": [] }, "output": { "type": "string", "enum": [ "json", "csv", "xml", "php" ], "description": "The output format." } }, "type": "object", "required": [ "date_from", "data_source" ] } } } }, "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": "Overview history - 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**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**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. \ntype: string\n\n**topic**: The topic of the query. \ntype: string", "required": false, "explode": false, "schema": { "type": "string" }, "name": "where", "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" }, { "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": "AI visibility reports are switching to AI adjusted volume. It better estimates demand for AI responses across chatbots and AI search surfaces. It is calculated by adjusting Google search volume for each AI platform’s estimated usage compared with Google. This param will be deprecated on August 31, 2026; all requests will use new AI adjusted volume.\n\n`ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform.\n\n`keyword_volume` - Previous calculation. Uses Google search volume without AI platform adjustment. Available until August 31, 2026.", "required": false, "explode": false, "schema": { "type": "string", "enum": [ "ask_volume", "keyword_volume" ], "default": "ask_volume" }, "name": "search_volume_type", "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 ID of the report to use. If one is given, other parameters are taken from the report (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": "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": "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 the niche markets of your brands. Deprecated on 2026-05-18, this parameter will have no effect shortly after this date.", "required": false, "explode": false, "schema": { "type": "string", "default": "" }, "name": "market", "in": "query" }, { "description": "The brand to search for.", "required": true, "explode": false, "schema": { "type": "string" }, "name": "brand", "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": "Overview history - 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**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**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. \ntype: string\n\n**topic**: The topic of the query. \ntype: string" }, "tags_filter": { "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" ] } ] } ] }, "date_to": { "type": "string", "format": "date", "description": "The end date of the historical period in YYYY-MM-DD format." }, "date_from": { "type": "string", "format": "date", "description": "The start date of the historical period in YYYY-MM-DD format." }, "search_volume_type": { "type": "string", "enum": [ "ask_volume", "keyword_volume" ], "description": "AI visibility reports are switching to AI adjusted volume. It better estimates demand for AI responses across chatbots and AI search surfaces. It is calculated by adjusting Google search volume for each AI platform’s estimated usage compared with Google. This param will be deprecated on August 31, 2026; all requests will use new AI adjusted volume.\n\n`ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform.\n\n`keyword_volume` - Previous calculation. Uses Google search volume without AI platform adjustment. Available until August 31, 2026.", "default": "ask_volume" }, "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": [] }, "report_id": { "type": "string", "description": "The ID of the report to use. If one is given, other parameters are taken from the report (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#/...`" }, "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." }, "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." }, "market": { "items": { "type": "string", "title": "markets" }, "type": "array", "minItems": 1, "description": "A list of the niche markets of your brands. Deprecated on 2026-05-18, this parameter will have no effect shortly after this date." }, "brands": { "items": { "$ref": "#/components/schemas/entity" }, "type": "array", "description": "A list of brand names and websites to search for.", "default": [] }, "output": { "type": "string", "enum": [ "json", "csv", "xml", "php" ], "description": "The output format." } }, "type": "object", "required": [ "date_from", "data_source" ] } } } }, "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": "Overview history - 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**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**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. \ntype: string\n\n**topic**: The topic of the query. \ntype: string", "required": false, "explode": false, "schema": { "type": "string" }, "name": "where", "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" }, { "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": "AI visibility reports are switching to AI adjusted volume. It better estimates demand for AI responses across chatbots and AI search surfaces. It is calculated by adjusting Google search volume for each AI platform’s estimated usage compared with Google. This param will be deprecated on August 31, 2026; all requests will use new AI adjusted volume.\n\n`ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform.\n\n`keyword_volume` - Previous calculation. Uses Google search volume without AI platform adjustment. Available until August 31, 2026.", "required": false, "explode": false, "schema": { "type": "string", "enum": [ "ask_volume", "keyword_volume" ], "default": "ask_volume" }, "name": "search_volume_type", "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 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": "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": "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 the niche markets of your brands. Deprecated on 2026-05-18, this parameter will have no effect shortly after this date.", "required": false, "explode": false, "schema": { "type": "string", "default": "" }, "name": "market", "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 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" }, { "$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": "Overview history - 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**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**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. \ntype: string\n\n**topic**: The topic of the query. \ntype: string" }, "tags_filter": { "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" ] } ] } ] }, "date_to": { "type": "string", "format": "date", "description": "The end date of the historical period in YYYY-MM-DD format." }, "date_from": { "type": "string", "format": "date", "description": "The start date of the historical period in YYYY-MM-DD format." }, "search_volume_type": { "type": "string", "enum": [ "ask_volume", "keyword_volume" ], "description": "AI visibility reports are switching to AI adjusted volume. It better estimates demand for AI responses across chatbots and AI search surfaces. It is calculated by adjusting Google search volume for each AI platform’s estimated usage compared with Google. This param will be deprecated on August 31, 2026; all requests will use new AI adjusted volume.\n\n`ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform.\n\n`keyword_volume` - Previous calculation. Uses Google search volume without AI platform adjustment. Available until August 31, 2026.", "default": "ask_volume" }, "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": [] }, "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#/...`" }, "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." }, "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." }, "market": { "items": { "type": "string", "title": "markets" }, "type": "array", "minItems": 1, "description": "A list of the niche markets of your brands. Deprecated on 2026-05-18, this parameter will have no effect shortly after this date." }, "competitors": { "items": { "$ref": "#/components/schemas/entity" }, "type": "array", "description": "A list of competitor names and websites to search for.", "default": [] }, "brands": { "items": { "$ref": "#/components/schemas/entity" }, "type": "array", "description": "A list of brand names and websites to search for.", "default": [] }, "output": { "type": "string", "enum": [ "json", "php" ], "description": "The output format." } }, "type": "object", "required": [ "date_from", "data_source" ] } } } }, "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" } } } }, "/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- `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**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**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. \ntype: string\n\n**topic**: The topic of the query. \ntype: string", "required": false, "explode": false, "schema": { "type": "string" }, "name": "where", "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": "AI visibility reports are switching to AI adjusted volume. It better estimates demand for AI responses across chatbots and AI search surfaces. It is calculated by adjusting Google search volume for each AI platform’s estimated usage compared with Google. This param will be deprecated on August 31, 2026; all requests will use new AI adjusted volume.\n\n`ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform.\n\n`keyword_volume` - Previous calculation. Uses Google search volume without AI platform adjustment. Available until August 31, 2026.", "required": false, "explode": false, "schema": { "type": "string", "enum": [ "ask_volume", "keyword_volume" ], "default": "ask_volume" }, "name": "search_volume_type", "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": "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" }, { "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": "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": "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 the niche markets of your brands. Deprecated on 2026-05-18, this parameter will have no effect shortly after this date.", "required": false, "explode": false, "schema": { "type": "string", "default": "" }, "name": "market", "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 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" }, { "$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": { "brand_filter": { "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" }, "to": { "type": "integer" } }, "type": "object", "description": "The volume range to filter by." }, "select": { "items": { "type": "string" }, "type": "array", "description": "A list of fields to return.\n\n- `responses`\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**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**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. \ntype: string\n\n**topic**: The topic of the query. \ntype: string" }, "tags_filter": { "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" ] } ] } ] }, "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." }, "search_volume_type": { "type": "string", "enum": [ "ask_volume", "keyword_volume" ], "description": "AI visibility reports are switching to AI adjusted volume. It better estimates demand for AI responses across chatbots and AI search surfaces. It is calculated by adjusting Google search volume for each AI platform’s estimated usage compared with Google. This param will be deprecated on August 31, 2026; all requests will use new AI adjusted volume.\n\n`ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform.\n\n`keyword_volume` - Previous calculation. Uses Google search volume without AI platform adjustment. Available until August 31, 2026.", "default": "ask_volume" }, "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": [] }, "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." }, "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#/...`" }, "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." }, "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." }, "market": { "items": { "type": "string", "title": "markets" }, "type": "array", "minItems": 1, "description": "A list of the niche markets of your brands. Deprecated on 2026-05-18, this parameter will have no effect shortly after this date." }, "competitors": { "items": { "$ref": "#/components/schemas/entity" }, "type": "array", "description": "A list of competitor names and websites to search for.", "default": [] }, "brands": { "items": { "$ref": "#/components/schemas/entity" }, "type": "array", "description": "A list of brand names and websites to search for.", "default": [] }, "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**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**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. \ntype: string\n\n**topic**: The topic of the query. \ntype: string", "required": false, "explode": false, "schema": { "type": "string" }, "name": "where", "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": "AI visibility reports are switching to AI adjusted volume. It better estimates demand for AI responses across chatbots and AI search surfaces. It is calculated by adjusting Google search volume for each AI platform’s estimated usage compared with Google. This param will be deprecated on August 31, 2026; all requests will use new AI adjusted volume.\n\n`ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform.\n\n`keyword_volume` - Previous calculation. Uses Google search volume without AI platform adjustment. Available until August 31, 2026.", "required": false, "explode": false, "schema": { "type": "string", "enum": [ "ask_volume", "keyword_volume" ], "default": "ask_volume" }, "name": "search_volume_type", "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 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": "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": "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 the niche markets of your brands. Deprecated on 2026-05-18, this parameter will have no effect shortly after this date.", "required": false, "explode": false, "schema": { "type": "string", "default": "" }, "name": "market", "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 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" }, { "$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": { "brand_filter": { "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" }, "to": { "type": "integer" } }, "type": "object", "description": "The volume range to filter by." }, "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**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**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. \ntype: string\n\n**topic**: The topic of the query. \ntype: string" }, "tags_filter": { "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" ] } ] } ] }, "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." }, "search_volume_type": { "type": "string", "enum": [ "ask_volume", "keyword_volume" ], "description": "AI visibility reports are switching to AI adjusted volume. It better estimates demand for AI responses across chatbots and AI search surfaces. It is calculated by adjusting Google search volume for each AI platform’s estimated usage compared with Google. This param will be deprecated on August 31, 2026; all requests will use new AI adjusted volume.\n\n`ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform.\n\n`keyword_volume` - Previous calculation. Uses Google search volume without AI platform adjustment. Available until August 31, 2026.", "default": "ask_volume" }, "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": [] }, "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#/...`" }, "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." }, "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." }, "market": { "items": { "type": "string", "title": "markets" }, "type": "array", "minItems": 1, "description": "A list of the niche markets of your brands. Deprecated on 2026-05-18, this parameter will have no effect shortly after this date." }, "competitors": { "items": { "$ref": "#/components/schemas/entity" }, "type": "array", "description": "A list of competitor names and websites to search for.", "default": [] }, "brands": { "items": { "$ref": "#/components/schemas/entity" }, "type": "array", "description": "A list of brand names and websites to search for.", "default": [] }, "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" } } } } }, "components": { "schemas": { "Error response": { "properties": { "error": { "type": "string" } }, "type": "object", "xml": { "name": "AhrefsApiResponse" } }, "ai-responses": { "properties": { "ai_responses": { "items": { "properties": { "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." }, "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." }, "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" } }, "entity": { "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" }, "impressions-overview": { "properties": { "metrics": { "items": { "properties": { "brand": { "type": "string", "title": "brand", "description": "Brand name (either your brand or a competitor provided in the request)." }, "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)." }, "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)." }, "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)." }, "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" }, "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" } }, "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." }, "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" } } }, "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/" } }