Saltar al contenido principal
GET /v1/monitors/{id}/analytics (referencia) devuelve todas las cifras del informe de un monitor a partir de un mismo conjunto de respuestas: una ventana, un conjunto de filtros y la ventana anterior de la misma duración para comparar. Construye cada panel de tu propio informe con este endpoint y lee quality antes que las cifras. Leer un informe no cuesta nada.

Parámetros de consulta

La ventana es semiabierta y en UTC: since se incluye y until no. La ventana anterior tiene exactamente la misma duración, termina en since y usa los mismos filtros, así que cada comparación es equivalente. Envía cada parámetro una sola vez.

Ejemplo

Por ejemplo, un monitor de marca que pregunta a ChatGPT dos prompts una vez al día con samples: 5 (diez respuestas al día), filtrado a ChatGPT durante dos días, devuelve:
Cómo leerlo: la marca se nombró en 9 de 20 respuestas de ChatGPT (45 %), 15 puntos menos que en los dos días anteriores. Northwind Audio se nombró en más respuestas, y «are cheap earbuds worth it» es el prompt más débil, con 4 respuestas que nombraron a un competidor y no a la marca. quality.lowSample es true, así que trata la variación como una señal que revisar, no como una tendencia.

Secciones de la respuesta

Objetos de tasa

stats, previous, cada entrada de engineRates y series, cada prompt y cada celda llevan los mismos campos:

Celdas

Una celda es un prompt en un motor. Además del objeto de tasa y previous, lleva: Cada id es null cuando ninguna respuesta cumple la condición. Abre una con GET /v1/monitors/{id}/answers/{taskId}.

Marcas y cuota de voz

Cada entrada de brands tiene name, mentions, sampleSize, mentionRate, shareOfVoice, previousMentionRate, previousShareOfVoice y configured (false para una marca nombrada en la ventana que ya no está en el monitor).

Qué significan las cifras

GET /v1/monitors/capabilities devuelve estas definiciones como metrics, para que un cliente pueda mostrarlas junto a las cifras.
  • mentionRate es 100 × mentioned / respuestas puntuadas, para la ventana, cada motor, cada día y cada celda. Se pondera por respuestas, no se promedia entre motores, así que un motor con mucha actividad no queda en minoría frente a uno con poca.
  • citationRate tiene la misma forma para las respuestas que citaron uno de tus dominios. Sin dominios siempre es 0, porque el seguimiento de citas está desactivado.
  • La tasa de una marca se divide por su propio sampleSize. Para tu marca son todas las respuestas puntuadas. Para un competidor son solo las respuestas puntuadas mientras estaba en el monitor, así que un competidor añadido hoy se mide desde hoy. El mentionRate de un competidor es null cuando algunas respuestas de la ventana se puntuaron antes de que se guardara el contexto de puntuación, porque se desconoce con qué se compararon.
  • shareOfVoice es 100 × menciones de esa marca / todas las menciones de marcas seguidas en la ventana, así que las cuotas de una ventana suman 100 (quality.trackedBrandMentions es el denominador). Compara marcas dentro de las respuestas que recogiste para estos prompts. No es cuota de mercado ni un ranking de visibilidad.
  • competitorOnly y opportunities cuentan las respuestas que nombraron a un competidor mientras tu marca estaba ausente: la brecha sobre la que puedes actuar.
  • null no es 0. Una tasa es null cuando no había respuestas por las que dividir. 0 significa que había respuestas y ninguna coincidió.
  • Una respuesta sin texto cuenta como no mencionada. Una tarea completada que no devolvió respuesta sigue en el denominador; quality.noAnswerObservations las cuenta. Una tarea fallida se excluye de todas las tasas y solo aparece en health. Un motor averiado reduce la muestra en lugar de aparecer como ausencia.
  • position en una respuesta puntuada es el offset de carácter de la primera coincidencia de tu marca: un indicador aproximado de prominencia, no un ranking. Es null cuando la marca no aparece.

Cuándo se ocultan las variaciones

changes, el mentionRateChangePp de cada celda, y el previousMentionRate y previousShareOfVoice de cada marca son null, y quality.comparable es false, cuando las dos ventanas no se pueden comparar. quality.comparisonReason indica por qué: Cada respuesta conserva la definición con la que se puntuó, y quality.scoringVersions lista las definiciones distintas en ambas ventanas (legacy para respuestas sin ella). Cambiar tus alias o competidores nunca reescribe respuestas pasadas. La única excepción es la lectura semanal de competidores: cuando cambian los competidores que encuentra, las respuestas guardadas del monitor se vuelven a puntuar con la nueva lista.

Calidad

Salud

health tiene completed, failed, pending y topError (el código de error más frecuente entre las tareas fallidas) para las tareas del monitor en curso o terminadas en las últimas 24 horas. healthScope siempre es recent_visible_tasks. Es un diagnóstico de las ejecuciones, independiente de la ventana, y nunca forma parte del denominador de una tasa.

Consulta mientras una ejecución está en curso

Cada llamada devuelve el informe completo para la ventana y los filtros. Mientras una ejecución está en curso, health.pending cuenta sus tareas que aún se están ejecutando. Vuelve a leer el informe cuando llegue a 0.

Informes de categoría

Un monitor de categoría devuelve un cuerpo distinto desde el mismo endpoint, con los mismos window, filters, quality, pauses y health:
  • stats y previous contienen runs, named (respuestas que nombraron al menos una marca seguida) y namedRate. changes.namedRatePp es la variación en puntos.
  • category contiene el ranking:
Por ejemplo, una entrada de category.brands:
  • rank ordena las marcas por el número de respuestas que las nombran. Una marca que ninguna respuesta nombró tiene rank: null.
  • mentionRate se divide por el propio sampleSize de la marca: las respuestas puntuadas mientras estaba en la lista.
  • shareOfVoice es 100 × menciones de esa marca / todas las menciones de marcas en la ventana, así que las cuotas suman 100.

Errores y límites

  • La ventana es de 90 días como máximo.
  • Los parámetros no válidos devuelven 400 VALIDATION_ERROR con un mensaje que indica el problema: days junto con since o until, solo uno de since y until, una marca de tiempo sin zona horaria, un intervalo de más de 90 días, un until en el futuro, un motor que no se puede monitorizar, un prompt de más de 2000 caracteres o un parámetro repetido.
  • Un informe demasiado grande para agregarse devuelve 400 VALIDATION_ERROR con «This report is too large». Reduce la ventana, el motor o el prompt.
Consulta Monitores para los códigos que comparten todos los endpoints de monitores.

Próximos pasos

Fuentes y respuestas

Las páginas citadas y las respuestas detrás de cada cifra.

Eventos y alertas

Recibe un aviso cuando cambian las respuestas.