Veja onde sua marca fica de fora de uma resposta de IA

O Citation Analysis mostra em quais páginas uma resposta de IA se apoiou, onde sua marca está e o que fazer, começando pelo seu próprio site.

O que muda

• queries: as buscas que o motor fez, cada uma com as páginas encontradas.
• sources: cada página que o motor recuperou, com cited para separar as citadas das demais, a position na busca, os trechos que o motor disse citar, as marcas que a página menciona e um channel que diz quem a controla: seu site, outra marca, um veículo, uma loja, uma plataforma de avaliações, uma comunidade, vídeo, redes sociais, uma plataforma de blogs ou uma obra de referência.
• brands: sua marca, seus concorrentes e cada marca que a resposta cita, na ordem da resposta, com as páginas citadas e recuperadas que mencionam cada uma.
• visibility: a etapa que sua marca alcançou, de citada na resposta a ausente das páginas que lemos.
• actions: o que fazer, na ordem do que depende de você: primeiro suas páginas, depois as plataformas onde você pode publicar e por último os veículos a quem fazer uma proposta. Cada ação traz steps concretos e as páginas que a sustentam.
• insights: o que as páginas citadas têm em comum, como canal, formato, atualidade e critérios, e onde sua marca está, cada leitura com as páginas e links em que se apoia.

A resposta de POST /v1/citation-analysis agora traz version: 4 e esses novos campos. links mantém o formato, cada insight passa a listar suas páginas em sourceIds ao lado de linkIds, e os resultados salvos antes desta mudança mantêm o formato com que foram salvos. O produto agora se chama Citation Analysis: /v1/source-influence e /v1/geo-audit, os taskTypes SOURCE_INFLUENCE e GEO_AUDIT, e include.sourceInfluence e include.geoAudit continuam funcionando, e as respostas usam /v1/citation-analysis, CITATION_ANALYSIS e citationAnalysis.

Como funciona

Com um taskId, as buscas e as páginas recuperadas vêm da própria tarefa de resposta quando o motor as expõe, como o ChatGPT e o Google AI Overview. Você também pode enviá-las em queries e como citations com cited: false. Os demais motores listam as páginas citadas.

As recomendações vêm principalmente de páginas de terceiros. Nas respostas do ChatGPT que estudamos, o motor recuperou uma mediana de 20 páginas e citou 3, e o site próprio de uma marca recomendada foi recuperado em 16% dos casos e citado em 6,8%. As ações seguem esse caminho, começando pelo que está nas suas mãos:

• improve_page: sua página que o motor recuperou e deixou passar, ou que citou enquanto a resposta deixa sua marca de fora, com o que acrescentar para que ela responda ao prompt como as páginas citadas.
• publish_page: um briefing de página nova no seu site para uma busca em que nenhuma página sua foi citada, com base nas páginas citadas: tipo de página, padrão de título, seções, evidências e data.
• post_on_platform: uma página de loja, plataforma de avaliações, comunidade, vídeo ou rede social que menciona seus concorrentes, com passos como completar seu anúncio, pedir avaliações a clientes reais ou responder identificado como representante da marca.
• pitch_publisher: uma página editorial citada que só o veículo pode alterar, com o que enviar a ele.

Cada correspondência mostra qual página diz o que a resposta diz, e cada ação aponta para as páginas exatas em que se apoia. A etapa not_found significa que nenhuma página lida menciona sua marca. Envie brand para receber visibility e actions, e adicione brandDomains e brandAliases para contar suas páginas e seus outros nomes.

Onde ajuda

• Comece pelo seu próprio site: refaça a página que o motor deixou passar ou planeje uma nova com base nas citadas.
• Entregue à sua equipe de marketplaces e comunidades os anúncios e tópicos em que seus concorrentes aparecem.
• Faça propostas aos veículos com a página exata e os trechos que a resposta aproveitou.

Envie a requisição

Envie a requisição com a sua chave de API no cabeçalho Authorization.

curl -X POST https://api.querying.ai/v1/citation-analysis \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskId": "…",
    "brand": "Blueair",
    "competitors": ["Coway", "Levoit"],
    "brandDomains": ["blueair.com"]
  }'

Campos da requisição

taskIdstringObrigatório

Uma tarefa de resposta sua já concluída. A resposta e as páginas citadas viram answer e citations.

brandstring

O nome da sua marca. Com ele, o resultado ganha visibility e actions.

competitorsarray

Nomes dos concorrentes acompanhados na resposta e nas páginas.

brandDomainsarray

Até 10 hostnames dos seus sites, como coway.com. As páginas deles contam como own.

brandAliasesarray

Até 10 outros nomes da sua marca, como linhas de produto ou grafias locais.

citations[].citedboolean

Padrão true. Envie false para uma página que o motor recuperou e não citou, com position e query se tiver.

countrystring

País de onde as páginas citadas são lidas. Padrão US.

webhook.urlstring

Um endereço HTTPS do seu servidor. A tarefa concluída é enviada para lá assim que termina.

idempotencyKeystring

Seu próprio ID para a requisição. Cada chave cria uma única tarefa por conta, então um reenvio continua sendo uma tarefa.

Resposta

Uma tarefa concluída chega assim, resumida para facilitar a leitura.

{
  "success": true,
  "task": {
    "id": "…",
    "taskType": "CITATION_ANALYSIS",
    "status": "COMPLETED",
    "createdAt": "…"
  },
  "credits": { "creditsToCharge": "…", "creditsCharged": "…" },
  "response": {
    "version": 4,
    "answer": "The best-reviewed air purifiers depend on whether you …",
    "queries": [
      {
        "id": "q0",
        "text": "best air purifiers 2026 reviews independent testing …",
        "sourceIds": ["s0", "s1", "s2", "…", "s20"]
      }
    ],
    "sources": [
      {
        "id": "s13",
        "url": "https://www.blueair.com/products/blue-pure-211i-max",
        "domain": "blueair.com",
        "channel": "own",
        "cited": false,
        "position": 14,
        "queryIds": ["q0"],
        "publishedAt": null,
        "citedText": [],
        "brandIds": ["b0"],
        "own": true,
        "paragraphs": []
      },
      {
        "id": "s14",
        "url": "https://www.target.com/p/levoit-core-300-air-…",
        "domain": "target.com",
        "channel": "retailer",
        "cited": true,
        "position": 15,
        "queryIds": ["q0"],
        "publishedAt": null,
        "citedText": [
          "A compact, straightforward option with a 4.6/5 rating …"
        ],
        "brandIds": ["b2"],
        "own": false,
        "paragraphs": [
          {
            "id": "s14p1",
            "text": "Levoit Core 300 Air Purifier White … $99.99 …"
          }
        ]
      },
      "…"
    ],
    "brands": [
      {
        "id": "b0",
        "name": "Blueair",
        "role": "target",
        "rank": 2,
        "answerRanges": ["…"],
        "citedSourceIds": ["s1", "s3", "s11"],
        "retrievedSourceIds": ["s5", "s6", "s8", "s9", "s13"],
        "ownSourceIds": ["s11", "s13"]
      },
      {
        "id": "b1",
        "name": "Coway",
        "role": "competitor",
        "rank": 1,
        "answerRanges": ["…"],
        "citedSourceIds": ["s1", "s3", "s4", "s7"],
        "retrievedSourceIds": ["s0", "s5", "s6", "s9", "s10", "s18"],
        "ownSourceIds": []
      },
      {
        "id": "b2",
        "name": "Levoit",
        "role": "competitor",
        "rank": 3,
        "answerRanges": ["…"],
        "citedSourceIds": ["s3", "s7", "s14"],
        "retrievedSourceIds": ["s6", "s15", "s16"],
        "ownSourceIds": []
      },
      "…"
    ],
    "links": [
      {
        "id": "l40",
        "paragraphId": "s14p1",
        "answerRanges": ["…"],
        "explanation": "Lists the Levoit Core 300 at $99.99, …"
      },
      "…"
    ],
    "visibility": {
      "brandId": "b0",
      "stage": "mentioned",
      "rank": 2,
      "answerBrands": 5
    },
    "actions": [
      {
        "id": "a0",
        "type": "improve_page",
        "control": "owned",
        "priority": 1,
        "summary": "Update Blueair’s site with a current, …",
        "steps": [
          "Add a page on best air purifiers in 2026 that covers …",
          "Include Blueair models in direct comparisons using published …",
          "…"
        ],
        "sourceIds": ["s13"],
        "brandIds": ["b0"],
        "queryIds": ["q0"],
        "linkIds": []
      },
      {
        "id": "a1",
        "type": "post_on_platform",
        "control": "platform",
        "priority": 2,
        "summary": "Improve Blueair’s Target product listing with …",
        "steps": [
          "Ensure the Blueair listing clearly states the model, current …",
          "…",
          "Keep product details current and invite genuine purchasers to …"
        ],
        "sourceIds": ["s14"],
        "brandIds": ["b2"],
        "queryIds": ["q0"],
        "linkIds": ["l40"]
      },
      "…"
    ],
    "insights": [
      {
        "summary": "Blueair’s second-place position is reflected in …",
        "sourceIds": ["s1", "s3", "s11"],
        "linkIds": ["l1", "l12", "l36"]
      },
      "…"
    ]
  }
}

task.statusstring

QUEUED, PROCESSING e, no fim, COMPLETED com a resposta ou FAILED com error.

credits.creditsChargedinteger

Créditos cobrados pela tarefa concluída. Uma tarefa que falhou cobra 0.

response.versionnumber

O formato do resultado. 4 nas análises com buscas, páginas recuperadas, marcas e ações.

response.answerstring

A resposta enviada, exatamente como está. Os intervalos são posições UTF-16 deste mesmo texto.

response.queriesarray

As buscas que o motor fez, cada uma com id, o text e os sourceIds encontrados.

response.sourcesarray

Cada página que o motor recuperou. cited separa as citadas das demais e channel diz quem controla a página (own, brand, editorial, retailer, review_platform, community, video, social, blog_platform ou reference). Também traz position, queryIds, citedText, brandIds e own. As citadas trazem paragraphs.

response.brandsarray

Sua marca, seus concorrentes e as marcas que a resposta cita, cada uma com role, o rank na resposta, answerRanges e as páginas citadas e recuperadas que a mencionam.

response.linksarray

Cada link liga um parágrafo aos answerRanges correspondentes e a uma explanation de uma frase.

response.visibilityobject

Até onde sua marca chegou: stage é mentioned, on_cited_page, on_retrieved_page ou not_found, com rank e answerBrands. null sem brand.

response.actionsarray

O que fazer, por priority: primeiro o trabalho owned no seu site (improve_page, publish_page), depois as publicações platform (post_on_platform) e por último o outreach (pitch_publisher). Cada ação traz seu control, um summary, de 1 a 5 steps e as fontes, marcas, buscas e links que a sustentam. Vazio sem brand.

response.insightsarray

Até 4 leituras curtas do que as páginas citadas têm em comum e de onde sua marca está, cada uma com as páginas em sourceIds e os links em linkIds.

Receba o resultado

A requisição devolve a tarefa na hora, com status QUEUED. Consulte GET /v1/async/task/{id} até status virar COMPLETED ou FAILED, ou adicione webhook.url e a tarefa concluída chega ao seu servidor com os mesmos task, credits e response. Os resultados ficam disponíveis por 24 horas após o fim da tarefa.

curl https://api.querying.ai/v1/async/task/$TASK_ID \
  -H "Authorization: Bearer $QUERYING_API_KEY"

Preço

O preço continua o mesmo: os créditos são reservados quando a análise começa e acertados quando ela termina.