API de monitorización GEO: menciones y citas de marca

Los monitores repiten un conjunto guardado de prompts según un calendario y puntúan las respuestas de IA resultantes para tu marca y sus competidores. Esta página es el contrato de la API: cómo configurar un monitor, qué significa cada cifra, cómo leer las fuentes que hay detrás y cómo exportar las respuestas subyacentes. Para ver los mismos datos en el panel, empieza por la guía del producto. Todas las claves, ids, marcas y prompts de esta página son ejemplos. Nada de esto es una credencial ni un monitor real.

Qué es un monitor

Un monitor es un conjunto de prompts con nombre en un mercado: una lista de prompts, los motores a los que se envían, los alias que significan «tu marca», opcionalmente tus dominios y algunos competidores, un país y un intervalo. Cada ejecución programada envía prompts × motores tareas asíncronas normales, y cada respuesta terminada se puntúa una vez y se conserva. La puntuación es deliberadamente acotada, y los datos no pueden responder más de lo que almacenan:

Registra si un alias de marca aparece en el texto de la respuesta y en qué offset de carácter; si la respuesta citó uno de tus dominios registrados; y cuáles de tus competidores configurados aparecieron en la misma respuesta.
No produce una puntuación de sentimiento ni una estimación de cuota de mercado. Una posición es un lugar entre las marcas que mencionan las respuestas, como en el ranking de un monitor de categoría (más abajo).

Los competidores se encuentran solos

No hace falta que listes competidores. Cuando termina la primera ejecución de un monitor, leemos sus respuestas recientes con un modelo de lenguaje y nos quedamos con las marcas que venden lo mismo que tú y aparecen en al menos dos respuestas, hasta 15. La lectura se repite cada 30 días, así que los rivales nuevos entran y los que dejan de nombrarse salen.

Los competidores encontrados llevan source: "auto". Los que añades tú llevan source: "user", y la lectura nunca los cambia ni los quita.
Cuando cambia la lista encontrada, las respuestas guardadas del monitor se vuelven a contar con ella, para que todas las marcas de un informe se midan sobre las mismas respuestas. competitorsReadAt en el monitor indica cuándo fue la última lectura.
Los nombres en alfabeto latino coinciden como palabras completas, así que «replicates» no cuenta como mención de la marca Replicate.

Separa los monitores con intención

Monitores distintos representan temas o mercados distintos, y son informes distintos: cada uno tiene su propia ventana, su propia definición de puntuación y su propio calendario. Dos hábitos compensan:

Un monitor por tema y mercado, para que la cohorte del informe siga siendo comparable. Mezclar «mejor CRM» y «cómo poner precio a un CRM» en un conjunto promedia dos intenciones distintas en una sola cifra.
Redacta los prompts como lo haría un comprador y nunca incluyas tu propia marca. Un prompt que contiene la marca siempre es una mención, así que informa 100 % para siempre y no mide nada. Los nombres de competidores están bien y suelen ser los prompts más útiles que puedes escribir.

Monitores de categoría: ordena las marcas de un mercado

Un monitor de marca sigue una marca. Un monitor de categoría sigue un mercado: nombras la categoría, agrupas sus preguntas por subárea y el informe ordena las marcas que mencionan los motores al responder. Establece "mode": "CATEGORY" al crear el monitor. mode es BRAND por defecto y no cambia durante toda la vida del monitor, porque decide qué significa cada fila almacenada.

curl -X POST "$BASE/v1/monitors" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Sunscreen market",
    "mode": "CATEGORY",
    "category": "Sunscreen",
    "engines": ["CHATGPT", "GEMINI"],
    "prompts": ["best sunscreen for sensitive skin", "best sunscreen for kids"],
    "promptTopics": {
      "best sunscreen for sensitive skin": "Sensitive skin",
      "best sunscreen for kids": "Kids"
    },
    "competitors": [{ "name": "Supergoop" }, { "name": "La Roche-Posay", "aliases": ["LRP"] }],
    "country": "US",
    "intervalHours": 24
  }'

Campo	En un monitor de categoría
`category`	Obligatorio, de 1 a 80 caracteres: el mercado tal como lo nombra un comprador.
`promptTopics`	Asocia un prompt (su texto exacto) con su subárea. Hasta 30 subáreas de como máximo 60 caracteres. Un prompt sin entrada abarca toda la categoría.
`competitors`	Las marcas que se ordenan: hasta 25 que tú indicas. Cuando entra la primera ejecución, la lectura mensual añade hasta 25 más que mencionan las respuestas.
`aliases` · `domains` · `alertBelowPct`	Déjalos vacíos. Un monitor de categoría no tiene marca propia, dominio propio ni alerta, así que un valor devuelve `400 VALIDATION_ERROR`.

El calendario, el coste, la ventana, los filtros, quality, las fuentes, las citas, los resultados y las respuestas funcionan igual que en un monitor de marca. Un monitor de categoría no tiene alerta, así que POST /v1/monitors/{id}/alerts/test devuelve 400.

Qué ordena el informe

GET /v1/monitors/{id}/analytics devuelve la vista de categoría. stats y previous contienen runs, named (respuestas que mencionan al menos una marca seguida) y namedRate; changes.namedRatePp es el cambio en puntos, y el objeto category contiene el ranking:

Campo	Qué contiene
`category.brands`	Cada marca seguida que mencionaron las respuestas, primero las que más respuestas mencionan: `rank`, `mentions`, `sampleSize`, `mentionRate`, `shareOfVoice` y el cambio respecto al intervalo anterior.
`category.topics`	Una fila por subárea (`topic: null` es toda la categoría) con sus `runs`, `namedRate` y las tres marcas más mencionadas.
`category.engines`	Una fila por motor con las tres marcas que más menciona.
`category.series`	Por día UTC, las tasas de las cinco marcas líderes.
`category.prompts`	Una fila por prompt con sus marcas líderes y celdas por motor; cada celda lleva un `evidenceTaskId` para abrir la respuesta que hay detrás.

rank ordena las marcas por el número de respuestas que las mencionan: es un puesto entre las marcas que mencionan estas respuestas. Una marca que ninguna respuesta mencionó tiene rank: null.
El mentionRate de una marca se divide entre su propio sampleSize, las respuestas puntuadas mientras la marca estaba en la lista. Una marca que añades hoy se mide desde hoy.
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.
GET /v1/monitors añade leader (la marca más mencionada, con su tasa) a cada monitor de categoría. Sus recuentos mentioned y cited son siempre 0.
GET /v1/monitors/{id}/answers/{taskId} devuelve mode, un aliases vacío y las marcas seguidas como competitors.

Investiga los prompts a partir de la demanda de búsqueda

POST /v1/monitors/research acepta el cuerpo de la solicitud de Prompt Research, cuesta los mismos 12 créditos y devuelve el mismo resultado, enviado a nombre de tu cuenta. Lee la tarea en cola con GET /v1/async/task/{id}; el id está en data.task.id de la respuesta.

curl -X POST "$BASE/v1/monitors/research" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{ "seed": "sunscreen", "country": "US", "monitorSize": 10, "monitorEngines": ["CHATGPT", "GEMINI"] }'

Usa monitorSet.prompts como prompts, el topic de cada prompt como su subárea en promptTopics y brands[].brand como competitors. El botón Ejecutar investigación del panel hace lo mismo y rellena el formulario; no se guarda nada hasta que creas el monitor.

Coste y calendario

Una ejecución encola una tarea por prompt y por motor, al precio en créditos publicado de cada motor. El calendario se repite hasta que pausas o eliminas el monitor, así que al crearlo estás eligiendo un coste recurrente:

credits per run  = prompts × sum(credits for each engine)
credits / month  ≈ credits per run × (24 × 30) / intervalHours

Por ejemplo, 12 prompts en ChatGPT (2 créditos) y Gemini (1 crédito) son 24 tareas y 36 créditos por ejecución, unos 1.080 créditos al mes con un intervalo diario. Lee los precios actuales del endpoint de capabilities en lugar de fijarlos en el código. Conviene conocer dos propiedades del calendario antes de depender de él:

Una ejecución no es una ráfaga. Las tareas se admiten según lo permitan la concurrencia del plan y la cola, así que una ejecución que supera el límite de un plan gratuito llega a lo largo de varios minutos en lugar de descartarse. Consulta health.pending en un informe para ver una ejecución en curso.
La siguiente ventana es un momento, no una garantía. nextRunAt es cuándo vence la ejecución; un monitor pausado durante una semana se reanuda un intervalo después del momento en que se reactiva, sin lanzar las ejecuciones perdidas.

Encontrar tus competidores añade 100 créditos al mes por monitor, repartidos entre sus ejecuciones según el intervalo: unos 3 créditos por ejecución en un monitor diario y unos 23 en uno semanal. Se cobra cuando todas las tareas de una ejecución han entrado, así que una ejecución que tu saldo detuvo no paga nada por ello.

Endpoints

Método y ruta	Qué te da
`GET /v1/monitors/capabilities`	Motores con sus precios en créditos, límites, definiciones de métricas y la economía del calendario. Una lectura barata sin efectos secundarios.
`GET /v1/monitors`	Tus monitores con un resumen de 30 días de cada uno.
`POST /v1/monitors`	Crea e inicia uno.
`GET /v1/monitors/{id}`	Detalle de periodo heredado. Usa `/analytics` en su lugar: este mezcla una matriz de celdas de todo el historial sin filtrar con cifras de la ventana y recorta las citas a 12 dominios y 20 páginas.
`PATCH /v1/monitors/{id}`	Actualiza campos, o envía `enabled` para pausar y reanudar.
`DELETE /v1/monitors/{id}`	Elimina el monitor y su historial puntuado.
`POST /v1/monitors/{id}/run`	Adelanta la siguiente ejecución a ahora. Consume créditos como cualquier ejecución.
`GET /v1/monitors/{id}/analytics`	El contrato del informe. Una cohorte, un conjunto de filtros, todas las secciones.
`GET /v1/monitors/{id}/sources`	Dominios o páginas citados en la misma ventana, paginados.
`GET /v1/monitors/{id}/citations`	Serie diaria de citas de los dominios y páginas principales: los datos de los gráficos de citas del panel.
`GET /v1/monitors/{id}/results`	Las filas puntuadas en sí, en JSON o CSV, con filtros y cursor.
`GET /v1/monitors/{id}/answers/{taskId}`	La respuesta conservada detrás de una fila.
`GET /v1/monitors/{id}/prompt`	Detalle de un prompt: su serie, fuentes y filas recientes.
`GET /v1/monitors/{id}/alerts` · `POST .../alerts/test`	Umbral de alerta, estado de enclavamiento e historial de envíos; encola un correo de prueba.
`POST /v1/monitors/suggest`	Prompts candidatos a partir de datos de la marca. No guarda nada ni consume créditos de tareas.
`POST /v1/monitors/research`	Investiga prompts para un monitor: la solicitud, el precio y el resultado de Prompt Research, enviados a nombre de tu cuenta.

Todos usan la misma clave bearer que el resto de la API (consulta Autenticación). Un monitor de otra cuenta responde 404, no 403.

Crear un monitor

curl -X POST "$BASE/v1/monitors" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Earbud brand tracking",
    "engines": ["CHATGPT", "GEMINI"],
    "prompts": ["best wireless earbuds for commuting", "are cheap earbuds worth it"],
    "aliases": ["Acme Audio", "Acme"],
    "domains": ["example.com"],
    "competitors": [{ "name": "Sony", "aliases": ["Sony"] }],
    "country": "US",
    "intervalHours": 24
  }'

name, engines, prompts, aliases e intervalHours son obligatorios en un monitor de marca; un monitor de categoría recibe category en lugar de aliases. Cada lista acepta un array o una cadena separada por saltos de línea; las entradas se recortan, las líneas vacías se descartan y los duplicados se eliminan. country elige el mercado para el que responden los motores y no traduce los prompts. prompts × engines debe quedar en o por debajo del límite tasksPerRun de capabilities. Los motores son las superficies de prompt programables: CHATGPT, GEMINI, PERPLEXITY, GOOGLE, AIMODE, NAVER_AI_BRIEF, NAVER_AI_TAB y el alias obsoleto NAVER. GOOGLE_AIO y GOOGLE_AIMODE se aceptan y se guardan como GOOGLE y AIMODE. Las tareas de análisis como SOURCE_INFLUENCE no son superficies de prompt y no se pueden programar en un monitor. Una clave restringida a ciertos motores solo puede programar esos motores; cualquier otro es 403 KEY_SCOPE_DENIED. El límite de monitores por cuenta devuelve 409 MONITOR_LIMIT.

Ejecútalo y lee el informe

POST /v1/monitors/{id}/run hace que la siguiente ejecución venza de inmediato, y las tareas de respuesta aparecen en aproximadamente un minuto. Se cobra como una programada, y un reintento de la llamada mientras esa ventana sigue vencida no cobra dos veces. GET /v1/monitors/{id}/analytics es el contrato del que debe salir cada parte de tu informe. Su ventana es semiabierta y en UTC: since inclusivo, until exclusivo, y la eliges de una de estas dos formas:

Parámetro	Regla
`days`	Uno de `7`, `30` (por defecto) o `90`, terminando ahora. No se puede combinar con `since`/`until`.
`since` y `until`	Ambos obligatorios a la vez, instantes ISO completos con zona horaria (por ejemplo `2026-09-15T00:00:00Z`). El intervalo debe ser positivo, de 90 días como máximo y no estar en el futuro. Un `YYYY-MM-DD` suelto se rechaza aquí: no define una ventana portable.

Dos filtros opcionales se aplican a todas las secciones a la vez: engine (id canónico o alias público) y prompt (texto exacto, hasta 2.000 caracteres). Las filas se indexan por el texto del prompt, así que un prompt que luego quites del monitor sigue siendo consultable. Todas las secciones comparten esa cohorte, y el intervalo anterior tiene exactamente la misma duración y los mismos filtros, así que la comparación es homogénea:

Campo	Qué contiene
`window`	`since`, `until`, `previousSince`, `previousUntil`, `timezone` y los `bounds` literales de la ventana. `previousUntil` siempre es el `since` de esta ventana.
`filters`	Los filtros aplicados, resueltos: el id canónico del motor, el prompt exacto o `null`.
`stats` · `previous`	Recuentos y tasas de la ventana y del intervalo anterior.
`changes`	Variaciones en puntos porcentuales, o `null` si la comparación no es válida (ver abajo).
`engineRates`	Las mismas tasas por motor, para ver un motor débil sin leer un gráfico.
`series`	Por día UTC y motor, con `partial` marcando un día cortado por el borde de la ventana.
`brands`	Tu marca (`__you__`) y cada competidor seguido, de más a menos menciones, cada uno con su propio `sampleSize` y la tasa medida sobre él.
`voiceSeries`	Las mismas marcas por día UTC, para la línea de tendencia.
`prompts`	Totales por prompt, de menor a mayor tasa de mención, cada uno con sus celdas por motor.
`opportunities`	Celdas en las que se mencionó a un competidor y no a tu marca, de más a menos fallos. La lista con la que trabajar.
`quality`	De qué se compone la muestra, y todo lo que las cifras no pueden decir.
`health` · `healthScope`	Salud de ejecución de las tareas aún visibles de forma individual: un ámbito reciente aparte, nunca parte del denominador.

Qué significan las cifras

Lee esto antes de etiquetar un panel. Las definiciones son el contrato publicado, y GET /v1/monitors/capabilities las devuelve como metrics para que un cliente pueda mostrarlas junto a las cifras.

mentionRate de la ventana, de sus grupos por motor y de sus grupos por celda es 100 × respuestas con mención / respuestas puntuadas. Se pondera por respuestas, no es una media de las tasas por motor, así que un motor con mucho volumen no queda eclipsado por uno con poco. (La tasa propia de una marca tiene su propio denominador, explicado a continuación.)
citationRate tiene la misma forma para las respuestas que citaron uno de tus dominios registrados. Sin dominios registrados siempre es cero, porque el seguimiento de citas está desactivado.
La tasa de una marca se divide por su propio sampleSize, no por el total de la ventana. Para tu marca son todas las respuestas puntuadas; para un competidor, solo las respuestas puntuadas mientras estaba en el monitor. Si añades un competidor hoy, su primer informe cubre las respuestas que lo midieron: el historial anterior a su existencia no cuenta en su contra. Una marca sin respuestas válidas informa mentionRate: null, no 0 %, porque 0 % se leería como una desaparición real.
shareOfVoice en brands es 100 × menciones de esa marca / todas las menciones de marcas seguidas en la ventana, así que las cuotas de una ventana suman 100. Compara marcas dentro de las respuestas que tú recogiste para estos prompts; no es cuota de mercado ni un ranking de visibilidad. El shareOfVoice del endpoint de detalle heredado es la antigua vista de penetración de respuestas, en la que cada marca se cuenta sobre las respuestas recogidas y las cifras pueden sumar más de 100: no mezcles ambas en un mismo gráfico.
competitorOnly (y la lista opportunities) cuenta las respuestas que nombraron a un competidor configurado mientras tu marca estaba ausente. Es la brecha sobre la que puedes actuar.
Las tasas son anulables, no cero. Sin respuestas en la ventana, el valor es null; una tasa cero significa que hubo respuestas y ninguna coincidió.
Una observación completada sin respuesta cuenta como no mencionada. Permanece en el denominador, y quality.noAnswerObservations indica cuántas hubo. Una tarea fallida se excluye de todas las tasas y solo aparece en health: un motor averiado reduce la muestra en lugar de convertirse en silencio en una ausencia, y quality nunca la reconstruye como tal (historicalFailures siempre es null).
Las variaciones se ocultan cuando engañarían. changes y el mentionRateChangePp por celda son null, y quality.comparable es false, cuando un periodo no tiene respuestas (insufficient_periods), cuando hay filas puntuadas antes de que existiera el contexto de puntuación (legacy_scoring_unknown) o cuando la definición de puntuación cambió entre periodos (scoring_definitions_changed). Las filas históricas conservan las definiciones con que se puntuaron (quality.scoring), así que cambiar tus alias o competidores nunca reescribe el pasado. La única excepción es la lectura mensual de competidores descrita arriba.
El tamaño de muestra se publica. quality.lowSample es true por debajo de 30 respuestas puntuadas, quality.missingCells cuenta las celdas prompt × motor configuradas sin respuestas aún, y quality.partialDays indica los días UTC que la ventana corta a la mitad: el recuento menor de un día parcial es aritmética, no un descenso.

position en una fila puntuada es el offset de carácter de la primera coincidencia de alias dentro del texto de la respuesta: un indicador aproximado de prominencia, no un ranking. Es null cuando la marca no aparece, por eso 0 nunca tiene que significar «ausente».

De dónde salen las respuestas

GET /v1/monitors/{id}/sources responde a «qué páginas están ganando estos prompts», con la misma ventana y filtros que el informe y contando respuestas distintas en lugar de citas en bruto, así que una página citada tres veces en una respuesta cuenta una vez.

Parámetro	Regla
`groupBy`	`domain` (por defecto, host sin `www.`) o `page` (URL completa con su etiqueta).
`limit`	1–100, por defecto 20.
`cursor`	El `nextCursor` de la respuesta anterior, devuelto sin cambios. `null` termina la lista.
`days` / `since`+`until` / `engine` / `prompt`	Exactamente como en el informe.

Cada fila lleva citations y prompts (ambos recuentos de respuestas distintas), own para tus dominios registrados y un evidenceTaskId que puedes abrir con el endpoint de respuestas. Aquí no hay un recorte silencioso a los N primeros: cada dominio o página de la ventana es accesible siguiendo el cursor.

Citas a lo largo del tiempo

GET /v1/monitors/{id}/citations devuelve los datos de los gráficos de citas del panel: el total diario de citas de la ventana y una serie diaria para cada dominio y página principal. Solo lee resultados guardados, así que no gasta créditos.

Parámetro	Regla
`days`	`7`, `30` o `90`; por defecto `30`.
`since`+`until`	Una ventana fija de hasta 90 días, como en el informe. Si se indica, `days` es solo una etiqueta.
`engine` / `prompt`	Igual que en el informe.
`kind`	`all` (por defecto), `owned`, `editorial`, `pr_wire`, `institution`, `reviews`, `commerce`, `social`, `other`.
`q`	Filtra dominios por nombre o páginas por URL. Hasta 200 caracteres.
`offset`	0–10.000. Cada lista devuelve 20 filas.

Aquí una cita es una página que aparece en una respuesta, así que la misma página dos veces en una respuesta cuenta una sola vez. /sources cuenta respuestas distintas, por lo que sus cifras pueden diferir.

Campo	Significado
`totals`	`answers`, `citedAnswers`, `citations` y `ownedCitations` de la ventana.
`days`	Una entrada por día UTC medido con `answers`, `citations` y `ownedCitations`. Un día con respuestas pero sin citas aparece con `citations: 0`; un día sin respuestas no aparece.
`domains` / `pages`	Los 20 primeros en el `offset` actual, cada uno con `kind`, `owned`, `citations`, `answers`, `prompts` y una serie `daily` de `{day, citations}`. `daily` solo incluye días con citas.
`types`	Citas y dominios distintos por `kind`, sobre todas las fuentes.
`pagination`	`offset`, `limit`, `totalDomains`, `totalPages`.

La cuota de una fuente es su citations dividido entre totals.citations. kind, q y offset solo acotan las listas; totals, days y types siempre cubren todas las fuentes de la ventana.

curl "$BASE/v1/monitors/$MONITOR_ID/citations?days=30&kind=owned" \
  -H "Authorization: Bearer $QUERYING_API_KEY"

Exportar las filas puntuadas

GET /v1/monitors/{id}/results devuelve las filas en sí, para una carga en un data warehouse, una presentación semanal o una hoja de cálculo.

Parámetro	Regla
`since` · `until`	Semiabierto, por defecto los últimos 30 días hasta ahora. `since` también acepta un `YYYY-MM-DD` suelto (leído como `00:00:00Z`) por compatibilidad con la exportación original; el endpoint del informe no.
`engine` · `prompt`	Los mismos filtros que el informe.
`mentioned` · `cited`	`true`/ `false`. `mentioned=false` es la vista de brecha competitiva.
`competitor`	Un nombre exacto de competidor configurado; conserva las respuestas cuya lista de competidores almacenada lo contiene.
`includeEvidence`	Añade `answerText`, `sources` y `scoringContext` a cada fila y reduce el límite de tamaño de página.
`limit`	1–10.000, por defecto 10.000. Con `includeEvidence` el valor por defecto y el máximo son 100.
`format`	`json` (por defecto) o `csv`.
`cursor`	El `nextCursor` de la respuesta anterior.

La paginación es un keyset sobre (ranAt, id) con precisión de microsegundos, así que las filas que comparten marca de tiempo no se pueden saltar ni repetir. Para que la extracción sea repetible: envía since y until explícitos, mantenlos fijos y sigue nextCursor hasta que sea null. Cambiar la ventana entre páginas puede saltar o repetir filas. Trata el cursor como opaco: se devuelve y se reenvía, nunca se construye. Con format=csv la respuesta es text/csv (UTF-8 con BOM, para que Excel la abra correctamente) y el estado de paginación pasa a las cabeceras, porque un cuerpo CSV no tiene otro sitio donde ponerlo:

Cabecera	Significado
`x-next-cursor`	El cursor de la página siguiente; vacío en la última página.
`x-result-truncated`	`true` cuando coincidieron más filas de las que devolvió esta página.
`x-result-since` · `x-result-until`	La ventana resuelta, para que una exportación reanudada pueda fijarla.

Las columnas son ran_at, monitor, engine, prompt, mentioned, cited, position, competitors, task_id, más answer_text, sources, scoring_context cuando includeEvidence=true (sources y scoring_context como texto JSON dentro de sus celdas). Las celdas que podrían interpretarse como una fórmula se neutralizan antes de escribirse, así que el texto de terceros no puede convertirse en una fórmula en tu hoja.

Leer la respuesta detrás de una cifra

GET /v1/monitors/{id}/answers/{taskId} devuelve la evidencia conservada de una fila:

answerText: la respuesta tal como la dio el motor, en markdown cuando está disponible, como máximo 8.000 caracteres, cortada con puntos suspensivos si era más larga.
sources: las citas en el orden del motor, cada una con su etiqueta y su posición (empezando en 1) en esa lista.
aliases y competitors: contra qué se comparó esta fila, para que la mención pueda comprobarse en lugar de darse por buena.
scoringContext: la definición exacta usada, con un hash version, la hora de puntuación, answerPresent y evidenceTruncated cuando el texto anterior se cortó.

Las filas puntuadas antes de que se guardara el contexto de puntuación devuelven scoringKnown: false con los alias actuales del monitor y un evidenceTruncated null. answerText es null cuando el motor no devolvió texto de respuesta.

Errores en esta superficie

El sobre es el mismo que en el resto (consulta Errores); los códigos específicos de la monitorización son:

Código	Estado	Cuándo
`VALIDATION_ERROR`	400	Ventana incorrecta (`days` mezclado con `since`/`until`, un intervalo de más de 90 días, un instante sin zona horaria), un motor desconocido, un prompt demasiado largo, un `limit` fuera de rango o un informe demasiado grande para agregarse: acota la ventana, el motor o el prompt.
`MISSING_API_KEY` / `UNAUTHORIZED`	401	Sin clave, o una clave que no pertenece a esta cuenta.
`KEY_SCOPE_DENIED`	403	Los motores permitidos de la clave no cubren los motores del monitor.
`NOT_FOUND`	404	No existe ese monitor para esta clave (el monitor de otra persona se ve igual), o no hay fila puntuada con ese id de tarea.
`MONITOR_LIMIT`	409	La cuenta ya tiene el número máximo de monitores.
`RATE_LIMITED`	429	Sugerencias de prompts (una cada 20 segundos, 30 por hora) o correos de alerta de prueba (tres por monitor cada cinco minutos).
`SUGGEST_FAILED`	400 / 502 / 503	Se rechazaron las sugerencias de prompts para esta marca, falló el servicio de sugerencias o no está configurado en este despliegue.

Un agente en el circuito

Una secuencia práctica para un agente o un script, usando solo los endpoints de esta página. Es ilustrativa: sustituye tu propia clave, id de monitor y ventana:

GET /v1/monitors/capabilities: lee los motores, precios y límites antes de gastar nada.
GET /v1/monitors: reutiliza un monitor existente para el tema y el mercado, o POST /v1/monitors para crear uno (opcionalmente llamando antes a POST /v1/monitors/suggest y editando los candidatos).
POST /v1/monitors/{id}/run: si necesitas respuestas antes de la siguiente ventana programada.
GET /v1/monitors/{id}/analytics?days=30&engine=CHATGPT: lee primero quality (comparable, lowSample, missingCells, partialDays) y después las cifras. Sondea hasta que health.pending se estabilice y quality.sampleSize deje de crecer.
GET /v1/monitors/{id}/sources?days=30&groupBy=page: pagina con nextCursor para encontrar las páginas que ganan los prompts.
GET /v1/monitors/{id}/answers/{taskId}: abre la respuesta detrás de la primera entrada de opportunities antes de decidir nada.
GET /v1/monitors/{id}/results?since=...&until=...&includeEvidence=true&format=csv: exporta la misma ventana, siguiendo x-next-cursor hasta que esté vacío.

Las mismas operaciones se ofrecen a los agentes como herramientas MCP (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, test_monitor_alert). Las escrituras están anotadas como mutaciones, y create_monitor y run_monitor indican que consumen créditos antes de llamarse.

Límites

Límite	Valor
Monitores por cuenta	20
Tareas por ejecución	200 (`prompts × engines`)
Prompts por monitor	100
Longitud del prompt	2.000 caracteres
Alias de marca	20
Dominios registrados	20
Competidores	Monitor de marca: 10 tuyos, más hasta 15 encontrados. Monitor de categoría: 25 tuyos, más hasta 25 encontrados
Nombre de la categoría	80 caracteres
Subáreas por monitor de categoría	30, de 60 caracteres como máximo cada una
Intervalo	1–168 horas
Ventana del informe	90 días
Página de resultados	10.000 por defecto, 10.000 como máximo; 100 con evidencia
Página de fuentes o evidencia	100

Consulta los precios y la referencia de motores antes de aumentar el volumen.

Primeros pasos

Conceptos clave

Motores

Source Influence

Prompt Research

Monitorización GEO

Migración

API de monitorización GEO: menciones y citas de marca

Qué es un monitor

Los competidores se encuentran solos

Separa los monitores con intención

Monitores de categoría: ordena las marcas de un mercado

Qué ordena el informe

Investiga los prompts a partir de la demanda de búsqueda

Coste y calendario

Endpoints

Crear un monitor

Ejecútalo y lee el informe

Qué significan las cifras

De dónde salen las respuestas

Citas a lo largo del tiempo

Exportar las filas puntuadas

Leer la respuesta detrás de una cifra

Errores en esta superficie

Un agente en el circuito

Límites

​Qué es un monitor

​Los competidores se encuentran solos

​Separa los monitores con intención

​Monitores de categoría: ordena las marcas de un mercado

​Qué ordena el informe

​Investiga los prompts a partir de la demanda de búsqueda

​Coste y calendario

​Endpoints

​Crear un monitor

​Ejecútalo y lee el informe

​Qué significan las cifras

​De dónde salen las respuestas

​Citas a lo largo del tiempo

​Exportar las filas puntuadas

​Leer la respuesta detrás de una cifra

​Errores en esta superficie

​Un agente en el circuito

​Límites

Qué es un monitor

Los competidores se encuentran solos

Separa los monitores con intención

Monitores de categoría: ordena las marcas de un mercado

Qué ordena el informe

Investiga los prompts a partir de la demanda de búsqueda

Coste y calendario

Endpoints

Crear un monitor

Ejecútalo y lee el informe

Qué significan las cifras

De dónde salen las respuestas

Citas a lo largo del tiempo

Exportar las filas puntuadas

Leer la respuesta detrás de una cifra

Errores en esta superficie

Un agente en el circuito

Límites