Monitores de marca e de categoria
Um monitor tem ummode, 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, ounullquando a marca não aparece. - Citada: a resposta cita uma página de um dos seus
domainsou de um subdomínio dele. - Concorrentes encontrados: quais dos concorrentes do monitor aparecem na mesma resposta.
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
quality, depois stats, brands e opportunities. Cada campo é explicado em
Relatórios e métricas.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 trazemsource: "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.
competitorsReadAtmostra quando foi a última leitura. - Na atualização,
competitorssubstitui a sua própria lista e mantém as encontradas. Entradas comsource: "auto"na requisição são ignoradas, então você pode reenviar o que oGETretornou.
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 dointervalHoursdo monitor, até 168. O mecanismo participa a cada k execuções, contando a partir da primeira, da qual todos os mecanismos participam.
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:locationpergunta cada prompt a partir de um ponto, em graus decimais.gridpergunta cada prompt a partir de cada ponto de uma grade quadrada em torno decenter.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.
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 emdisplay.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á emanswer.analysisdeGET /v1/monitors/{id}/answers/{taskId}.
location ou grid soma 1 crédito a cada tarefa.
Ler relatórios, fontes, respostas e resultados não custa nada.
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_ERRORcom 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 mudarintervalHours, 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.
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.
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 compromptTopics:
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: falsepausa o monitor;enabled: trueo retoma, com a próxima execução um intervalo a partir de agora. As pausas aparecem nos relatórios comopauses.- Mudar
alertBelowPctrearma 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 emhttps://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:
GET /v1/monitors/capabilities: mecanismos, preços e limites antes de gastar qualquer coisa.GET /v1/monitors: reutilize um monitor para o tema e o mercado, ou crie um, opcionalmente partindo dePOST /v1/monitors/suggest.POST /v1/monitors/{id}/runsó se precisar de respostas antes da próxima execução agendada.GET /v1/monitors/{id}/analytics?days=30: leiaqualityantes dos números e espere atéhealth.pendingchegar a0.GET /v1/monitors/{id}/sources?days=30&groupBy=page: siganextCursoraté o fim.GET /v1/monitors/{id}/answers/{taskId}: abra a resposta por trás da primeira entrada deopportunitiesantes de agir com base nela.GET /v1/monitors/{id}/results?since=...&until=...&format=csv: exporte a mesma janela, seguindox-next-cursoraté 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.