GET /v1/monitors/{id}/analytics (referência) retorna cada
número do relatório de um monitor a partir de um único conjunto de respostas: uma janela, um conjunto de filtros e a mesma janela
imediatamente anterior para comparação. Monte cada painel do seu próprio relatório com este endpoint e leia quality
antes dos números. Ler um relatório não custa nada.
Parâmetros de consulta
A janela é semiaberta e em UTC:
since entra, until não. A janela anterior tem exatamente
a mesma duração, termina em since e usa os mesmos filtros, então toda comparação é equivalente. Envie
cada parâmetro uma única vez.
Exemplo
Por exemplo, um monitor de marca que pergunta dois prompts ao ChatGPT uma vez por dia comsamples: 5 (dez respostas por
dia), filtrado para o ChatGPT ao longo de dois dias, retorna:
Resposta completa
Resposta completa
quality.lowSample é true, então trate
a variação como um sinal a verificar, não como tendência.
Seções da resposta
Objetos de taxa
stats, previous, cada entrada de engineRates e series, cada prompt e cada célula trazem os mesmos
campos:
Células
Uma célula é um prompt em um mecanismo. Além do objeto de taxa e deprevious, ela traz:
Cada id é
null quando nenhuma resposta se qualifica. Abra um com
GET /v1/monitors/{id}/answers/{taskId}.
Marcas e share of voice
Cada entrada debrands tem name, mentions, sampleSize, mentionRate, shareOfVoice,
previousMentionRate, previousShareOfVoice e configured (false para uma marca citada na janela
que não está mais no monitor).
O que os números significam
GET /v1/monitors/capabilities retorna estas definições como metrics, para que um cliente possa exibi-las ao lado
dos números.
mentionRateé100 × mentioned / respostas pontuadas, para a janela, cada mecanismo, cada dia e cada célula. É ponderado por respostas, não uma média entre mecanismos, então um mecanismo movimentado não é sufocado por um quieto.citationRatetem o mesmo formato para as respostas que citaram um dos seus domínios. Sem domínios, é sempre 0, porque o rastreamento de citações fica desligado.- A taxa de uma marca divide pelo próprio
sampleSize. Para a sua marca, são todas as respostas pontuadas. Para um concorrente, só as respostas pontuadas enquanto ele estava no monitor, então um concorrente adicionado hoje é medido a partir de hoje. OmentionRatede um concorrente énullquando algumas respostas da janela foram pontuadas antes de o contexto de pontuação ser armazenado, porque não se sabe com o que elas foram comparadas. shareOfVoiceé100 × menções daquela marca / todas as menções de marcas acompanhadasna janela, então as participações de uma janela somam 100 (quality.trackedBrandMentionsé o denominador). Ele compara marcas dentro das respostas que você coletou para estes prompts. Não é participação de mercado nem ranking de visibilidade.competitorOnlyeopportunitiescontam as respostas que citaram um concorrente enquanto a sua marca estava ausente: a lacuna sobre a qual você pode agir.nullnão é 0. Uma taxa énullquando não havia respostas para dividir. 0 significa que houve respostas e nenhuma correspondeu.- Uma resposta sem texto conta como não mencionada. Uma tarefa concluída que não retornou resposta fica no
denominador;
quality.noAnswerObservationsas conta. Uma tarefa com falha é excluída de todas as taxas e aparece só emhealth. Um mecanismo quebrado encolhe a amostra em vez de aparecer como ausência. positionem uma resposta pontuada é o offset de caractere da primeira ocorrência da sua marca: um indicador de destaque, não um ranking. Énullquando a marca não aparece.
Quando as variações são retidas
changes, o mentionRateChangePp de cada célula e o previousMentionRate e o
previousShareOfVoice de cada marca ficam null, e quality.comparable fica false, quando as duas janelas não podem ser
comparadas. quality.comparisonReason diz por quê:
Cada resposta mantém a definição com que foi pontuada, e
quality.scoringVersions lista as definições
distintas nas duas janelas (legacy para respostas sem definição). Mudar seus aliases ou concorrentes
nunca reescreve respostas passadas. A única exceção é a leitura semanal de concorrentes: quando os concorrentes que ela
encontra mudam, as respostas armazenadas do monitor são pontuadas de novo com a nova lista.
Qualidade
Saúde
health tem completed, failed, pending e topError (o código de erro mais comum entre as tarefas com
falha) para as tarefas do monitor em andamento ou concluídas nas últimas 24 horas. healthScope é
sempre recent_visible_tasks. É um diagnóstico das execuções, independente da janela, e nunca faz parte do
denominador de uma taxa.
Polling durante uma execução
Toda chamada retorna o relatório completo da janela e dos filtros. Enquanto uma execução está em andamento,health.pending conta as tarefas dela que ainda estão rodando. Leia o relatório de novo quando ele chegar a 0.
Relatórios de categoria
Um monitor de categoria retorna um corpo diferente pelo mesmo endpoint, com os mesmoswindow, filters, quality, pauses e health:
statseprevioustrazemruns,named(respostas que citaram pelo menos uma marca acompanhada) enamedRate.changes.namedRatePpé a variação em pontos.categorytraz o ranking:
Por exemplo, uma entrada de
category.brands:
rankordena as marcas pelo número de respostas que as citam. Uma marca que nenhuma resposta citou temrank: null.mentionRatedivide pelo própriosampleSizeda marca: as respostas pontuadas enquanto ela estava na lista.shareOfVoiceé100 × menções daquela marca / todas as menções de marcasna janela, então as participações somam 100.
Erros e limites
- A janela tem no máximo 90 dias.
- Parâmetros inválidos retornam
400 VALIDATION_ERRORcom uma mensagem que indica o problema:dayscomsinceouuntil, só um entresinceeuntil, um timestamp sem fuso horário, um intervalo acima de 90 dias, umuntilno futuro, um mecanismo que não pode ser monitorado, um prompt acima de 2.000 caracteres ou um parâmetro repetido. - Um relatório grande demais para agregar retorna
400 VALIDATION_ERRORcom “This report is too large”. Restrinja a janela, o mecanismo ou o prompt.
Próximos passos
Fontes e respostas
As páginas citadas e as respostas por trás de cada número.
Eventos e alertas
Seja avisado quando as respostas mudarem.