Panoramica - Menzioni

API + MCP

POST/v3/brand-radar/mentions-overview

Le richieste inviate a questo endpoint consumano unità API in base al parametro prompts: le richieste che restituiscono solo dati di prompt personalizzati sono gratuite, mentre quelle che includono dati dei prompt di Ahrefs seguono la tariffazione standard delle unità API.

Ogni entità fornita in brands (e in competitors, se applicabile) deve includere almeno un valore in names. Le entità costituite solo da url_groups non sono supportate qui perché le menzioni vengono abbinate ai nomi dei brand.

Corpo della richiesta

selectarray<string>Required

Un elenco di campi da restituire.

Example:["field_a","field_b"]

whereobject

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

report_idstring

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

brandsarray<object>

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

Default:[]

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.

Valori consentiti:urlpathdomainsubdomains

competitorsarray<object>

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

Default:[]

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.

Valori consentiti:urlpathdomainsubdomains

data_sourcearray<string>Required

Un elenco di modelli di chatbot. Tutti i modelli possono essere combinati tra loro. Il modulo claude supporta solo prompt personalizzati.
I modelli google_ai_overviews_keywords e google_ai_mode_keywords riportano la visibilità in AI Overviews / AI Mode calcolata a partire dalle query di ricerca su Google (parole chiave), anziché dai prompt.

Valori consentiti:chatgptgoogle_ai_overviewsgoogle_ai_modegeminiperplexitycopilotclaudegrokgoogle_ai_overviews_keywordsgoogle_ai_mode_keywords

countryarray<string>

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

Valori consentiti:adaeafagaialamaoarasatauawazba…

Default:[]

promptsstring

Il tipo di prompt da utilizzare. Se non specificato, verranno utilizzati entrambi. I prompt personalizzati richiedono la specifica di un report_id.

Valori consentiti:ahrefscustom

search_volume_typestring

I report sulla visibilità IA stanno passando al volume rettificato per l’IA. Offre una stima migliore della domanda di risposte IA su chatbot e superfici di ricerca IA. Viene calcolato rettificando il volume di ricerca Google in base all’utilizzo stimato di ciascuna piattaforma IA rispetto a Google. Questo parametro verrà deprecato il 30 settembre 2026; tutte le richieste utilizzeranno il nuovo volume rettificato per l’IA.

Valori consentiti:ask_volumekeyword_volume

Default:ask_volume

tags_filterobject

Un’espressione di filtro per i tag dei prompt. Richiede report_id. Usa 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, or è 2.

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

outputstring

Il formato di output.

Valori consentiti: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 '{ "select": ["field_a","field_b"], "where": {}, "report_id": "string", "brands": [ { "names": ["ahrefs","ahrefs seo"], "url_groups": [ { "target": "ahrefs.com", "scope": "url" } ] } ], "competitors": [ { "names": ["ahrefs","ahrefs seo"], "url_groups": [ { "target": "ahrefs.com", "scope": "url" } ] } ], "data_source": ["chatgpt"], "country": ["ad"], "prompts": "ahrefs", "search_volume_type": "ask_volume", "tags_filter": {"or":[{"field":"tag","is":["eq","branded"]},{"field":"tag","is":["eq","competitor"]}]}, "output": "json" }'

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