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

# Monitores

> Vigila un endpoint de dataset con una frecuencia y recibe por correo lo nuevo: cómo corren los monitores después de cada actualización de la fuente, qué cobran, el filtro de relevancia y la API completa.

Un **monitor** es una consulta guardada sobre un endpoint de dataset que Croma
evalúa con una frecuencia y envía por correo hasta a tres direcciones. Describes
qué vigilar igual que consultarías el endpoint; Croma mantiene la programación,
recuerda lo que ya reportó y envía solo lo que apareció desde la última
ejecución.

<Note>
  Los monitores son parte de la API. Créalos con `POST /monitors`, pidiéndoselo
  a Claude o a cualquier cliente MCP ([Monitores desde Claude](/es/monitors-mcp))
  o desde la consola en
  [platform.usecroma.com/monitors](https://platform.usecroma.com/monitors).
  Los tres administran los mismos monitores.
</Note>

## ¿Qué endpoints se pueden monitorear?

Todo endpoint que responde desde un dataset de Croma y pagina sus resultados:
la lista está en [Fuentes monitoreables](/es/monitors-sources), con el nombre
de herramienta y la hora de actualización de cada uno. `GET /catalog` marca los
mismos endpoints con `monitorable: true`. Las consultas en vivo, que llegan a
la fuente en el momento, aún no se pueden monitorear.

## Crear uno

```bash theme={"dark"}
curl -X POST https://api.croma.run/monitors \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contrato AD9-111",
    "endpoint": "/co/anm/notices-search/v1",
    "query": { "title_number": "AD9-111" },
    "schedule": { "cadence": "source" },
    "recipients": ["legal@example.com"],
    "notify": "always",
    "language": "es"
  }'
```

| Campo        | Significado                                                                                                                              |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `endpoint`   | El endpoint a vigilar, por ruta, id de catálogo o nombre de herramienta MCP (`anm_notices_search`).                                      |
| `query`      | El cuerpo que el monitor envía en cada ejecución, validado exactamente como una solicitud directa. `page` y `per_page` no se permiten.   |
| `schedule`   | Cuándo corre. Ver abajo. Por defecto `{ "cadence": "source" }`.                                                                          |
| `recipients` | De uno a tres correos.                                                                                                                   |
| `notify`     | `always` (por defecto) envía un correo en cada ejecución, incluso si no encontró nada nuevo; `on_new` solo cuando hay algo que reportar. |
| `language`   | `es` (por defecto) o `en`, para los correos.                                                                                             |
| `relevance`  | Opcional. Una instrucción en lenguaje natural que filtra los resultados nuevos antes de enviarlos. Ver abajo.                            |

La respuesta es el monitor con su programación compilada:

```json theme={"dark"}
{
  "data": {
    "id": "mon_5f1c2c0a-9d1e-4a3b-8c7d-1e2f3a4b5c6d",
    "name": "Contrato AD9-111",
    "endpoint": { "id": "anm-notices-search", "path": "/co/anm/notices-search/v1", "source": "ANM", "name": "Notices Search" },
    "query": { "title_number": "AD9-111" },
    "relevance": null,
    "schedule": { "cadence": "source", "timezone": "America/Bogota", "cron": "30 7 * * *", "next_run_at": "2026-09-22T12:30:00.000Z" },
    "recipients": ["legal@example.com"],
    "notify": "always",
    "language": "es",
    "status": "active",
    "created_at": "2026-09-21T15:04:05.000Z",
    "updated_at": "2026-09-21T15:04:05.000Z",
    "last_run": null
  }
}
```

## La primera ejecución

Justo después de crearlo, el monitor corre una vez para registrar lo que ya
coincide hoy (hasta 200 filas) y envía un correo de bienvenida con ese conteo y
la próxima ejecución. Desde entonces, cada ejecución reporta solo filas que no
se habían visto.

## Frecuencias

| `cadence` | Corre                                                                                                                        |
| --------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `source`  | Justo después de que termina la actualización del dataset. En una fuente diaria, una vez al día, apenas llegan datos nuevos. |
| `hourly`  | Cada hora, en punto.                                                                                                         |
| `daily`   | Cada día a las `at` (HH:MM, por defecto 08:00) en `timezone` (por defecto la del dataset).                                   |
| `weekly`  | Cada `weekday` (por defecto monday) a las `at`.                                                                              |

Un monitor nunca puede revisar una fuente más seguido de lo que la fuente se
actualiza: un dataset `daily` rechaza `hourly` con `schedule_faster_than_source`.
Cuando una ejecución `source` tiene que seguir sin la actualización del día (la
fuente no publicó), la ejecución y su correo lo dicen: `source_stale` es `true`
y el correo dice "la fuente no ha publicado datos nuevos desde…", nunca un
simple "sin novedades".

## El filtro de relevancia

Con `relevance`, cada fila nueva se evalúa contra tu instrucción antes de
enviar el correo. Las filas que el filtro descarta nunca se pierden: quedan en
el monitor con `relevant: false` y el correo dice cuántas se dejaron fuera. Si
el filtro no está disponible, las filas se envían marcadas como sin revisar en
vez de descartarse.

```json theme={"dark"}
{ "relevance": "solo avisos sobre suspensión o caducidad del título" }
```

`GET /monitors/{id}/matches?relevant=false` lista lo descartado, con la razón
de cada fila.

## Administrarlo

| Llamada                      | Qué hace                                                                                         |
| ---------------------------- | ------------------------------------------------------------------------------------------------ |
| `GET /monitors`              | Tus monitores, con la última ejecución de cada uno.                                              |
| `GET /monitors/{id}`         | Un monitor.                                                                                      |
| `PATCH /monitors/{id}`       | Cambia todo menos el endpoint. `{ "status": "paused" }` pausa, `{ "status": "active" }` reanuda. |
| `POST /monitors/{id}/run`    | Ejecuta ahora, fuera de la programación.                                                         |
| `GET /monitors/{id}/runs`    | Cada ejecución: cuándo, qué encontró, si salió el correo.                                        |
| `GET /monitors/{id}/matches` | Cada fila reportada, con el veredicto de relevancia.                                             |
| `DELETE /monitors/{id}`      | Elimina el monitor, su programación, sus ejecuciones y sus resultados.                           |

Cada correo lleva un enlace para dejar de recibirlo. Un monitor que se queda sin
destinatarios se pausa.

## Créditos y límites

Cada ejecución gasta los mismos créditos que una solicitud al endpoint (una
solicitud de dataset). Crear y administrar monitores es gratis. Cuando la
organización no tiene créditos, la ejecución queda como `skipped_plan_limit`,
se avisa a los destinatarios una vez al día y la programación se mantiene.

Una organización puede tener hasta 20 monitores, cada uno con hasta 3
destinatarios. Una ejecución reporta hasta 500 filas nuevas; más allá queda
marcada como `truncated`.