Panoramica - Menzioni

API + MCP

POST/v3/brand-radar/mentions-overview

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.

Corpo della richiesta

whereobject

L’espressione di filtro. Sono riconosciuti i seguenti identificatori di colonna (diversi dagli identificatori riconosciuti dal parametro select).

selectarray<string>Required

Un elenco di campi da restituire.

Example:["field_a","field_b"]

tags_filterobject

Un'espressione di filtro per i tag dei prompt. Richiede report_id. Utilizza la sintassi dei filtri con le seguenti restrizioni: l'unico nome di campo valido è "tag"; gli unici operatori validi sono: "eq", "neq", "substring", "isubstring", "phrase_match", "iphrase_match", "prefix", "suffix", "empty"; la profondità massima di annidamento di and e or è 2. Esempio: {"or": [{"field": "tag", "is": ["eq", "branded"]}, {"field": "tag", "is": ["eq", "competitor"]}]}.

countryarray<string>

Un elenco di codici paese a due lettere (ISO 3166-1 alpha-2).

Allowed values:adaeafagaialamaoarasatauawazbabbbdbebfbgbhbibjbnbobrbsbtbwbybzcacdcfcgchcickclcmcncocrcucvcyczdedjdkdmdodzeceeegesetfifjfmfofrgagbgdgegfggghgiglgmgngpgqgrgtgugyhkhnhrhthuidieiliminiqisitjejmjojpkekgkhkiknkrkwkykzlalblclilklsltlulvlymamcmdmemgmkmlmmmnmqmrmsmtmumvmwmxmymznancnengninlnonpnrnunzompapepfpgphpkplpnprpsptpyqarerorsrurwsasbscsesgshsiskslsmsnsosrstsvtdtgthtjtktltmtntotrtttwtzuaugusuyuzvcvevgvivnvuwsyeytzazmzw

Default:

report_idstring

L'ID del report da usare. Se ne viene indicato uno, gli altri parametri vengono presi dal report (brand, concorrenti, mercato, paese, filtri). Se vengono forniti il paese o i filtri, sovrascrivono quelli del report. Puoi trovarlo nell'URL del report di Brand Radar in Ahrefs: https://app.ahrefs.com/brand-radar/reports/#report_id#/...

promptsstring

Il tipo di prompt da usare. Se non specificato, verranno usati entrambi. I prompt personalizzati richiedono che venga fornito un report_id.

Allowed values:ahrefscustom

data_sourcearray<string>Required

Un elenco di modelli di chatbot. I modelli di keyword di Google (google_ai_overviews_keywords, google_ai_mode_keywords) non possono essere combinati tra loro né con altri modelli.

Allowed values:chatgptgoogle_ai_overviewsgoogle_ai_modegeminiperplexitycopilotgrokgoogle_ai_overviews_keywordsgoogle_ai_mode_keywords

marketarray<string>

Un elenco dei mercati di nicchia dei tuoi brand. Deprecato il 2026-05-18, questo parametro non avrà alcun effetto poco dopo questa data.

competitorsarray<object>

Un elenco di nomi e siti web dei concorrenti da cercare.

At least one of names or url_groups is required

namesarray<string>

I nomi del brand/concorrente

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

url_groupsarray<object>

targetstring (domain)required

Il dominio del target

Example:ahrefs.com

scopestringrequired

Ambito del target.

Allowed values:urlpathdomainsubdomains

brandsarray<object>

Un elenco di nomi e siti web dei brand da cercare.

At least one of names or url_groups is required

namesarray<string>

I nomi del brand/concorrente

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

url_groupsarray<object>

targetstring (domain)required

Il dominio del target

Example:ahrefs.com

scopestringrequired

Ambito del target.

Allowed values:urlpathdomainsubdomains

outputstring

Il formato di output.

Allowed values:jsoncsvxmlphp

Risposte

metricsarray<object>

brandstring

Nome del brand (il tuo brand o un concorrente fornito nella richiesta).

no_tracked_brandsinteger

Menzioni stimate provenienti da risposte relative al mercato specificato che non menzionano alcun brand fornito (il valore è zero quando market non è specificato).

only_competitors_brandsinteger

Menzioni stimate provenienti da risposte che menzionano solo i brand dei concorrenti.

only_target_brandinteger

Menzioni stimate provenienti da risposte che menzionano solo il tuo brand.

target_and_competitors_brandsinteger

Menzioni stimate provenienti da risposte che menzionano sia il tuo brand sia i brand dei concorrenti.

totalinteger

Totale menzioni stimate per il tuo brand (include sia only_target_brand sia target_and_competitors_brands).

curl "https://api.ahrefs.com/v3/brand-radar/mentions-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": {}, "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 } ] }