Saltar para o conteúdo principal
Você cria um monitor uma vez. Cada execução é um conjunto de tarefas assíncronas comuns, cobradas ao preço de cada mecanismo. Esta página cobre como criar, executar e gerenciar monitores. A leitura dos números está em Relatórios e métricas, as respostas por trás deles em Fontes e respostas, e webhooks e alertas por e-mail em Eventos e alertas. Para ver os mesmos dados no painel, veja a página do produto.

Monitores de marca e de categoria

Um monitor tem um mode, definido ao criá-lo e fixo durante toda a vida dele, porque decide o que cada resposta armazenada significa. Cada resposta é pontuada uma vez, quando chega:
  • Mencionada: um dos seus aliases aparece no texto da resposta. position é o offset de caractere da primeira ocorrência, ou null quando a marca não aparece.
  • Citada: a resposta cita uma página de um dos seus domains ou de um subdomínio dele.
  • Concorrentes encontrados: quais dos concorrentes do monitor aparecem na mesma resposta.
Essas pontuações não trazem sentimento nem estimativa de participação de mercado. A posição de um monitor de categoria é um lugar entre as marcas que as respostas citam, nada mais. Para sentimento e recomendações por resposta, ative analysis.

Início rápido

1

Crie o monitor

A primeira execução começa assim que o monitor é criado.
A resposta é 201 com o monitor armazenado. Guarde data.monitor.id.
2

Aguarde as respostas

As tarefas entram conforme a concorrência do seu plano permite, então uma execução chega ao longo de segundos a minutos. O health.pending do relatório conta as tarefas ainda em andamento. Leia o relatório quando ele chegar a 0.
3

Leia o relatório

Leia primeiro quality, depois stats, brands e opportunities. Cada campo é explicado em Relatórios e métricas.
Para obter respostas antes da próxima execução agendada, chame POST /v1/monitors/{id}/run.

Crie um monitor

POST /v1/monitors (referência) valida a definição, confere com os limites da sua conta, armazena o monitor e inicia a primeira execução. A chamada retorna 201 antes de essa execução terminar. Se a primeira execução não puder começar (por exemplo, saldo insuficiente), o monitor é criado mesmo assim e o agendador tenta a execução de novo a cada minuto. Por exemplo, a requisição do início rápido retorna:

Campos da requisição

Todo campo de lista aceita um array JSON ou uma única string separada por quebras de linha. As entradas são aparadas, entradas vazias são descartadas e duplicatas são removidas.

Mecanismos

Um monitor pode agendar os mecanismos de resposta baseados em prompt: CHATGPT, GEMINI, PERPLEXITY, GOOGLE (Google AI Overviews), AIMODE (Google AI Mode), NAVER_AI_BRIEF, NAVER_AI_TAB e NAVER, um nome obsoleto mantido para monitores existentes. Os aliases GOOGLE_AIO, GOOGLE_AIMODE e NAVER_AI_MODE são aceitos e salvos como GOOGLE, AIMODE e NAVER_AI_TAB. Os nomes dos mecanismos diferenciam maiúsculas de minúsculas. Tipos de tarefa de busca, dados da web e análise, como GOOGLE_SERP ou CITATION_ANALYSIS, não podem ser agendados. Preços e detalhes por mecanismo estão no catálogo de mecanismos. Uma chave de API restrita a alguns mecanismos só pode criar, atualizar ou executar monitores que usam esses mecanismos; qualquer outro caso retorna 403 KEY_SCOPE_DENIED.

Concorrentes

Você não precisa listar concorrentes. Depois da primeira execução, uma leitura semanal das respostas recentes do monitor acrescenta as marcas que vendem o mesmo que você e aparecem em pelo menos duas respostas: até 15 em um monitor de marca, 25 em um monitor de categoria.
  • Concorrentes encontrados trazem source: "auto"; os que você lista trazem source: "user". A leitura nunca altera nem remove os seus. Uma marca encontrada que as duas leituras seguintes não encontram é removida.
  • Quando a lista encontrada muda, as respostas armazenadas do monitor são pontuadas de novo com ela, para que toda marca de um relatório seja medida sobre as mesmas respostas. competitorsReadAt mostra quando foi a última leitura.
  • Na atualização, competitors substitui a sua própria lista e mantém as encontradas. Entradas com source: "auto" na requisição são ignoradas, então você pode reenviar o que o GET retornou.

Como os nomes são comparados

  • A comparação ignora maiúsculas/minúsculas e largura de caractere (NFKC).
  • Nomes em alfabeto latino batem só como palavras inteiras: “replicates” não é menção a uma marca chamada Replicate. Uma letra coreana, japonesa, chinesa ou tailandesa junto ao nome conta como limite de palavra, então “agoda를” e “ahamoが” mencionam agoda e ahamo. Nomes em coreano, japonês, chinês e tailandês batem em qualquer ponto do texto.
  • Um nome de um caractere nunca bate. Dê a essa marca um alias mais longo.
  • Quando dois nomes se sobrepõem, conta o que começa primeiro e, depois, o mais longo. “Acme” dentro de um concorrente chamado “Acme Pro” é o concorrente.
  • Destinos de links, URLs soltas e chips de citação são removidos antes da comparação; o texto visível de um link é mantido. Uma citação conta para cited, não como menção.

Escreva prompts que medem algo

  • Um monitor por tema e mercado. “melhor CRM” e “como precificar um CRM” são intenções diferentes; fazer a média das duas esconde ambas.
  • Escreva os prompts como um comprador e nunca inclua sua própria marca. Um prompt que cita a marca é sempre uma menção, então mostra 100% e não mede nada. Nomes de concorrentes nos prompts podem entrar.

Amostras e cadência por mecanismo

As respostas de IA mudam de uma sessão para outra, então a proporção entre várias respostas é mais estável do que uma só. engineSettings define, por mecanismo, quantas respostas coletar por prompt e com que frequência o mecanismo roda:
  • samples: de 1 a 10 respostas por prompt e ponto em cada execução (padrão 1). Cada uma é uma tarefa própria, em uma sessão própria, pontuada e cobrada como qualquer outra.
  • intervalHours: um múltiplo do intervalHours do monitor, até 168. O mecanismo participa a cada k execuções, contando a partir da primeira, da qual todos os mecanismos participam.
Uma entrada só pode nomear um dos mecanismos do monitor e aceita apenas essas duas chaves. Na atualização, engineSettings substitui o valor armazenado; uma atualização que remove um mecanismo remove a entrada dele, e uma que muda o intervalHours do monitor verifica os intervalos dos mecanismos com o novo valor.

Localização e grades

Por padrão, toda tarefa pergunta pelo país como um todo. Para medir respostas locais:
  • location pergunta cada prompt a partir de um ponto, em graus decimais.
  • grid pergunta cada prompt a partir de cada ponto de uma grade quadrada em torno de center. size é o número de pontos por lado: 3, 5, 7 ou 9 (de 9 a 81 pontos). radiusMeters, de 100 a 50.000, é a distância do centro ao meio de uma borda.
Só CHATGPT, GEMINI, GOOGLE e AIMODE respondem para uma localização. Um monitor com localização ou grade e qualquer outro mecanismo é recusado com 400 VALIDATION_ERROR. Na atualização, definir um entre location e grid limpa o outro, e null o limpa. Leia as respostas por ponto com GET /v1/monitors/{id}/grid.

Páginas de resposta

Uma resposta cuja tarefa guardou uma página leva o endereço dela em display.html, e o painel a entrega como arquivo com as fontes embutidas. A página é a tela real do motor, não uma nova renderização do markdown. Execuções de um monitor não pedem página, então suas respostas não levam uma. O endereço é lido da tarefa sempre que uma guardou, então uma página guardada continua abrível a partir da resposta.

Custo e agenda

Uma execução cria, para cada mecanismo que participa dela, uma tarefa por prompt, por ponto e por amostra:
points é 1 sem grade. Por exemplo, 12 prompts no CHATGPT (1 crédito) e no GOOGLE (1,25 crédito) são 24 tarefas e 27 créditos por execução, cerca de 810 créditos por mês com intervalo diário. Com "CHATGPT": { "samples": 5 }, o mesmo monitor são 72 tarefas e 75 créditos por execução. Leia os preços atuais em GET /v1/monitors/capabilities em vez de fixá-los no código; como os créditos são reservados e cobrados está em Créditos e limites. Duas cobranças se somam às tarefas:
  • Leitura de concorrentes: 80 créditos a cada 30 dias por monitor, divididos entre as execuções conforme a cadência (cerca de 2,67 créditos por execução em um monitor diário, 18,67 em um semanal). A cobrança acontece quando todas as tarefas de uma execução foram enviadas, então uma execução que seu saldo interrompeu não paga nada por ela.
  • Análise da resposta: com analysis: true, 1 crédito por tarefa, cobrado só pelas respostas analisadas. As pontuações (mentioned, cited, position) não mudam; o resultado de cada resposta está em answer.analysis de GET /v1/monitors/{id}/answers/{taskId}.
Um monitor com location ou grid soma 1 crédito a cada tarefa. Ler relatórios, fontes, respostas e resultados não custa nada.
A agenda se repete até você pausar ou excluir o monitor. O valor mensal acima é o compromisso que você assume ao criá-lo.
Como a agenda se comporta:
  • Uma execução não é uma rajada. As tarefas são enviadas conforme a concorrência do seu plano e as filas dos mecanismos permitem. A cada minuto o agendador continua de onde parou, uma tarefa por mecanismo em revezamento, e monitores de contas diferentes se revezam. Uma conta principal e suas subcontas compartilham o mesmo revezamento.
  • Uma execução precisa caber no seu intervalo. Se as tarefas de um mecanismo não puderem entrar antes de esse mecanismo rodar de novo, a criação e a atualização retornam 400 VALIDATION_ERROR com o menor intervalo que cabe. Uma execução ainda enviando tarefas quando um intervalo inteiro já passou é encerrada, e as tarefas restantes não são enviadas.
  • Execuções perdidas não são repetidas. nextRunAt é quando a próxima execução vence. Retomar um monitor pausado, ou mudar intervalHours, agenda a próxima execução para um intervalo a partir desse momento.

Capabilities

GET /v1/monitors/capabilities (referência) retorna, para a sua conta: cada mecanismo agendável com creditsPerTask, analysisCreditsPerTask e placeCreditsPerTask, seus limits, os modes, as definições das métricas (metrics), as fórmulas da agenda e os tipos de evento de mudança. Não tem efeitos colaterais e não custa nada; chame antes de criar monitores por programa.

Escolha os prompts

Sugira prompts a partir de informações da marca

POST /v1/monitors/suggest (referência) retorna até 12 prompts candidatos escritos como um comprador em country perguntaria. Não salva nada e não consome créditos.
Por exemplo:
Sugestões que contêm o nome da marca ou um alias são removidas. Revise a lista antes de criar o monitor. Você pode pedir uma sugestão a cada 20 segundos e 30 por hora; acima disso, a resposta é 429 RATE_LIMITED. Quando o modelo recusa a marca, a chamada retorna 400 SUGGEST_FAILED; quando o serviço de sugestões falha, 502 SUGGEST_FAILED; e quando ele não está configurado, 503 SUGGEST_FAILED.

Pesquise prompts pela demanda de busca

POST /v1/monitors/research (referência) recebe o corpo da requisição de Prompt Research, custa os mesmos 14 créditos e retorna o mesmo resultado, como uma tarefa da sua conta.
A resposta traz a tarefa enfileirada em data.task, com data.credits e data.replayed. Leia o resultado com GET /v1/async/task/{id} usando data.task.id (veja Tarefas assíncronas). Depois crie o monitor com prompts[].prompt como prompts, na ordem em que vêm; em um monitor de categoria, quando a pesquisa tiver mais de um core, o core de cada prompt como sua entrada em promptTopics, e brands[].brand como competitors. Nada é salvo até você criar o monitor. Uma execução pode enfileirar no máximo o limite tasksPerRun da sua conta, contado em cada mecanismo como prompts × pontos de localização × samples, então defina limit para o monitor que você vai criar. Veja Da pesquisa a um monitor.

Monitores de categoria

Um monitor de categoria ordena as marcas que os mecanismos citam para um mercado. Agrupe os prompts por subárea com promptTopics:
Um monitor de categoria não tem marca própria: aliases, domains e alertBelowPct precisam ficar vazios, senão a requisição retorna 400 VALIDATION_ERROR, e ele não tem alerta. Seus stats.mentioned e stats.cited em GET /v1/monitors são sempre 0; a lista acrescenta leader, a marca mais citada nos últimos 30 dias. O relatório dele está descrito em Relatórios de categoria. Agenda, custo, fontes, respostas, resultados e eventos de mudança funcionam como em um monitor de marca, exceto que um monitor de categoria envia só eventos monitor.source.first_cited. Na atualização, uma edição em prompts descarta as entradas de promptTopics dos prompts removidos. As respostas que esses prompts coletaram continuam no ranking.

Gerencie monitores

O resumo de período antigo em GET /v1/monitors/{id} é mantido por compatibilidade. Para os números, use /analytics: o resumo antigo mistura uma matriz de todo o histórico com a última resposta por prompt e mecanismo aos números da janela, corta as fontes em 12 domínios e 20 páginas, e seu shareOfVoice conta cada marca em relação a todas as respostas, então as participações podem somar mais de 100. Um monitor que pertence a outra conta retorna 404 NOT_FOUND, não 403.

Atualize um monitor

PATCH recebe qualquer subconjunto dos campos de criação e valida o resultado como um todo, com os mesmos limites. Campos omitidos mantêm seus valores.
  • enabled: false pausa o monitor; enabled: true o retoma, com a próxima execução um intervalo a partir de agora. As pausas aparecem nos relatórios como pauses.
  • Mudar alertBelowPct rearma o alerta.
  • Mudar aliases, domínios ou concorrentes afeta as respostas pontuadas daí em diante. As respostas armazenadas mantêm as definições com que foram pontuadas, então os relatórios retêm as comparações que atravessam a mudança (veja Relatórios e métricas).

Execute um monitor agora

POST /v1/monitors/{id}/run faz a próxima execução vencer imediatamente; o agendador a inicia em cerca de um minuto, e a chamada retorna data.queued: true. A execução é cobrada como uma agendada. Chamar de novo enquanto essa execução ainda está vencida não cria uma segunda execução. Antes de enfileirar, a chamada confere se o seu saldo cobre a execução, incluindo a leitura de concorrentes e os créditos de análise. Se não cobrir, retorna 402 INSUFFICIENT_CREDITS com details.needed e details.available. Uma subconta acima do limite mensal de créditos recebe 429 SUB_ACCOUNT_CREDIT_LIMIT. Um monitor pausado retorna 404 NOT_FOUND: retome-o antes.

Compartilhe um relatório

Você pode publicar o relatório de um monitor em https://querying.ai/<slug>. Um relatório compartilhado mostra a análise, as fontes, as citações, os resultados e as respostas; nunca mostra configurações, alertas, os controles de execução nem a saúde das tarefas da sua conta. GET /v1/monitors/{id}/share (referência) retorna o estado atual, access, slug, locale e url, mais um suggestedSlug quando nenhum está definido. PUT /v1/monitors/{id}/share (referência) o altera:
Definir access como PRIVATE tira o relatório do ar e mantém o slug, então ativar o compartilhamento de novo reutiliza o mesmo endereço.

Use monitores a partir de um agente

O servidor MCP expõe os monitores como ferramentas: 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 e test_monitor_alert. Cada uma faz uma chamada à API com a sua chave. Uma sequência prática para um agente ou script:
  1. GET /v1/monitors/capabilities: mecanismos, preços e limites antes de gastar qualquer coisa.
  2. GET /v1/monitors: reutilize um monitor para o tema e o mercado, ou crie um, opcionalmente partindo de POST /v1/monitors/suggest.
  3. POST /v1/monitors/{id}/run só se precisar de respostas antes da próxima execução agendada.
  4. GET /v1/monitors/{id}/analytics?days=30: leia quality antes dos números e espere até health.pending chegar a 0.
  5. GET /v1/monitors/{id}/sources?days=30&groupBy=page: siga nextCursor até o fim.
  6. GET /v1/monitors/{id}/answers/{taskId}: abra a resposta por trás da primeira entrada de opportunities antes de agir com base nela.
  7. GET /v1/monitors/{id}/results?since=...&until=...&format=csv: exporte a mesma janela, seguindo x-next-cursor até ele ficar vazio.

Limites

Uma conta com contrato é uma com limite de concorrência negociado. Estes valem para todas as contas: Os limites de relatório, tamanho de página e retenção estão nas páginas que os usam: Relatórios e métricas, Fontes e respostas e Eventos e alertas.

Erros

O envelope de erro é o mesmo de todo o resto (veja Erros). Códigos específicos dos monitores:

Próximos passos

Relatórios e métricas

O contrato de /analytics e o que cada número significa.

Fontes e respostas

Páginas citadas, as respostas por trás de cada pontuação e exportações.

Eventos e alertas

Webhooks quando as respostas mudam e alertas por e-mail sobre a sua taxa de menção.

Prompt Research

Encontre pela demanda de busca os prompts que valem acompanhar.