> ## 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.

# Source Influence

> Quais parágrafos de uma página citada correspondem a quais partes de uma resposta de IA, com intervalos exatos, uma explicação curta para cada vínculo e resumos curtos montados a partir desses vínculos

Compare uma resposta de IA concluída com as fontes que ela citou. O resultado é um mapa compacto: os parágrafos de
cada página de origem incluídos no resultado, as partes da resposta a que eles correspondem, uma explicação para cada
vínculo e resumos curtos montados a partir desses vínculos.

É 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={null}
curl -X POST https://api.querying.ai/v1/source-influence \
  -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: "SOURCE_INFLUENCE"`. Não envie esta análise por `POST /v1/async/task`: use o endpoint dedicado.
`POST /v1/research` e o tipo de tarefa `CITATION_ATTRIBUTION` são os nomes anteriores a setembro de 2026 e continuam
funcionando como aliases obsoletos.

### 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={null}
curl -X POST https://api.querying.ai/v1/source-influence \
  -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`.

## 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` | 1–100 fontes, 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. |
| `prompt` | não | Pergunta original. Mantido por compatibilidade com integrações existentes; não é retornado no resultado. |
| `engine` | não | Qual mecanismo de IA produziu a resposta. Mesmo contexto de compatibilidade, não é retornado. |
| `brand` | não | O nome da sua marca. Mesmo contexto de compatibilidade, não é retornado. |
| `competitors[]` | não | Até 25 nomes de concorrentes. Mesmo contexto de compatibilidade, não é retornado. |
| `country` | não | País usado para buscar as fontes, padrão `US`. |

<Warning>
  A opção `analysis` foi descontinuada.
  Versões anteriores aceitavam `analysis: {version: 1, …}`. Agora os insights fazem parte de todo resultado, então esse
  campo é rejeitado com `400` em vez de ignorado: remova-o das integrações existentes. O conteúdo das tarefas existentes
  continua legível; os registros armazenados não são migrados.
</Warning>

## Resultado

```json theme={null}
{
  "answer": "Teams plan starts at $19.95 per month for up to 10 users. The Business plan adds audit logs.",
  "sources": [
    {
      "id": "s1",
      "url": "https://example.com/pricing",
      "paragraphs": [
        { "id": "p1", "text": "Teams: $19.95 / month, up to 10 users." },
        { "id": "p2", "text": "Business adds audit logs and SSO." }
      ]
    },
    {
      "id": "s2",
      "url": "https://review.example.com/note",
      "paragraphs": [],
      "error": "…"
    }
  ],
  "links": [
    { "id": "l1", "paragraphId": "p1", "answerRanges": [{ "start": 0, "end": 57 }], "explanation": "States the same price and seat cap." },
    { "id": "l2", "paragraphId": "p2", "answerRanges": [{ "start": 58, "end": 92 }], "explanation": "Names the audit-log add-on." }
  ],
  "insights": [
    { "summary": "The pricing page covers both statements; the review page could not be read.", "linkIds": ["l1", "l2"] }
  ]
}
```

### `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 identifica uma unidade semântica inteira da resposta: uma frase, um item de
lista ou uma célula de tabela. Os limites se referem ao texto original.

### `sources[]`: uma entrada por citação enviada

* `id`: identificador opaco, único dentro do resultado.
* `url`: a URL da citação que você enviou.
* `paragraphs[]`: os parágrafos daquela página 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.
* `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.

### `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.

### `insights[]`

Resumos curtos do que os vínculos deste resultado mostram em conjunto. `linkIds` indica a partir de quais vínculos cada
resumo foi montado e só pode citar vínculos que aparecem em `links[]`: um insight nunca afirma uma relação que a
resposta não contém. Sem vínculos, não há o que resumir.

## 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. Ele não mede influência na geração, não ordena páginas entre si, não dá nota
  à página nem informa como a resposta foi produzida.
* **Os ids são internos.** Não guarde os identificadores `p…`/`l…` 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.