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

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

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

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:

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, enviados em nome da sua conta.

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

Crie um monitor

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.

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); 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.

GET /v1/monitors/capabilities: leia os mecanismos, preços e limites antes de gastar qualquer coisa.
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).
POST /v1/monitors/{id}/run: se precisar de respostas antes da próxima janela agendada.
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.
GET /v1/monitors/{id}/sources?days=30&groupBy=page: pagine com nextCursor para achar as páginas que ganham os prompts.
GET /v1/monitors/{id}/answers/{taskId}: abra a resposta por trás da primeira entrada de opportunities antes de decidir qualquer coisa.
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 e a referência de mecanismos antes de aumentar o volume.

Primeiros passos

Conceitos principais

Mecanismos

Source Influence

Prompt Research

Monitoramento GEO

Migração

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

O que é um monitor

Os concorrentes são encontrados para você

Separe os monitores com intenção

Monitores de categoria: ordene as marcas de um mercado

O que o relatório ordena

Pesquise os prompts pela demanda de busca

Custo e agenda

Endpoints

Crie um monitor

Execute e depois leia o relatório

O que os números significam

De onde vêm as respostas

Citações ao longo do tempo

Exporte as linhas pontuadas

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

Erros nesta superfície

Um agente no circuito

Limites

​O que é um monitor

​Os concorrentes são encontrados para você

​Separe os monitores com intenção

​Monitores de categoria: ordene as marcas de um mercado

​O que o relatório ordena

​Pesquise os prompts pela demanda de busca

​Custo e agenda

​Endpoints

​Crie um monitor

​Execute e depois leia o relatório

​O que os números significam

​De onde vêm as respostas

​Citações ao longo do tempo

​Exporte as linhas pontuadas

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

​Erros nesta superfície

​Um agente no circuito

​Limites

O que é um monitor

Os concorrentes são encontrados para você

Separe os monitores com intenção

Monitores de categoria: ordene as marcas de um mercado

O que o relatório ordena

Pesquise os prompts pela demanda de busca

Custo e agenda

Endpoints

Crie um monitor

Execute e depois leia o relatório

O que os números significam

De onde vêm as respostas

Citações ao longo do tempo

Exporte as linhas pontuadas

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

Erros nesta superfície

Um agente no circuito

Limites