openapi: 3.2.0 info: title: Brand Radar Overview history API 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 security: - http: - read tags: - name: Overview history paths: /impressions-history: get: tags: - Overview history 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. `ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform. `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. The `google_ai_overviews_keywords` and `google_ai_mode_keywords` models report AI Overviews / AI Mode visibility derived from Google search queries (keywords) rather than prompts.' 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 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. `ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform. `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. The `google_ai_overviews_keywords` and `google_ai_mode_keywords` models report AI Overviews / AI Mode visibility derived from Google search queries (keywords) rather than prompts.' 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 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. Every 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. `ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform. `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. The `google_ai_overviews_keywords` and `google_ai_mode_keywords` models report AI Overviews / AI Mode visibility derived from Google search queries (keywords) rather than prompts.' 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 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. `ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform. `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. The `google_ai_overviews_keywords` and `google_ai_mode_keywords` models report AI Overviews / AI Mode visibility derived from Google search queries (keywords) rather than prompts.' 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 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. Every 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. `ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform. `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. The `google_ai_overviews_keywords` and `google_ai_mode_keywords` models report AI Overviews / AI Mode visibility derived from Google search queries (keywords) rather than prompts.' 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 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. `ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform. `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. The `google_ai_overviews_keywords` and `google_ai_mode_keywords` models report AI Overviews / AI Mode visibility derived from Google search queries (keywords) rather than prompts.' 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 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. `ask_volume` - New calculation (default). Estimates demand for AI responses by adjusting Google search volume for each AI platform. `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. The `google_ai_overviews_keywords` and `google_ai_mode_keywords` models report AI Overviews / AI Mode visibility derived from Google search queries (keywords) rather than prompts.' 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' components: responses: error_400: description: Bad Request 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_500: description: Internal Error 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_429: description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/Error_response' application/xml: schema: $ref: '#/components/schemas/Error_response' schemas: 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-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 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 Error_response: properties: error: type: string 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 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 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 securitySchemes: http: type: http scheme: bearer externalDocs: description: '' url: https://docs.ahrefs.com/docs/api/v3/