Saltar para o conteúdo principal
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 com samples: 5 (dez respostas por dia), filtrado para o ChatGPT ao longo de dois dias, retorna:
Como ler: a marca foi citada em 9 de 20 respostas do ChatGPT (45%), 15 pontos a menos que nos dois dias anteriores. A Northwind Audio foi citada em mais respostas, e “are cheap earbuds worth it” é o prompt mais fraco, com 4 respostas que citaram um concorrente e não a marca. 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 de previous, 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 de brands 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.
  • citationRate tem 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. O mentionRate de um concorrente é null quando 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 acompanhadas na 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.
  • competitorOnly e opportunities contam as respostas que citaram um concorrente enquanto a sua marca estava ausente: a lacuna sobre a qual você pode agir.
  • null não é 0. Uma taxa é null quando 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.noAnswerObservations as conta. Uma tarefa com falha é excluída de todas as taxas e aparece só em health. Um mecanismo quebrado encolhe a amostra em vez de aparecer como ausência.
  • position em uma resposta pontuada é o offset de caractere da primeira ocorrência da sua marca: um indicador de destaque, não um ranking. É null quando 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 mesmos window, filters, quality, pauses e health:
  • stats e previous trazem runs, named (respostas que citaram pelo menos uma marca acompanhada) e namedRate. changes.namedRatePp é a variação em pontos.
  • category traz o ranking:
Por exemplo, uma entrada de category.brands:
  • rank ordena as marcas pelo número de respostas que as citam. Uma marca que nenhuma resposta citou tem rank: null.
  • mentionRate divide pelo próprio sampleSize da marca: as respostas pontuadas enquanto ela estava na lista.
  • shareOfVoice é 100 × menções daquela marca / todas as menções de marcas na 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_ERROR com uma mensagem que indica o problema: days com since ou until, só um entre since e until, um timestamp sem fuso horário, um intervalo acima de 90 dias, um until no 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_ERROR com “This report is too large”. Restrinja a janela, o mecanismo ou o prompt.
Veja Monitores para os códigos que todos os endpoints de monitor compartilham.

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.