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

# API de monitoramento GEO: menções e citações de marca

> Agende conjuntos de prompts, leia um único contrato de relatório com denominador explícito e exporte as respostas por trás de cada número.

Os monitores repetem um conjunto salvo de prompts conforme uma agenda e pontuam as respostas de IA resultantes para a
sua marca e os concorrentes dela. Esta página é o contrato da API: como configurar um monitor, o que cada número
significa, como ler as fontes por trás dele e como exportar as respostas por baixo. Para ver os mesmos dados no
painel, comece pelo [guia do produto](https://querying.ai/pt/monitors).

Todas as chaves, ids, marcas e prompts desta página são exemplos. Nada aqui é uma credencial ou um monitor real.

## O que é um monitor

Um monitor é um **conjunto nomeado de prompts em um mercado**: uma lista de prompts, os mecanismos que vão recebê-los,
os aliases que significam "sua marca", opcionalmente seus domínios e alguns concorrentes, um país e um intervalo. Cada
execução agendada envia prompts × mecanismos tarefas assíncronas comuns, e cada resposta concluída é pontuada uma vez e guardada.

A pontuação é propositalmente restrita, e os dados não respondem além do que armazenam:

* Ela registra se um alias da marca aparece no texto da resposta e em qual offset de caractere; se a resposta citou um
  dos seus domínios cadastrados; e quais dos concorrentes configurados apareceram na mesma resposta.
* Ela **não** gera nota de sentimento nem estimativa de participação de mercado. Uma posição é um lugar entre as
  marcas que as respostas citam, como no ranking de um monitor de categoria (veja abaixo).

### Os concorrentes são encontrados para você

Você não precisa listar concorrentes. Quando a primeira execução de um monitor termina, lemos as respostas recentes com um
modelo de linguagem e mantemos as marcas que vendem o mesmo que você e aparecem em pelo menos duas respostas, até 15. A
leitura se repete a cada 30 dias, então rivais novos entram e os que deixam de ser citados saem.

* Concorrentes encontrados trazem `source: "auto"`. Os que você adiciona trazem `source: "user"`, e a leitura nunca os
  altera nem remove.
* Quando a lista encontrada muda, as respostas guardadas do monitor são contadas de novo com ela, para que toda marca de um
  relatório seja medida sobre as mesmas respostas. `competitorsReadAt` no monitor mostra quando foi a última leitura.
* Nomes em alfabeto latino batem como palavras inteiras, então "replicates" não conta como menção à marca Replicate.

### Separe os monitores com intenção

Monitores diferentes representam temas ou mercados diferentes e são relatórios separados: cada um tem sua própria
janela, sua própria definição de pontuação e sua própria agenda. Dois hábitos valem a pena:

* Um monitor por tema e mercado, para que a coorte do relatório continue comparável. Misturar "melhor CRM" e "como
  precificar um CRM" em um conjunto faz a média de duas intenções diferentes em um único número.
* Escreva os prompts como um comprador e nunca inclua sua própria marca. Um prompt que contém a marca é sempre uma
  menção, então mostra 100% para sempre e não mede nada. Nomes de concorrentes podem entrar e muitas vezes rendem os
  prompts mais úteis que você pode escrever.

## Monitores de categoria: ordene as marcas de um mercado

Um monitor de marca acompanha uma marca. Um **monitor de categoria** acompanha um mercado: você dá nome à categoria,
agrupa as perguntas por subárea, e o relatório ordena as marcas que os mecanismos citam ao responder. Defina
`"mode": "CATEGORY"` ao criar o monitor. `mode` é `BRAND` por padrão e permanece fixo durante toda a vida do monitor,
porque decide o que cada linha armazenada significa.

```bash theme={null}
curl -X POST "$BASE/v1/monitors" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Sunscreen market",
    "mode": "CATEGORY",
    "category": "Sunscreen",
    "engines": ["CHATGPT", "GEMINI"],
    "prompts": ["best sunscreen for sensitive skin", "best sunscreen for kids"],
    "promptTopics": {
      "best sunscreen for sensitive skin": "Sensitive skin",
      "best sunscreen for kids": "Kids"
    },
    "competitors": [{ "name": "Supergoop" }, { "name": "La Roche-Posay", "aliases": ["LRP"] }],
    "country": "US",
    "intervalHours": 24
  }'
```

| Campo | Em um monitor de categoria |
| - | - |
| `category` | Obrigatório, de 1 a 80 caracteres: o mercado como um comprador o chama. |
| `promptTopics` | Associa um prompt (seu texto exato) à sua subárea. Até 30 subáreas de no máximo 60 caracteres. Um prompt sem entrada cobre a categoria inteira. |
| `competitors` | As marcas a ordenar: até 25 que você lista. Quando a primeira execução termina, a leitura mensal acrescenta até 25 que as respostas citam. |
| `aliases` · `domains` · `alertBelowPct` | Deixe vazios. Um monitor de categoria não tem marca própria, domínio próprio nem alerta, então um valor retorna `400 VALIDATION_ERROR`. |

A agenda, o custo, a janela, os filtros, `quality`, as fontes, as citações, os resultados e as respostas funcionam como
em um monitor de marca. Um monitor de categoria não tem alerta, então `POST /v1/monitors/{id}/alerts/test` retorna `400`.

### O que o relatório ordena

`GET /v1/monitors/{id}/analytics` retorna a visão de categoria. `stats` e `previous` trazem `runs`, `named` (respostas
que citam ao menos uma marca acompanhada) e `namedRate`; `changes.namedRatePp` é a variação em pontos, e o objeto
`category` traz o ranking:

| Campo | O que traz |
| - | - |
| `category.brands` | Cada marca acompanhada que as respostas citaram, primeiro as citadas em mais respostas: `rank`, `mentions`, `sampleSize`, `mentionRate`, `shareOfVoice` e a variação em relação ao intervalo anterior. |
| `category.topics` | Uma linha por subárea (`topic: null` é a categoria inteira) com `runs`, `namedRate` e as três marcas mais citadas. |
| `category.engines` | Uma linha por mecanismo com as três marcas que ele mais cita. |
| `category.series` | Por dia UTC, as taxas das cinco marcas líderes. |
| `category.prompts` | Uma linha por prompt com suas marcas líderes e células por mecanismo; cada célula traz um `evidenceTaskId` para abrir a resposta por trás. |

* **`rank`** ordena as marcas pelo número de respostas que as citam: é uma posição entre as marcas que essas respostas
  citam. Uma marca que nenhuma resposta citou tem `rank: null`.
* **O `mentionRate` de uma marca** divide pelo próprio `sampleSize` dela, as respostas pontuadas enquanto a marca
  estava na lista. Uma marca que você adiciona hoje é medida a partir de hoje.
* **`shareOfVoice`** é `100 × menções dessa marca / todas as menções de marcas acompanhadas` na janela, então as
  participações de uma janela somam 100.
* `GET /v1/monitors` acrescenta `leader` (a marca mais citada, com sua taxa) a cada monitor de categoria. As contagens
  `mentioned` e `cited` dele são sempre `0`.
* `GET /v1/monitors/{id}/answers/{taskId}` retorna `mode`, um `aliases` vazio e as marcas acompanhadas como
  `competitors`.

### Pesquise os prompts pela demanda de busca

`POST /v1/monitors/research` recebe o corpo da requisição de [Prompt Research](/pt/research/prompt-research), custa os
mesmos 12 créditos e retorna o mesmo resultado, enviado em nome da sua conta. Leia a tarefa enfileirada com
`GET /v1/async/task/{id}`; o id está em `data.task.id` na resposta.

```bash theme={null}
curl -X POST "$BASE/v1/monitors/research" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{ "seed": "sunscreen", "country": "US", "monitorSize": 10, "monitorEngines": ["CHATGPT", "GEMINI"] }'
```

Use `monitorSet.prompts` como `prompts`, o `topic` de cada prompt como sua subárea em `promptTopics` e `brands[].brand`
como `competitors`. O botão **Executar pesquisa** do painel faz o mesmo e preenche o formulário; nada é salvo até você
criar o monitor.

## Custo e agenda

Uma execução enfileira uma tarefa por prompt e por mecanismo, ao preço em créditos publicado de cada mecanismo. A agenda
se repete até você pausar ou excluir o monitor, então o que você escolhe ao criá-lo é um custo recorrente:

```text theme={null}
credits per run  = prompts × sum(credits for each engine)
credits / month  ≈ credits per run × (24 × 30) / intervalHours
```

Por exemplo, 12 prompts no ChatGPT (2 créditos) e no Gemini (1 crédito) são 24 tarefas e 36 créditos por execução,
cerca de 1.080 créditos por mês com intervalo diário. Leia os preços atuais no endpoint de capabilities em vez de
fixá-los no código.

Vale conhecer duas propriedades da agenda antes de depender dela:

* Uma execução **não** é uma rajada. As tarefas entram conforme a concorrência do plano e a fila permitem, então uma
  execução acima do limite de um plano gratuito chega ao longo de alguns minutos em vez de ser descartada. Acompanhe
  `health.pending` em um relatório para ver uma execução em andamento.
* A próxima janela é um horário, não uma garantia. `nextRunAt` é quando a execução vence; um monitor pausado por uma
  semana volta um intervalo depois de ser reativado, sem disparar as execuções perdidas.

Encontrar seus concorrentes acrescenta 100 créditos por mês por monitor, divididos entre as execuções conforme o
intervalo: cerca de 3 créditos por execução num monitor diário e cerca de 23 num semanal. A cobrança acontece depois
que todas as tarefas de uma execução entram, então uma execução que seu saldo parou não paga nada por isso.

## Endpoints

| Método e caminho | O que entrega |
| - | - |
| `GET /v1/monitors/capabilities` | Mecanismos com seus preços em créditos, limites, definições das métricas e a conta da agenda. Uma leitura barata e sem efeitos colaterais. |
| `GET /v1/monitors` | Seus monitores, cada um com um resumo de 30 dias. |
| `POST /v1/monitors` | Cria e inicia um monitor. |
| `GET /v1/monitors/{id}` | Detalhe de período legado. Use `/analytics` no lugar: este mistura uma matriz de células de todo o histórico, sem filtro, com os números da janela e corta as citações em 12 domínios e 20 páginas. |
| `PATCH /v1/monitors/{id}` | Atualiza campos, ou envie `enabled` para pausar e retomar. |
| `DELETE /v1/monitors/{id}` | Exclui o monitor e seu histórico pontuado. |
| `POST /v1/monitors/{id}/run` | Antecipa a próxima execução para agora. Consome créditos como qualquer execução. |
| `GET /v1/monitors/{id}/analytics` | **O contrato do relatório.** Uma coorte, um conjunto de filtros, todas as seções. |
| `GET /v1/monitors/{id}/sources` | Domínios ou páginas citados na mesma janela, paginados. |
| `GET /v1/monitors/{id}/citations` | Série diária de citações dos principais domínios e páginas: os dados dos gráficos de citações do painel. |
| `GET /v1/monitors/{id}/results` | As linhas pontuadas em si, em JSON ou CSV, com filtros e cursor. |
| `GET /v1/monitors/{id}/answers/{taskId}` | A resposta guardada por trás de uma linha. |
| `GET /v1/monitors/{id}/prompt` | Detalhamento de um prompt: sua série, fontes e linhas recentes. |
| `GET /v1/monitors/{id}/alerts` · `POST .../alerts/test` | Limite de alerta, estado de trava e histórico de envios; enfileira um e-mail de teste. |
| `POST /v1/monitors/suggest` | Prompts candidatos a partir de informações da marca. Não salva nada e não consome créditos de tarefa. |
| `POST /v1/monitors/research` | Pesquisa de prompts para um monitor: a requisição, o preço e o resultado de [Prompt Research](/pt/research/prompt-research), enviados em nome da sua conta. |

Todos usam a mesma chave bearer do restante da API (veja [Autenticação](/pt/authentication)). Um monitor de outra conta
responde `404`, não `403`.

## Crie um monitor

```bash theme={null}
curl -X POST "$BASE/v1/monitors" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Earbud brand tracking",
    "engines": ["CHATGPT", "GEMINI"],
    "prompts": ["best wireless earbuds for commuting", "are cheap earbuds worth it"],
    "aliases": ["Acme Audio", "Acme"],
    "domains": ["example.com"],
    "competitors": [{ "name": "Sony", "aliases": ["Sony"] }],
    "country": "US",
    "intervalHours": 24
  }'
```

`name`, `engines`, `prompts`, `aliases` e `intervalHours` são obrigatórios em um monitor de marca; um monitor de categoria recebe `category` no lugar de `aliases`. Cada lista aceita um array ou uma única
string separada por quebras de linha; as entradas são aparadas, linhas vazias descartadas e duplicatas removidas.
`country` escolhe o mercado para o qual os mecanismos respondem e não traduz os prompts. `prompts × engines` precisa
ficar igual ou abaixo do limite `tasksPerRun` de capabilities.

Os mecanismos são as superfícies de prompt agendáveis: `CHATGPT`, `GEMINI`, `PERPLEXITY`, `GOOGLE`, `AIMODE`,
`NAVER_AI_BRIEF`, `NAVER_AI_TAB` e o alias obsoleto `NAVER`. `GOOGLE_AIO` e `GOOGLE_AIMODE` são aceitos e salvos como
`GOOGLE` e `AIMODE`. Tarefas de análise como `SOURCE_INFLUENCE` não são superfícies de prompt e não podem ser agendadas
em um monitor.

Uma chave restrita a alguns mecanismos só pode agendar esses mecanismos; qualquer outro resulta em
`403 KEY_SCOPE_DENIED`. O limite de monitores da conta retorna `409 MONITOR_LIMIT`.

## Execute e depois leia o relatório

`POST /v1/monitors/{id}/run` faz a próxima execução vencer imediatamente, e as tarefas de resposta aparecem em cerca de
um minuto. Ela é cobrada como uma execução agendada, e repetir a chamada enquanto aquela janela ainda está vencida não
cobra duas vezes.

`GET /v1/monitors/{id}/analytics` é o contrato de onde deve sair cada parte do seu relatório. A janela é
**semiaberta e em UTC** (`since` inclusivo, `until` exclusivo), e você a escolhe de uma destas duas formas:

| Parâmetro | Regra |
| - | - |
| `days` | Um de `7`, `30` (padrão) ou `90`, terminando agora. Não pode ser combinado com `since`/`until`. |
| `since` e `until` | Os dois juntos, como instantes ISO completos **com fuso horário** (por exemplo `2026-09-15T00:00:00Z`). O intervalo precisa ser positivo, ter no máximo 90 dias e não estar no futuro. Um `YYYY-MM-DD` sozinho é rejeitado aqui, porque não define uma janela portável. |

Dois filtros opcionais se aplicam a **todas** as seções ao mesmo tempo: `engine` (id canônico ou alias público) e
`prompt` (texto exato, até 2.000 caracteres). As linhas são indexadas pelo texto do prompt, então um prompt removido
depois do monitor continua consultável.

Todas as seções compartilham essa coorte, e o intervalo anterior tem exatamente a mesma duração e os mesmos filtros,
então a comparação é equivalente:

| Campo | O que contém |
| - | - |
| `window` | `since`, `until`, `previousSince`, `previousUntil`, `timezone` e os `bounds` literais da janela. `previousUntil` é sempre o `since` desta janela. |
| `filters` | Os filtros aplicados, já resolvidos: o id canônico do mecanismo, o prompt exato ou `null`. |
| `stats` · `previous` | Contagens e taxas da janela e do intervalo anterior. |
| `changes` | Variações em pontos percentuais, ou `null` quando a comparação não é confiável (veja abaixo). |
| `engineRates` | As mesmas taxas por mecanismo, para que um mecanismo fraco apareça sem precisar ler um gráfico. |
| `series` | Por dia UTC e mecanismo, com `partial` marcando um dia cortado pela borda da janela. |
| `brands` | Sua marca (`__you__`) e cada concorrente acompanhado, do mais mencionado para o menos, cada um com seu próprio `sampleSize` e a taxa medida sobre ele. |
| `voiceSeries` | As mesmas marcas por dia UTC, para a linha de tendência. |
| `prompts` | Totais por prompt, da menor taxa de menção para a maior, cada um com suas células por mecanismo. |
| `opportunities` | Células em que um concorrente foi mencionado e sua marca não, das que mais perderam para as que menos perderam. A lista para trabalhar. |
| `quality` | Do que a amostra é feita e tudo o que os números não conseguem dizer. |
| `health` · `healthScope` | Saúde de execução das tarefas ainda visíveis individualmente: um escopo recente separado, nunca parte do denominador. |

## O que os números significam

Leia isto antes de dar nome a um painel. As definições são o contrato publicado, e `GET /v1/monitors/capabilities` as
retorna como `metrics` para que um cliente possa exibi-las ao lado dos números.

* **`mentionRate`** da janela, dos grupos por mecanismo e dos grupos por célula é
  `100 × respostas com menção / respostas pontuadas`. É ponderado por respostas, não uma média das taxas por mecanismo,
  então um mecanismo movimentado não é sufocado por um quieto. (A taxa própria de uma marca tem denominador próprio,
  explicado a seguir.)
* **`citationRate`** tem o mesmo formato para as respostas que citaram um dos seus domínios cadastrados. Sem domínios
  cadastrados, é sempre zero, porque o rastreamento de citações fica desligado.
* **A taxa de uma marca divide pelo próprio `sampleSize`, não pelo total da janela.** Para sua marca, são todas as
  respostas pontuadas; para um concorrente, só as respostas pontuadas enquanto ele estava no monitor. Adicione um
  concorrente hoje e o primeiro relatório dele cobre as respostas que o mediram: o histórico anterior não conta contra
  ele. Uma marca sem respostas elegíveis informa `mentionRate: null`, não 0%, porque 0% seria lido como um sumiço real.
* **`shareOfVoice`** em `brands` é `100 × menções daquela marca / todas as menções das marcas acompanhadas` na janela,
  então as participações de uma janela somam 100. Ele compara marcas dentro das respostas **que você coletou para
  estes prompts**; não é participação de mercado nem ranking de visibilidade. O `shareOfVoice` do endpoint de detalhe
  legado é a visão antiga de penetração nas respostas, em que cada marca é contada em relação às respostas coletadas e
  os números podem somar mais de 100. Não misture os dois no mesmo gráfico.
* **`competitorOnly`** (e a lista `opportunities`) conta as respostas que citaram um concorrente configurado enquanto
  sua marca estava ausente. É a lacuna sobre a qual você pode agir.
* **As taxas são anuláveis, não zero.** Sem respostas na janela, o valor é `null`; uma taxa zero significa que houve
  respostas e nenhuma correspondeu.
* **Uma observação concluída sem resposta conta como não mencionada.** Ela fica no denominador, e
  `quality.noAnswerObservations` diz quantas houve. Uma tarefa **com falha** é excluída de todas as taxas e aparece só
  em `health`: um mecanismo quebrado encolhe a amostra em vez de virar ausência em silêncio, e `quality` nunca a
  reconstrói como ausência (`historicalFailures` é sempre `null`).
* **Variações são retidas quando enganariam.** `changes` e o `mentionRateChangePp` por célula ficam `null`, e
  `quality.comparable` fica `false`, quando um período não tem respostas (`insufficient_periods`), quando há linhas
  pontuadas antes de existir o contexto de pontuação (`legacy_scoring_unknown`) ou quando a definição de pontuação
  mudou entre os períodos (`scoring_definitions_changed`). Linhas históricas mantêm as definições com que foram
  pontuadas (`quality.scoring`), então mudar aliases ou concorrentes nunca reescreve o passado. A única exceção é a leitura mensal de concorrentes descrita acima.
* **O tamanho da amostra é publicado.** `quality.lowSample` é true abaixo de 30 respostas pontuadas,
  `quality.missingCells` conta as células prompt × mecanismo configuradas ainda sem respostas, e `quality.partialDays`
  aponta os dias UTC que a janela corta ao meio: a contagem menor de um dia parcial é aritmética, não queda.

`position` em uma linha pontuada é o **offset de caractere** da primeira ocorrência de alias no texto da resposta: um
indicador aproximado de destaque, não um ranking. É `null` quando a marca não aparece, e por isso `0` nunca precisa
significar "ausente".

## De onde vêm as respostas

`GET /v1/monitors/{id}/sources` responde a "quais páginas estão ganhando estes prompts", com a mesma janela e os mesmos
filtros do relatório, contando **respostas distintas** em vez de citações brutas, então uma página citada três vezes em
uma resposta conta uma vez.

| Parâmetro | Regra |
| - | - |
| `groupBy` | `domain` (padrão, host sem `www.`) ou `page` (URL completa com seu rótulo). |
| `limit` | 1–100, padrão 20. |
| `cursor` | O `nextCursor` da resposta anterior, devolvido sem alterações. `null` encerra a lista. |
| `days` / `since`+`until` / `engine` / `prompt` | Exatamente como no relatório. |

Cada linha traz `citations` e `prompts` (ambos contagens de respostas distintas), `own` para seus domínios cadastrados e
um `evidenceTaskId` que você pode abrir com o endpoint de respostas. Não há corte silencioso dos N primeiros: todo
domínio ou página da janela pode ser alcançado seguindo o cursor.

## Citações ao longo do tempo

`GET /v1/monitors/{id}/citations` devolve os dados dos gráficos de citações do painel: o total
diário de citações da janela e uma série diária para cada domínio e página principal. Ele só lê
resultados armazenados, então não gasta créditos.

| Parâmetro | Regra |
| - | - |
| `days` | `7`, `30` ou `90`; padrão `30`. |
| `since`+`until` | Uma janela fixa de até 90 dias, como no relatório. Quando informado, `days` é só um rótulo. |
| `engine` / `prompt` | Como no relatório. |
| `kind` | `all` (padrão), `owned`, `editorial`, `pr_wire`, `institution`, `reviews`, `commerce`, `social`, `other`. |
| `q` | Filtra domínios pelo nome ou páginas pela URL. Até 200 caracteres. |
| `offset` | 0–10.000. Cada lista devolve 20 linhas. |

Aqui uma citação é uma página que aparece em uma resposta, então a mesma página duas vezes na
mesma resposta conta uma vez. `/sources` conta respostas distintas, por isso os números podem
diferir.

| Campo | Significado |
| - | - |
| `totals` | `answers`, `citedAnswers`, `citations` e `ownedCitations` da janela. |
| `days` | Uma entrada por dia UTC medido com `answers`, `citations` e `ownedCitations`. Um dia com respostas mas sem citações aparece com `citations: 0`; um dia sem respostas não aparece. |
| `domains` / `pages` | Os 20 primeiros no `offset` atual, cada um com `kind`, `owned`, `citations`, `answers`, `prompts` e uma série `daily` de `{day, citations}`. `daily` só lista dias com citações. |
| `types` | Citações e domínios distintos por `kind`, sobre todas as fontes. |
| `pagination` | `offset`, `limit`, `totalDomains`, `totalPages`. |

A participação de uma fonte é o seu `citations` dividido por `totals.citations`. `kind`, `q`
e `offset` só restringem as listas; `totals`, `days` e `types` sempre cobrem todas as fontes
da janela.

```bash theme={null}
curl "$BASE/v1/monitors/$MONITOR_ID/citations?days=30&kind=owned" \
  -H "Authorization: Bearer $QUERYING_API_KEY"
```

## Exporte as linhas pontuadas

`GET /v1/monitors/{id}/results` retorna as próprias linhas, para carga em um data warehouse, uma apresentação semanal
ou uma planilha.

| Parâmetro | Regra |
| - | - |
| `since` · `until` | Semiaberto, com padrão nos últimos 30 dias até agora. `since` também aceita um `YYYY-MM-DD` sozinho (lido como `00:00:00Z`) por compatibilidade com a exportação original; o endpoint de relatório não aceita. |
| `engine` · `prompt` | Os mesmos filtros do relatório. |
| `mentioned` · `cited` | `true`/ `false`. `mentioned=false` é a visão de lacuna competitiva. |
| `competitor` | Um nome exato de concorrente configurado; mantém as respostas cuja lista de concorrentes salva o contém. |
| `includeEvidence` | Adiciona `answerText`, `sources` e `scoringContext` a cada linha e reduz o limite de tamanho de página. |
| `limit` | 1–10.000, padrão 10.000. Com `includeEvidence`, o padrão e o máximo são 100. |
| `format` | `json` (padrão) ou `csv`. |
| `cursor` | O `nextCursor` da resposta anterior. |

A paginação é um keyset sobre `(ranAt, id)` com precisão de microssegundos, então linhas com o mesmo timestamp não podem
ser puladas nem repetidas. Para tornar a extração repetível: **envie `since` e `until` explícitos, mantenha-os fixos e
siga `nextCursor` até ele ser `null`.** Mudar a janela entre páginas pode pular ou repetir linhas. Trate o cursor como
opaco: ele é devolvido e reenviado, nunca montado por você.

Com `format=csv`, a resposta é `text/csv` (UTF-8 com BOM, para o Excel abrir corretamente) e o estado da paginação vai
para os cabeçalhos, porque um corpo CSV não tem outro lugar para ele:

| Cabeçalho | Significado |
| - | - |
| `x-next-cursor` | O cursor da próxima página; vazio na última página. |
| `x-result-truncated` | `true` quando mais linhas corresponderam do que esta página retornou. |
| `x-result-since` · `x-result-until` | A janela resolvida, para que uma exportação retomada possa fixá-la. |

As colunas são `ran_at, monitor, engine, prompt, mentioned, cited, position, competitors, task_id`, mais
`answer_text, sources, scoring_context` quando `includeEvidence=true` (`sources` e `scoring_context` como texto JSON nas
células). Células que poderiam ser lidas como fórmula de planilha são neutralizadas antes da gravação, então texto de
terceiros não vira fórmula na sua planilha.

## Leia a resposta por trás de um número

`GET /v1/monitors/{id}/answers/{taskId}` retorna a evidência guardada de uma linha:

* `answerText`: a resposta como o mecanismo deu, em markdown quando disponível, **no máximo 8.000 caracteres**, cortada
  com reticências quando era mais longa.
* `sources`: as citações na ordem do mecanismo, cada uma com seu rótulo e sua posição (a partir de 1) naquela lista.
* `aliases` e `competitors`: com o que esta linha foi comparada, para que a menção possa ser conferida em vez de aceita na confiança.
* `scoringContext`: a definição exata usada, com um hash `version`, o horário da pontuação, `answerPresent` e
  `evidenceTruncated` quando o texto acima foi cortado.

Linhas pontuadas antes de o contexto de pontuação ser guardado retornam `scoringKnown: false` com os aliases atuais do
monitor e um `evidenceTruncated` `null`. `answerText` é `null` quando o mecanismo não retornou texto de resposta.

## Erros nesta superfície

O envelope é o mesmo de todo o resto (veja [Erros](/pt/concepts/errors)); os códigos específicos do monitoramento são:

| Código | Status | Quando |
| - | - | - |
| `VALIDATION_ERROR` | 400 | Janela inválida (`days` misturado com `since`/`until`, intervalo acima de 90 dias, instante sem fuso horário), mecanismo desconhecido, prompt longo demais, `limit` fora do intervalo ou relatório grande demais para agregar: restrinja a janela, o mecanismo ou o prompt. |
| `MISSING_API_KEY` / `UNAUTHORIZED` | 401 | Sem chave, ou uma chave que não pertence a esta conta. |
| `KEY_SCOPE_DENIED` | 403 | Os mecanismos permitidos da chave não cobrem os mecanismos do monitor. |
| `NOT_FOUND` | 404 | Não existe esse monitor para esta chave (o monitor de outra pessoa aparece do mesmo jeito), ou não há linha pontuada com esse id de tarefa. |
| `MONITOR_LIMIT` | 409 | A conta já tem o número máximo de monitores. |
| `RATE_LIMITED` | 429 | Sugestões de prompts (uma a cada 20 segundos, 30 por hora) ou e-mails de alerta de teste (três por monitor a cada cinco minutos). |
| `SUGGEST_FAILED` | 400 / 502 / 503 | As sugestões de prompts foram recusadas para esta marca, o serviço de sugestões falhou ou não está configurado nesta implantação. |

## Um agente no circuito

Uma sequência prática para um agente ou script, usando só os endpoints desta página. É ilustrativa: troque pela sua
chave, pelo id do seu monitor e pela sua janela.

1. `GET /v1/monitors/capabilities`: leia os mecanismos, preços e limites antes de gastar qualquer coisa.
2. `GET /v1/monitors`: reutilize um monitor existente para o tema e o mercado, ou use `POST /v1/monitors` para criar
   um (opcionalmente chamando antes `POST /v1/monitors/suggest` e editando os candidatos).
3. `POST /v1/monitors/{id}/run`: se precisar de respostas antes da próxima janela agendada.
4. `GET /v1/monitors/{id}/analytics?days=30&engine=CHATGPT`: leia primeiro `quality` (`comparable`, `lowSample`,
   `missingCells`, `partialDays`) e depois os números. Faça polling até `health.pending` se estabilizar e
   `quality.sampleSize` parar de crescer.
5. `GET /v1/monitors/{id}/sources?days=30&groupBy=page`: pagine com `nextCursor` para achar as páginas que ganham os prompts.
6. `GET /v1/monitors/{id}/answers/{taskId}`: abra a resposta por trás da primeira entrada de `opportunities` antes de decidir qualquer coisa.
7. `GET /v1/monitors/{id}/results?since=...&until=...&includeEvidence=true&format=csv`: exporte a mesma janela,
   seguindo `x-next-cursor` até ele ficar vazio.

As mesmas operações ficam disponíveis para agentes como ferramentas MCP (`get_monitor_capabilities`, `list_monitors`,
`get_monitor`, `create_monitor`, `update_monitor`, `delete_monitor`, `run_monitor`, `get_monitor_analytics`,
`get_monitor_sources`, `get_monitor_results`, `get_monitor_answer`, `suggest_monitor_prompts`, `get_monitor_alerts`,
`test_monitor_alert`). As escritas são anotadas como mutações, e `create_monitor` e `run_monitor` avisam que consomem
créditos antes de serem chamadas.

## Limites

| Limite | Valor |
| - | - |
| Monitores por conta | 20 |
| Tarefas por execução | 200 (`prompts × engines`) |
| Prompts por monitor | 100 |
| Tamanho do prompt | 2.000 caracteres |
| Aliases de marca | 20 |
| Domínios cadastrados | 20 |
| Concorrentes | Monitor de marca: 10 seus, mais até 15 encontrados. Monitor de categoria: 25 seus, mais até 25 encontrados |
| Nome da categoria | 80 caracteres |
| Subáreas por monitor de categoria | 30, de no máximo 60 caracteres cada |
| Intervalo | 1–168 horas |
| Janela do relatório | 90 dias |
| Página de resultados | 10.000 por padrão, 10.000 no máximo; 100 com evidência |
| Página de fontes ou evidências | 100 |

Veja os [preços](https://querying.ai/pt/pricing) e a [referência de mecanismos](/pt/engines/overview) antes de aumentar o volume.