Docs
Search docs...⌘K

Overview history - Citations

API only
POST/v3/brand-radar/citations-history

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.

Request body

whereobject

The filter expression. The following column identifiers are recognized (this differs from the identifiers recognized by the select parameter).

tags_filterobject

A filter expression for prompt tags. Requires report_id. Uses filter syntax with the following restrictions: the only valid field name is "tag"; the only valid operator are: "eq", "neq", "substring", "isubstring", "phrase_match", "iphrase_match", "prefix", "suffix", "empty"; maximum nesting depth of and, or is 2. Example: {"or": [{"field": "tag", "is": ["eq", "branded"]}, {"field": "tag", "is": ["eq", "competitor"]}]}.

date_tostring (date)

The end date of the historical period in YYYY-MM-DD format.

date_fromstring (date)Required

The start date of the historical period in YYYY-MM-DD format.

countryarray<string>

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

Allowed values:adaeafagaialamaoarasatauawazbabbbdbebfbgbhbibjbnbobrbsbtbwbybzcacdcfcgchcickclcmcncocrcucvcyczdedjdkdmdodzeceeegesetfifjfmfofrgagbgdgegfggghgiglgmgngpgqgrgtgugyhkhnhrhthuidieiliminiqisitjejmjojpkekgkhkiknkrkwkykzlalblclilklsltlulvlymamcmdmemgmkmlmmmnmqmrmsmtmumvmwmxmymznancnengninlnonpnrnunzompapepfpgphpkplpnprpsptpyqarerorsrurwsasbscsesgshsiskslsmsnsosrstsvtdtgthtjtktltmtntotrtttwtzuaugusuyuzvcvevgvivnvuwsyeytzazmzw
Default:
report_idstring

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

promptsstring

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

Allowed values:ahrefscustom
data_sourcearray<string>Required

A list of chatbot models. Google keyword models (google_ai_overviews_keywords, google_ai_mode_keywords) cannot be combined with each other or with other models.

Allowed values:chatgptgoogle_ai_overviewsgoogle_ai_modegeminiperplexitycopilotgrokgoogle_ai_overviews_keywordsgoogle_ai_mode_keywords
marketarray<string>

A list of the niche markets of your brands. Deprecated on 2026-05-18, this parameter will have no effect shortly after this date.

brandsarray<object>

A list of brand names and websites to search for.

At least one of names or url_groups is required
namesarray<string>

The names of the brand/competitor

Example:["ahrefs","ahrefs seo"]
url_groupsarray<object>
targetstring (domain)required

The domain of the target

Example:ahrefs.com
scopestringrequired

Scope of the target.

Allowed values:urlpathdomainsubdomains
outputstring

The output format.

Allowed values:jsoncsvxmlphp

Responses

metricsarray<object>
citationsinteger

Estimated citations from responses mentioning the brand URLs.

datestring (date)