Resumen: citas

Solo API

POST/v3/brand-radar/citations-overview

Las solicitudes a este endpoint consumen unidades de API en función del parámetro prompts: las solicitudes que devuelven únicamente datos de prompts personalizados son gratuitas, mientras que las solicitudes que incluyen datos de prompts de Ahrefs se cobran según la tarifa estándar de unidades de API.

Cada entidad proporcionada en brands (y en competitors, cuando corresponda) debe incluir al menos un valor en url_groups. Aquí no se admiten entidades compuestas únicamente por names, ya que las citas se cotejan con grupos de URL.

Cuerpo de la solicitud

whereobject

La expresión de filtro. Se reconocen los siguientes identificadores de columna (que son distintos de los identificadores reconocidos por el parámetro select).

selectarray<string>Required

Una lista de campos para devolver.

Example:["field_a","field_b"]

tags_filterobject

Una expresión de filtro para etiquetas de prompt. Requiere report_id. Usa la sintaxis de filtros con las siguientes restricciones: el único nombre de campo válido es "tag"; los únicos operadores válidos son: "eq", "neq", "substring", "isubstring", "phrase_match", "iphrase_match", "prefix", "suffix", "empty"; la profundidad máxima de anidamiento de and y or es 2.

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

search_volume_typestring

Los informes de visibilidad de IA están migrando al volumen ajustado por IA. Permite estimar mejor la demanda de respuestas de IA en chatbots y superficies de búsqueda con IA. Se calcula ajustando el volumen de búsqueda de Google según el uso estimado de cada plataforma de IA en comparación con Google. Este parámetro quedará obsoleto el 31 de agosto de 2026; todas las solicitudes usarán el nuevo volumen ajustado por IA.

Valores permitidos:ask_volumekeyword_volume

Default:ask_volume

countryarray<string>

Una lista de códigos de país de dos letras (ISO 3166-1 alfa-2).

Valores permitidos:adaeafagaialamaoarasatauawazba…

Default:[]

report_idstring

El ID del informe que se va a usar. Si se indica uno, los demás parámetros se toman del informe (marca, competidores, mercado, país, filtros). Si se especifican el país o los filtros, estos prevalecen sobre los del informe. Puedes encontrarlo en la URL de tu informe de Brand Radar en Ahrefs: https://app.ahrefs.com/brand-radar/reports/#report_id#/...

promptsstring

El tipo de prompts que se va a usar. Si no se especifica, se usarán ambos tipos. Los prompts personalizados requieren que se proporcione un report_id.

Valores permitidos:ahrefscustom

data_sourcearray<string>Required

Una lista de modelos de chatbot. Todos los modelos se pueden combinar entre sí. El módulo claude solo admite prompts personalizados.

Valores permitidos:chatgptgoogle_ai_overviewsgoogle_ai_modegeminiperplexitycopilotclaudegrokgoogle_ai_overviews_keywordsgoogle_ai_mode_keywords

marketarray<string>

Una lista de los nichos de mercado de tus marcas. En desuso a partir del 2026-05-18, este parámetro dejará de tener efecto poco después de esa fecha.

competitorsarray<object>

Una lista de nombres de competidores y sitios web que se deben buscar.

Default:[]

At least one of names or url_groups is required

namesarray<string>

Los nombres de la marca o del competidor

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

url_groupsarray<object>

targetstring (domain)required

El dominio del objetivo

Example:ahrefs.com

scopestringrequired

El alcance del objetivo.

Valores permitidos:urlpathdomainsubdomains

brandsarray<object>

Una lista de nombres de marcas y sitios web que se deben buscar.

Default:[]

At least one of names or url_groups is required

namesarray<string>

Los nombres de la marca o del competidor

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

url_groupsarray<object>

targetstring (domain)required

El dominio del objetivo

Example:ahrefs.com

scopestringrequired

El alcance del objetivo.

Valores permitidos:urlpathdomainsubdomains

outputstring

El formato de salida.

Valores permitidos:jsoncsvxmlphp

Respuestas

metricsarray<object>

brandstring

Nombre de la marca (ya sea su marca o la de un competidor incluido en la solicitud).

no_tracked_brandsinteger

Citas estimadas de respuestas relacionadas con el mercado especificado que no mencionan ninguna de las URL de marca proporcionadas (el valor es cero cuando no se especifica market).

only_competitors_brandsinteger

Citas estimadas de respuestas que mencionan únicamente las URL de marca de los competidores.

only_target_brandinteger

Citas estimadas de respuestas que mencionan únicamente las URL de tu marca.

target_and_competitors_brandsinteger

Citas estimadas de respuestas que mencionan tanto las URL de tu marca como las de los competidores.

totalinteger

Total de citas estimadas para las URL de tu marca (incluye only_target_brand y 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 } ] }