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: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
Adicioneinclude.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.
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
COMPLETEDassim que a resposta está pronta. Continue consultando até queresponse.citationAnalysis.task.statussejaCOMPLETEDouFAILED. - 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.
Resultado
Resultados armazenados antes da v4 mantêm o formato anterior, sem o campoversion.
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 quandoowné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 comoeditorial.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:truequando a resposta cita a página,falsequando o mecanismo apenas a recuperou.position: a posição que o próprio mecanismo deu à página, ounullquando ele não informou nenhuma.queryIds[]: as buscas que encontraram a página.publishedAt: a data de publicação como o mecanismo a informou, ounull.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 emcitedText.own:truequando 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 umid(único em todo o resultado) e otextdo 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 casoparagraphsfica 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;nullquando 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 delinks[], 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.
links[]: uma relação por parágrafo
paragraphId: o parágrafo a que o vínculo se refere. Sempre aponta para um parágrafo que existe emsources[].answerRanges[]: as partes da resposta a que este parágrafo corresponde, como paresstart/endnos 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 embrands[].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: orankda sua marca embrands[].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[].errorestá 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 obodyse 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_foundsignifica 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
answerde 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[].errorsem 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.