Vue d’ensemble – Citations

API + MCP

POST/v3/brand-radar/citations-overview

Les requêtes vers ce point de terminaison consomment des unités d’API en fonction du paramètre prompts : les requêtes qui ne renvoient que des données de prompts personnalisés sont gratuites, tandis que celles qui incluent des données de prompts Ahrefs sont facturées selon la tarification standard en unités d’API.

Chaque entité fournie dans brands (et competitors, le cas échéant) doit inclure au moins une valeur dans url_groups. Les entités constituées uniquement de names ne sont pas prises en charge ici, car les citations sont mises en correspondance avec des groupes d’URL.

Corps de la requête

whereobject

Expression de filtrage. Les identifiants de colonnes suivants sont reconnus (ils diffèrent de ceux reconnus par le paramètre select).

selectarray<string>Required

Une liste de champs à renvoyer.

Example:["field_a","field_b"]

tags_filterobject

Expression de filtrage pour les étiquettes de prompt. Nécessite report_id. Utilise la syntaxe de filtre avec les restrictions suivantes : le seul nom de champ valide est "tag" ; les seuls opérateurs valides sont : "eq", "neq", "substring", "isubstring", "phrase_match", "iphrase_match", "prefix", "suffix", "empty" ; la profondeur d’imbrication maximale des opérateurs and et or est de 2.

Example:{"or":[{"field":"tag","is":["eq","branded"]},{"field":"tag","is":["eq","competitor"]}]}

search_volume_typestring

Les rapports de visibilité IA passent au volume ajusté pour l’IA. Celui-ci estime mieux la demande de réponses d’IA sur l’ensemble des chatbots et des interfaces de recherche IA. Il est calculé en ajustant le volume de recherche Google en fonction de l’utilisation estimée de chaque plateforme d’IA par rapport à celle de Google. Ce paramètre sera obsolète le 31 août 2026 ; toutes les requêtes utiliseront le nouveau volume ajusté pour l’IA.

Valeurs autorisées:ask_volumekeyword_volume

Default:ask_volume

countryarray<string>

Une liste de codes pays à deux lettres (ISO 3166-1 alpha-2).

Valeurs autorisées:adaeafagaialamaoarasatauawazba…

Default:[]

report_idstring

L’ID du rapport à utiliser. S’il est fourni, les autres paramètres sont repris du rapport (marque, concurrents, marché, pays, filtres). Si le pays ou des filtres sont fournis, ils remplacent ceux du rapport. Vous pouvez le trouver dans l’URL de votre rapport Brand Radar dans Ahrefs : https://app.ahrefs.com/brand-radar/reports/#report_id#/...

promptsstring

Le type de prompts à utiliser. S’il n’est pas précisé, les deux seront utilisés. Les prompts personnalisés nécessitent de fournir un report_id.

Valeurs autorisées:ahrefscustom

data_sourcearray<string>Required

Une liste de modèles de chatbot. Tous les modèles peuvent être combinés les uns avec les autres. Le module claude ne prend en charge que les prompts personnalisés.
Les modèles google_ai_overviews_keywords et google_ai_mode_keywords indiquent la visibilité dans AI Overviews / le mode IA, déterminée à partir de requêtes de recherche Google (mots-clés) plutôt que de prompts.

Valeurs autorisées:chatgptgoogle_ai_overviewsgoogle_ai_modegeminiperplexitycopilotclaudegrokgoogle_ai_overviews_keywordsgoogle_ai_mode_keywords

marketarray<string>

Une liste des marchés de niche de vos marques. Obsolète depuis le 2026-05-18, ce paramètre n’aura plus d’effet peu après cette date.

competitorsarray<object>

Une liste de noms et de sites web de concurrents à rechercher.

Default:[]

At least one of names or url_groups is required

namesarray<string>

Les noms de la marque/du concurrent

Example:["ahrefs","ahrefs seo"]

url_groupsarray<object>

targetstring (domain)required

Le domaine de la cible

Example:ahrefs.com

scopestringrequired

Portée de la cible.

Valeurs autorisées:urlpathdomainsubdomains

brandsarray<object>

Une liste de noms et de sites web de marques à rechercher.

Default:[]

At least one of names or url_groups is required

namesarray<string>

Les noms de la marque/du concurrent

Example:["ahrefs","ahrefs seo"]

url_groupsarray<object>

targetstring (domain)required

Le domaine de la cible

Example:ahrefs.com

scopestringrequired

Portée de la cible.

Valeurs autorisées:urlpathdomainsubdomains

outputstring

Le format de sortie.

Valeurs autorisées:jsoncsvxmlphp

Réponses

metricsarray<object>

brandstring

Nom de la marque (votre marque ou un concurrent fourni dans la requête).

no_tracked_brandsinteger

Nombre estimé de citations issues de réponses liées au marché spécifié et ne mentionnant aucune des URL de marque fournies (la valeur est égale à zéro lorsque market n’est pas spécifié).

only_competitors_brandsinteger

Nombre estimé de citations issues de réponses ne mentionnant que les URL des marques concurrentes.

only_target_brandinteger

Nombre estimé de citations issues de réponses ne mentionnant que les URL de votre marque.

target_and_competitors_brandsinteger

Nombre estimé de citations issues de réponses mentionnant à la fois les URL de votre marque et celles de vos concurrents.

totalinteger

Nombre total estimé de citations pour les URL de votre marque (inclut only_target_brand et target_and_competitors_brands).

curl "https://api.ahrefs.com/v3/brand-radar/citations-overview" \ -X POST \ -H "Authorization: Bearer $AHREFS_API_KEY" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ --data-raw '{ "where": {}, "select": ["field_a","field_b"], "tags_filter": {"or":[{"field":"tag","is":["eq","branded"]},{"field":"tag","is":["eq","competitor"]}]}, "search_volume_type": "ask_volume", "country": ["ad"], "report_id": "string", "prompts": "ahrefs", "data_source": ["chatgpt"], "market": ["string"], "competitors": [ { "names": ["ahrefs","ahrefs seo"], "url_groups": [ { "target": "ahrefs.com", "scope": "url" } ] } ], "brands": [ { "names": ["ahrefs","ahrefs seo"], "url_groups": [ { "target": "ahrefs.com", "scope": "url" } ] } ], "output": "json" }'

{ "metrics": [ { "brand": "string", "no_tracked_brands": 0, "only_competitors_brands": 0, "only_target_brand": 0, "target_and_competitors_brands": 0, "total": 0 } ] }