The Overview history API from Ahrefs — 4 operation(s) for overview history.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/ahrefs-overview-history-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
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
# --- truncated at 32 KB (82 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ahrefs/refs/heads/main/openapi/ahrefs-overview-history-api-openapi.yml