Respostas de IA

API + MCP

POST/v3/brand-radar/ai-responses

As solicitações para este endpoint consomem unidades de API com base no parâmetro prompts: solicitações que retornam apenas dados de prompt personalizado são gratuitas, enquanto solicitações que incluem dados de prompt da Ahrefs seguem o preço padrão de unidades de API.

Corpo da solicitação

brand_filterobject

Uma expressão de filtro para a visibilidade da sua marca, seguindo o mesmo comportamento do filtro “Sua marca”. brand_name indica se uma resposta menciona sua marca: "mentioned" ou "not_mentioned". page_status indica como a IA usou suas páginas: "cited" (a IA recuperou páginas do seu site e fez referência a elas na resposta), "found_but_not_cited" (a IA recuperou páginas do seu site como possíveis fontes, mas não fez referência a elas na resposta final) ou "not_found" (a IA não recuperou nenhuma página do seu site).
Usa a sintaxe de filtro com as seguintes restrições: o único operador válido é "eq"; cada campo deve ser uma seção: forneça um único valor ou combine vários valores do mesmo campo com or; una as seções brand_name e page_status com um and/or no nível superior. Selecionar todos os valores de um campo será rejeitado, pois corresponderia a tudo (omita o campo em vez disso).

Example:{"and":[{"field":"brand_name","is":["eq","mentioned"]},{"or":[{"field":"page_status","is":["eq","cited"]},{"field":"page_status","is":["eq","found_but_not_cited"]}]}]}

volume_rangeobject

O intervalo de volume para filtrar.

frominteger

tointeger

selectarray<string>Required

Uma lista de campos para retornar.\n\n- country\n- data_source\n- last_updated\n- links (10 unidades)\n- question\n- response\n- search_queries\n- tags\n- volume (10 unidades)

Example:["field_a","field_b"]

whereobject

A expressão de filtro. Os seguintes identificadores de coluna são reconhecidos (eles são diferentes dos identificadores reconhecidos pelo parâmetro select).

tags_filterobject

Uma expressão de filtro para tags de prompt. Requer report_id. Usa a sintaxe de filtro com as seguintes restrições: o único nome de campo válido é "tag"; os únicos operadores válidos são: "eq", "neq", "substring", "isubstring", "phrase_match", "iphrase_match", "prefix", "suffix", "empty"; a profundidade máxima de aninhamento de and e or é 2.

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

limitinteger

O número de resultados a retornar.

Default:1000

datestring (date)

A data a ser pesquisada no formato YYYY-MM-DD.

search_volume_typestring

Os relatórios de visibilidade de IA estão migrando para o volume ajustado por IA. Essa métrica estima melhor a demanda por respostas de IA em chatbots e em superfícies de busca com IA. O cálculo é feito ajustando o volume de pesquisa do Google para o uso estimado de cada plataforma de IA em comparação com o Google. Este parâmetro será descontinuado em 31 de agosto de 2026; todas as solicitações usarão o novo volume ajustado por IA.

Valores permitidos:ask_volumekeyword_volume

Default:ask_volume

countryarray<string>

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

Valores permitidos:adaeafagaialamaoarasatauawazba…

Default:[]

order_bystring

Uma coluna pela qual ordenar os resultados.

Valores permitidos:relevancevolume

Default:relevance

report_idstring

O ID do relatório a ser usado. Se for fornecido, outros parâmetros serão obtidos do relatório (marca, concorrentes, mercado, país, filtros). Se país ou filtros forem fornecidos, eles substituirão os do relatório. Você pode encontrá-lo na URL do seu relatório do Brand Radar no Ahrefs: https://app.ahrefs.com/brand-radar/reports/#report_id#/...

promptsstring

O tipo de prompts a serem usados. Se não for especificado, ambos serão usados. Prompts personalizados exigem que um report_id seja fornecido.

Valores permitidos:ahrefscustom

data_sourcearray<string>Required

Uma lista de modelos de chatbot. Todos os modelos podem ser combinados entre si. O módulo claude oferece suporte apenas a prompts personalizados.
Os modelos google_ai_overviews_keywords e google_ai_mode_keywords informam a visibilidade de AI Overviews / AI Mode derivada de consultas de pesquisa do Google (palavras-chave), em vez de prompts.

Valores permitidos:chatgptgoogle_ai_overviewsgoogle_ai_modegeminiperplexitycopilotclaudegrokgoogle_ai_overviews_keywordsgoogle_ai_mode_keywords

marketarray<string>

Uma lista dos nichos de mercado das suas marcas. Obsoleto em 2026-05-18, este parâmetro não terá mais efeito logo após essa data.

competitorsarray<object>

Uma lista de nomes e sites de concorrentes para pesquisar.

Default:[]

At least one of names or url_groups is required

namesarray<string>

Os nomes da marca/concorrente

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

url_groupsarray<object>

targetstring (domain)required

O domínio do alvo

Example:ahrefs.com

scopestringrequired

Escopo do alvo.

Valores permitidos:urlpathdomainsubdomains

brandsarray<object>

Uma lista de nomes e sites de marcas para pesquisar.

Default:[]

At least one of names or url_groups is required

namesarray<string>

Os nomes da marca/concorrente

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

url_groupsarray<object>

targetstring (domain)required

O domínio do alvo

Example:ahrefs.com

scopestringrequired

Escopo do alvo.

Valores permitidos:urlpathdomainsubdomains

outputstring

O formato de saída.

Valores permitidos:jsonphp

Respostas

ai_responsesarray<object>

countrystring

O país da pergunta.

data_sourcestring

O modelo de chatbot que gerou a resposta.

last_updatedstring (date)

A data em que os dados foram atualizados pela última vez.

linksarray<object>

(10 unidades) Os links usados para a resposta.

urlstring

titlestring or null

questionstring

A pergunta feita pelo usuário.

responsestring

(10 unidades) A resposta do modelo.

search_queriesarray<string>

A consulta de pesquisa usada pelo chatbot para encontrar informações para a resposta. Observação: se data_source não incluir chatgpt ou perplexity, este campo estará sempre vazio.

tagsarray<string>

Tags atribuídas à consulta.

volumeinteger

(10 unidades) Pesquisas mensais estimadas. Isso se baseia em nossas estimativas para o Google, combinando o volume de pesquisa de palavras-chave relacionadas em que esta pergunta aparece na seção People Also Ask.

curl "https://api.ahrefs.com/v3/brand-radar/ai-responses" \ -X POST \ -H "Authorization: Bearer $AHREFS_API_KEY" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ --data-raw '{ "brand_filter": {"and":[{"field":"brand_name","is":["eq","mentioned"]},{"or":[{"field":"page_status","is":["eq","cited"]},{"field":"page_status","is":["eq","found_but_not_cited"]}]}]}, "volume_range": { "from": 0, "to": 0 }, "select": ["field_a","field_b"], "where": {}, "tags_filter": {"or":[{"field":"tag","is":["eq","branded"]},{"field":"tag","is":["eq","competitor"]}]}, "limit": 0, "date": "string", "search_volume_type": "ask_volume", "country": ["ad"], "order_by": "relevance", "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" }'

{ "ai_responses": [ { "country": "string", "data_source": "string", "last_updated": "string", "links": [ { "url": "string", "title": "string" } ], "question": "string", "response": "string", "search_queries": ["string"], "tags": ["string"], "volume": 0 } ] }