Saltar para o conteúdo principal
Compare uma resposta de IA concluída com as páginas por trás dela. O resultado mostra as buscas que o mecanismo fez, as páginas que ele recuperou e as que citou, as marcas que a resposta nomeia e as páginas que as nomeiam, a posição da sua marca e ações priorizadas. Ele também mapeia os parágrafos de cada página citada às partes da resposta a que correspondem, com uma explicação para cada vínculo, e resume o que as páginas citadas têm em comum. É uma análise de correspondência a posteriori de uma resposta existente: não prova que uma fonte fez o modelo gerar uma frase, nem dá nota à qualidade de uma página. Trate como evidência a examinar, não como veredito.
Faça polling em GET /v1/async/task/:id ou informe webhook.url no envio; a tarefa informa taskType: "CITATION_ANALYSIS". Não envie esta análise por POST /v1/async/task: use o endpoint dedicado. Os endpoints antigos POST /v1/geo-audit, POST /v1/source-influence e POST /v1/research, os tipos de tarefa GEO_AUDIT, SOURCE_INFLUENCE e CITATION_ATTRIBUTION e include.geoAudit, include.sourceInfluence continuam funcionando; as respostas sempre usam os nomes novos.

Analisar uma tarefa que você já executou

Se a resposta veio desta API, envie o id da tarefa em vez de copiar a resposta e as citações do resultado:
A tarefa precisa ser sua, estar em COMPLETED e ainda poder ser lida por GET /v1/async/task/:id. O Markdown da resposta (o texto, se o mecanismo não retornou Markdown) vira answer, e as URLs citadas viram citations na ordem do mecanismo: as 100 primeiras, com no máximo 10 threads de discussão. Marcadores de cartões de produto e de vídeo (links de googleusercontent.com) e links de busca do Google são ignorados, porque não têm página para ler. O prompt, o country e o mecanismo da tarefa são usados, a menos que você os envie. Enviar taskId junto com answer ou citations é rejeitado com 400, assim como uma tarefa inacabada ou sem texto de resposta ou URL citada. Um id de tarefa desconhecido ou expirado retorna 404.

Analise cada resposta enquanto a coleta

Adicione include.citationAnalysis: true a uma solicitação de coleta e a análise é executada sobre a resposta assim que ela é coletada. Funciona com os mecanismos de resposta (CHATGPT, GEMINI, PERPLEXITY, GOOGLE_AIO, GOOGLE_AIMODE, NAVER_AI_BRIEF, NAVER_AI_TAB, BING_SEARCH, BING_COPILOT), em tarefas individuais, lotes de tarefas, grades e POST /v1/batches.
A análise lê a resposta e suas URLs citadas da mesma forma que taskId acima. O resultado da resposta passa a trazer response.citationAnalysis: a tarefa de análise exatamente como GET /v1/async/task/:id a retorna, com task, credits e response ou error.
  • Webhook: enviado uma única vez, depois que a análise termina, com a resposta e a análise juntas.
  • Consulta: a tarefa de resposta fica COMPLETED assim que a resposta está pronta. Continue consultando até que response.citationAnalysis.task.status seja COMPLETED ou FAILED.
  • Os lotes são concluídos quando todas as respostas e suas análises terminam.
  • Sem análise: se a resposta não cita nenhuma URL para ler, ou se seus créditos ou o limite diário da chave não cobrem a reserva da análise, response.citationAnalysis é { "error": "…" } e a resposta é entregue imediatamente.
  • Cobrança: a análise é cobrada à parte, por uso, como qualquer tarefa de Citation Analysis. A cobrança da resposta não muda. Uma chave limitada a certos tipos de tarefa também precisa permitir CITATION_ANALYSIS.

Payload

Com taskId ou include.citationAnalysis, esses campos são preenchidos a partir dos dados brutos da resposta. Para CHATGPT, as buscas do mecanismo viram queries e cada página que ele recuperou vira uma citação com cited, position, citedText, publishedAt e query; a mesma URL com parâmetros de rastreamento diferentes é mesclada. Para o Google AI Overview, as fontes da visão geral são citadas e os resultados orgânicos fora delas são não citados, com position igual à sua posição orgânica. Os demais mecanismos fornecem apenas fontes citadas.
Enviar analysis na solicitação retorna 400. Todos os resultados incluem insights.

Resultado

Resultados armazenados antes da v4 mantêm o formato anterior, sem o campo version.

version

Sempre 4 para este formato.

answer

A resposta que você enviou, sem alterações. answerRanges são offsets exatamente nesta string: unidades de código UTF-16 do JavaScript, start inclusivo e end exclusivo. Recorte como está, com answer.slice(start, end), em vez de dividir o texto de novo. Cada intervalo de links[] identifica uma unidade semântica inteira da resposta: uma frase, um item de lista ou uma célula de tabela. Cada intervalo de brands[] é o nome exato como está escrito. Os limites se referem ao texto original.

queries[]

As buscas que o mecanismo fez para esta resposta. Cada uma tem um id, seu text e sourceIds: as fontes que aquela busca encontrou. Fica vazio quando o mecanismo não expôs buscas e você não enviou nenhuma.

sources[]: uma entrada por página

  • id: identificador opaco, único dentro do resultado.
  • url: a URL da página; domain: o host dela.
  • channel: quem controla a página, avaliado a partir do host:
    • own: o site próprio da sua marca (exatamente quando own é true).
    • brand: o site próprio de outra marca que o resultado nomeia.
    • editorial: um veículo editorial; só o editor pode alterar a página. Hosts não reconhecidos são informados como editorial.
    • retailer: uma loja online ou marketplace.
    • review_platform: um site de avaliações de clientes ou de empresas.
    • community: um fórum ou site de perguntas e respostas.
    • video: uma plataforma de vídeo.
    • social: uma rede social.
    • blog_platform: um serviço de blogs hospedados.
    • reference: uma enciclopédia ou wiki; nunca é alvo de uma ação.
  • cited: true quando a resposta cita a página, false quando o mecanismo apenas a recuperou.
  • position: a posição que o próprio mecanismo deu à página, ou null quando ele não informou nenhuma.
  • queryIds[]: as buscas que encontraram a página.
  • publishedAt: a data de publicação como o mecanismo a informou, ou null.
  • citedText[]: trechos que o próprio mecanismo informou ter citado; [] quando não há nenhum.
  • brandIds[]: marcas nomeadas na página lida, no título dela ou em citedText.
  • own: true quando a página está no site próprio da sua marca.
  • paragraphs[]: os parágrafos de uma página citada incluídos no resultado. Cada um tem um id (único em todo o resultado) e o text do parágrafo. Um parágrafo pode ser incluído sem nenhum vínculo. Sempre vazio para páginas não citadas.
  • error: presente só quando a página não pôde ser lida. Nesse caso paragraphs fica vazio, e a string traz um motivo curto para aquela fonte.

brands[]

Todas as marcas que o resultado acompanha: a sua brand (role: "target"), seus competitors ("competitor") e outras marcas que a resposta nomeia ("answer").
  • rank: a ordem em que o nome da marca aparece pela primeira vez na resposta, começando em 1; null quando a resposta não nomeia a marca.
  • answerRanges[]: os trechos exatos em que a resposta nomeia a marca ou um de seus nomes de produto, nos mesmos offsets UTF-16; answer.slice(start, end) devolve o nome como está escrito. A busca ignora maiúsculas e minúsculas e considera palavras inteiras (exceto em escritas sem espaços); inclui títulos e células de tabela, nunca URLs de links nem marcação de imagens. Ao contrário dos intervalos de links[], não são unidades inteiras da resposta.
  • citedSourceIds[]: fontes citadas cuja página a nomeia.
  • retrievedSourceIds[]: fontes não citadas cuja página a nomeia.
  • ownSourceIds[]: fontes no site próprio da marca; preenchido apenas para a marca-alvo.
  • paragraphId: o parágrafo a que o vínculo se refere. Sempre aponta para um parágrafo que existe em sources[].
  • answerRanges[]: as partes da resposta a que este parágrafo corresponde, como pares start/end nos mesmos offsets UTF-16. Um vínculo pode ter vários intervalos; o mesmo texto da resposta não se repete entre eles. Cada intervalo é uma unidade inteira da resposta (frase, item de lista ou célula de tabela).
  • explanation: uma frase curta que descreve a correspondência, ou seja, o que o parágrafo afirma sobre aquela parte da resposta.

visibility

A posição da sua marca nesta resposta; null quando nenhuma brand foi enviada.
  • brandId: a sua marca em brands[].
  • stage: um destes:
    • mentioned: a resposta nomeia a sua marca.
    • on_cited_page: a resposta não a nomeia, mas uma página citada sim.
    • on_retrieved_page: só páginas que o mecanismo recuperou sem citar a nomeiam.
    • not_found: nenhuma página lida a nomeia.
  • rank: o rank da sua marca em brands[].
  • answerBrands: quantas marcas a resposta nomeia.

actions[]

Próximos passos priorizados para a sua marca; [] quando nenhuma brand foi enviada. priority começa em 1 (fazer primeiro) e não tem lacunas. As ações são ordenadas por control: primeiro o que a sua marca controla (owned), depois plataformas onde ela pode publicar (platform) e, por fim, contato com terceiros (outreach). summary é uma frase e steps[] traz de um a cinco passos concretos, ambos no idioma da resposta. sourceIds, brandIds, queryIds e linkIds apontam para a evidência neste resultado. brandIds nomeia a sua marca ou as marcas rivais que essas páginas nomeiam. As ações nunca sugerem avaliações falsas ou não declaradas, se passar por avaliador independente, comprar links nem editar páginas que a sua marca não possui. Páginas de terceiros que nomeiam a sua marca mas não foram citadas aparecem em brands[].retrievedSourceIds, não como ações.

insights[]

Até quatro resumos curtos do que as páginas mostram em conjunto: quais canais foram citados, o formato, a atualidade ou os critérios que as páginas citadas compartilham, como a ordem das marcas na resposta se compara com o que as páginas citadas cobrem e onde a sua marca fica. sourceIds indica as páginas e linkIds os vínculos em que cada resumo se apoia; pelo menos um deles não é vazio, e eles só citam entradas deste resultado. Os insights descrevem correspondência; não são recomendações.

Como ler o resultado corretamente

  • Ausência de vínculo não é veredito. Um parágrafo sem vínculo apenas não correspondeu a um intervalo da resposta, e uma parte da resposta sem intervalo significa que nenhum parágrafo foi vinculado a ela. Nenhum dos dois diz que a página é irrelevante, não foi usada ou não é confiável.
  • Uma página não lida continua incerta. Quando sources[].error está definido, aquela citação ficou fora da análise; não trate a falta de vínculos como resultado negativo. Tente de novo ou envie o body se ela importar.
  • Correspondência, não causalidade. O resultado descreve como uma resposta existente e o texto de uma página existente se alinham depois do fato, e quais marcas essas páginas nomeiam. Ele não mede influência na geração, não dá nota à página nem informa como a resposta foi produzida.
  • not_found significa que não está em nenhuma página lida. Não significa que a sua marca está ausente da web.
  • Os dados de recuperação dependem do mecanismo. Páginas não citadas só aparecem quando o mecanismo as expõe (ChatGPT, Google AI Overview) ou quando você envia páginas com cited: false. Caso contrário, todas as fontes são citadas, e a sua própria página só pode aparecer como citada.
  • Os canais são avaliados a partir do host. channel é inferido do host da página, não da leitura de quem a escreveu.
  • Ações são sugestões, não garantias. Elas são priorizadas a partir das páginas listadas neste resultado; agir sobre uma delas não garante que a resposta mude.
  • Os ids são internos. Não guarde os identificadores s…/q…/b…/l…/a… como chaves estáveis entre execuções; eles valem só dentro de um resultado.

Execução e limites

  • Tamanho não é motivo de falha. Tudo o que o contrato da requisição aceita, uma answer de até 200.000 caracteres com até 100 citações, é analisado. Respostas longas, conjuntos grandes de fontes e páginas muito longas são tratados dividindo o trabalho, não rejeitando a tarefa.
  • A profundidade acompanha a resposta, não a página. Uma página longa não gera mais vínculos do que a resposta consegue sustentar: a análise se concentra nos trechos com maior chance de corresponder à resposta, e toda fonte que mostra alguma correspondência aparece representada. Em uma página grande, ou que repete a mesma afirmação em navegação, listagens e avaliações, espere os trechos mais fortes, não cada ocorrência.
  • Marcação não é evidência. Mapas do site, índices de links e galerias de imagens não geram vínculos; uma página feita só disso é informada sem parágrafos, em vez de com correspondências inventadas.
  • Uma fonte que não pôde ser lida é informada em sources[].error sem derrubar a tarefa se outra fonte puder ser lida. A tarefa falha quando nenhuma fonte pôde ser lida, em caso de falha da análise, timeout ou erro de configuração do serviço.
  • As requisições são cobradas por uso, como o resto da API. A resposta do envio mostra a reserva temporária de créditos; a cobrança final é acertada quando a tarefa chega a um estado final.