> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Programa conjuntos de prompts, lee un único contrato de informe con un denominador explícito y exporta las respuestas que hay detrás de cada cifra.

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](https://querying.ai/es/monitors).

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.

```bash theme={null}
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](/es/research/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.

```bash theme={null}
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:

```text theme={null}
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](/es/research/prompt-research), enviados a nombre de tu cuenta. |

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

## Crear un monitor

```bash theme={null}
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.

```bash theme={null}
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](/es/concepts/errors)); 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:

1. `GET /v1/monitors/capabilities`: lee los motores, precios y límites antes de gastar nada.
2. `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).
3. `POST /v1/monitors/{id}/run`: si necesitas respuestas antes de la siguiente ventana programada.
4. `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.
5. `GET /v1/monitors/{id}/sources?days=30&groupBy=page`: pagina con `nextCursor` para encontrar las páginas que ganan los prompts.
6. `GET /v1/monitors/{id}/answers/{taskId}`: abre la respuesta detrás de la primera entrada de `opportunities` antes de decidir nada.
7. `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](https://querying.ai/es/pricing) y la [referencia de motores](/es/engines/overview) antes de aumentar el volumen.