> ## Documentation Index > Fetch the complete documentation index at: https://docs.querying.ai/llms.txt > Use this file to discover all available pages before exploring further. # Citation Analysis > Diagnóstico de visibilidade em IA por prompt: as buscas que um mecanismo fez, as páginas que ele recuperou e citou, as marcas que a resposta nomeia e as páginas por trás delas, a posição da sua marca e ações priorizadas 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. ```bash theme={"theme":"css-variables"} curl -X POST https://api.querying.ai/v1/citation-analysis \ -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \ -d '{ "answer": "…the AI answer, as raw markdown…", "prompt": "best password manager for a small team", "engine": "CHATGPT", "brand": "1Password", "competitors": ["Bitwarden"], "citations": [ { "url": "https://example.com/best-password-managers", "body": "…the page markdown…" }, { "url": "https://another.example.com/pricing" } ] }' ``` 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: ```bash theme={"theme":"css-variables"} curl -X POST https://api.querying.ai/v1/citation-analysis \ -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \ -d '{ "taskId": "7c1f…", "brand": "1Password", "competitors": ["Bitwarden"] }' ``` 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`. ```bash theme={"theme":"css-variables"} curl -X POST https://api.querying.ai/v1/async/task \ -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \ -d '{ "taskType": "CHATGPT", "payload": { "prompt": "best password manager for a small team", "country": "US", "include": { "citationAnalysis": true } }, "webhook": { "url": "https://example.com/hook" } }' ``` 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 | Campo | Obrigatório | Observações | | - | - | - | | `taskId` | no lugar de `answer` + `citations` | Uma tarefa de resposta sua já concluída; veja acima. | | `answer` | sim, exceto com `taskId` | Markdown original da resposta, 1–200.000 caracteres. Não altere; cada intervalo é um offset UTF-16 exatamente neste texto. | | `citations[]` | sim, exceto com `taskId` | As páginas que o mecanismo citou e, opcionalmente, páginas que ele recuperou mas não citou: no máximo 100 citadas e 50 não citadas, pelo menos uma citada, no máximo 10 URLs de threads de discussão. | | `citations[].url` | sim | URL HTTP(S), no máximo 2.048 caracteres. | | `citations[].body` | não | Markdown da fonte, no máximo 300.000 caracteres por citação; o corpo inteiro da requisição tem no máximo 1 MiB. Um corpo enviado é analisado como está e nunca substituído por uma busca atual. Sem corpo, buscamos a página; uma página que não pôde ser lida é informada naquela fonte com `error`. | | `citations[].kind` | não | `inline` ou `panel`; detectado pelos links da resposta quando omitido. | | `citations[].cited` | não | Padrão `true`. `false` marca uma página que o mecanismo recuperou (um resultado de busca) mas não citou. | | `citations[].position` | não | Inteiro ≥ 1: a posição que o próprio mecanismo deu à página nos resultados de busca. | | `citations[].query` | não | A busca (≤ 500 caracteres) que encontrou a página; adicionada a `queries` se faltar. | | `citations[].citedText[]` | não | Até 20 trechos (≤ 2.000 caracteres cada) que o próprio mecanismo informou ter citado. | | `citations[].publishedAt` | não | Data de publicação como o mecanismo a informou, ≤ 64 caracteres. | | `queries[]` | não | Até 20 buscas que o mecanismo fez, ≤ 500 caracteres cada. | | `prompt` | não | Pergunta original. | | `engine` | não | Qual mecanismo de IA produziu a resposta. | | `brand` | não | O nome da sua marca. Com ele, o resultado inclui `visibility` e `actions`. | | `brandDomains[]` | não | Até 10 hostnames dos sites próprios da sua marca, como `coway.com`: apenas o hostname, sem esquema nem caminho, com letras, dígitos, pontos e hífens, até 253 caracteres. Exige `brand`; enviado sem ele, a requisição é rejeitada com `422`. Sem `brandDomains`, um host cujo nome contém o nome da marca conta como site próprio da marca. | | `brandAliases[]` | não | Até 10 outros nomes da sua marca (linhas de produto, grafias locais), cada um com ≤ 200 caracteres. Exige `brand`; enviado sem ele, a requisição é rejeitada com `422`. | | `competitors[]` | não | Até 25 nomes de concorrentes, informados em `brands` com papel `competitor`. | | `country` | não | País usado para buscar as fontes, padrão `US`. | 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. > [!WARNING] > > 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`. ```json theme={"theme":"css-variables"} { "version": 4, "answer": "For most homes, the Coway Airmega 250 is the best all-round pick. Levoit Core 300 is a strong budget choice, and Blueair Blue Pure 211+ suits large rooms.", "queries": [ { "id": "q0", "text": "best air purifiers 2026 reviews", "sourceIds": ["s0", "s1", "s2"] } ], "sources": [ { "id": "s0", "url": "https://www.example-reviews.com/best-air-purifiers", "domain": "example-reviews.com", "channel": "editorial", "cited": true, "position": 1, "queryIds": ["q0"], "publishedAt": "October 7, 2026", "citedText": ["Levoit Core 300 is the best budget purifier we tested."], "brandIds": ["b1", "b2"], "own": false, "paragraphs": [ { "id": "s0p0", "text": "Levoit Core 300 is the best budget purifier we tested." }, { "id": "s0p1", "text": "For large rooms, the Blueair Blue Pure 211+ cleared the air fastest." } ] }, { "id": "s1", "url": "https://www.coway.com/airmega-250", "domain": "coway.com", "channel": "own", "cited": false, "position": 4, "queryIds": ["q0"], "publishedAt": null, "citedText": [], "brandIds": ["b0"], "own": true, "paragraphs": [] }, { "id": "s2", "url": "https://www.reddit.com/r/AirPurifiers/comments/abc123/budget_pick", "domain": "reddit.com", "channel": "community", "cited": true, "position": 6, "queryIds": ["q0"], "publishedAt": null, "citedText": [], "brandIds": ["b1"], "own": false, "paragraphs": [ { "id": "s2p0", "text": "Two years with the Levoit Core 300 and it is still quiet on sleep mode." } ] } ], "brands": [ { "id": "b0", "name": "Coway", "role": "target", "rank": 1, "answerRanges": [{ "start": 20, "end": 25 }], "citedSourceIds": [], "retrievedSourceIds": ["s1"], "ownSourceIds": ["s1"] }, { "id": "b1", "name": "Levoit", "role": "competitor", "rank": 2, "answerRanges": [{ "start": 66, "end": 72 }], "citedSourceIds": ["s0", "s2"], "retrievedSourceIds": [], "ownSourceIds": [] }, { "id": "b2", "name": "Blueair", "role": "answer", "rank": 3, "answerRanges": [{ "start": 113, "end": 120 }], "citedSourceIds": ["s0"], "retrievedSourceIds": [], "ownSourceIds": [] } ], "links": [ { "id": "l0", "paragraphId": "s0p0", "answerRanges": [{ "start": 66, "end": 154 }], "explanation": "Names the Levoit Core 300 as the budget pick." }, { "id": "l1", "paragraphId": "s0p1", "answerRanges": [{ "start": 66, "end": 154 }], "explanation": "Recommends the Blueair Blue Pure 211+ for large rooms." }, { "id": "l2", "paragraphId": "s2p0", "answerRanges": [{ "start": 66, "end": 154 }], "explanation": "Reports long-term use of the Levoit Core 300." } ], "visibility": { "brandId": "b0", "stage": "mentioned", "rank": 1, "answerBrands": 3 }, "actions": [ { "id": "a0", "type": "improve_page", "control": "owned", "priority": 1, "summary": "Coway's Airmega 250 page was retrieved for this search but not cited.", "steps": [ "Add a table of room coverage, noise level and yearly filter cost, the criteria the cited review compares.", "Show when the specifications were last updated." ], "sourceIds": ["s1"], "brandIds": ["b0"], "queryIds": ["q0"], "linkIds": [] }, { "id": "a1", "type": "publish_page", "control": "owned", "priority": 2, "summary": "No Coway page was cited for this search; the cited review is a dated buying guide.", "steps": [ "Publish a 2026 air purifier buying guide on coway.com, organized by room size and budget.", "Explain how models were compared, show measured results, and name the author and date." ], "sourceIds": ["s0"], "brandIds": ["b0"], "queryIds": ["q0"], "linkIds": ["l0", "l1"] }, { "id": "a2", "type": "post_on_platform", "control": "platform", "priority": 3, "summary": "A cited Reddit thread recommends Levoit and never mentions Coway.", "steps": [ "Reply as an identified Coway representative with the Airmega 250 details the thread asks about." ], "sourceIds": ["s2"], "brandIds": ["b1"], "queryIds": ["q0"], "linkIds": ["l2"] }, { "id": "a3", "type": "pitch_publisher", "control": "outreach", "priority": 4, "summary": "The top cited review names Levoit and Blueair but not Coway; only its publisher can add the Airmega 250.", "steps": [ "Offer the editors an Airmega 250 for testing.", "Send test data for the criteria the review uses: room coverage, noise and filter cost." ], "sourceIds": ["s0"], "brandIds": ["b1", "b2"], "queryIds": ["q0"], "linkIds": ["l0", "l1"] } ], "insights": [ { "summary": "Both cited pages recommend Levoit for a budget; the review also backs Blueair for large rooms.", "sourceIds": ["s0", "s2"], "linkIds": ["l0", "l1", "l2"] }, { "summary": "The answer names Coway first, yet no cited page names it; only its own page, which was not cited, does.", "sourceIds": ["s1"], "linkIds": [] } ] } ``` ### `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. ### `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 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. | `type` | `control` | Quando aparece | `sourceIds` | | - | - | - | - | | `improve_page` | `owned` | Uma por site seu: as suas próprias páginas nele foram recuperadas mas não citadas, ou citadas enquanto a resposta não nomeia a sua marca. Os passos dizem o que acrescentar ou mudar para que as páginas respondam ao prompt como as páginas citadas fazem: critérios, números, atualidade. | Até três das suas páginas nesse site, primeiro as não citadas. | | `publish_page` | `owned` | Para uma busca em que nenhuma das suas páginas foi citada: um briefing para uma nova página no seu próprio site, com base nas páginas citadas: tipo de página e título, seções e critérios, evidências a mostrar, data, autoria clara da marca. | As páginas citadas a tomar como modelo. | | `post_on_platform` | `platform` | Uma página em um varejista, plataforma de avaliações, comunidade, plataforma de vídeo, rede social ou plataforma de blogs nomeia marcas rivais, mas não a sua. A ação é o anúncio, o perfil, a resposta ou a publicação da própria marca nessa plataforma, pela sua própria conta: cadastrar ou melhorar o seu produto, reivindicar o seu perfil e pedir avaliações a clientes reais, responder como representante identificado da marca ou publicar uma demonstração ou comparação. Nunca pede nada à plataforma nem ao dono da página. No máximo uma por domínio. | A página citada nessa plataforma, que é de outra pessoa. | | `pitch_publisher` | `outreach` | Uma página editorial citada nomeia marcas rivais, mas não a sua, ou nomeia a sua enquanto a resposta não. Só o editor pode alterá-la; os passos dizem o que enviar. | A página a propor ao editor. | `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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.