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 consamples: 5 (diez
respuestas al día), filtrado a ChatGPT durante dos días, devuelve:
Respuesta completa
Respuesta completa
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 yprevious, 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 debrands 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.
mentionRatees100 × 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.citationRatetiene 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. ElmentionRatede un competidor esnullcuando algunas respuestas de la ventana se puntuaron antes de que se guardara el contexto de puntuación, porque se desconoce con qué se compararon. shareOfVoicees100 × menciones de esa marca / todas las menciones de marcas seguidasen la ventana, así que las cuotas de una ventana suman 100 (quality.trackedBrandMentionses el denominador). Compara marcas dentro de las respuestas que recogiste para estos prompts. No es cuota de mercado ni un ranking de visibilidad.competitorOnlyyopportunitiescuentan las respuestas que nombraron a un competidor mientras tu marca estaba ausente: la brecha sobre la que puedes actuar.nullno es 0. Una tasa esnullcuando 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.noAnswerObservationslas cuenta. Una tarea fallida se excluye de todas las tasas y solo aparece enhealth. Un motor averiado reduce la muestra en lugar de aparecer como ausencia. positionen una respuesta puntuada es el offset de carácter de la primera coincidencia de tu marca: un indicador aproximado de prominencia, no un ranking. Esnullcuando 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 mismoswindow, filters, quality, pauses y health:
statsypreviouscontienenruns,named(respuestas que nombraron al menos una marca seguida) ynamedRate.changes.namedRatePpes la variación en puntos.categorycontiene el ranking:
Por ejemplo, una entrada de
category.brands:
rankordena las marcas por el número de respuestas que las nombran. Una marca que ninguna respuesta nombró tienerank: null.mentionRatese divide por el propiosampleSizede la marca: las respuestas puntuadas mientras estaba en la lista.shareOfVoicees100 × menciones de esa marca / todas las menciones de marcasen 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_ERRORcon un mensaje que indica el problema:daysjunto consinceountil, solo uno desinceyuntil, una marca de tiempo sin zona horaria, un intervalo de más de 90 días, ununtilen 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_ERRORcon «This report is too large». Reduce la ventana, el motor o el prompt.
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.