Monitores

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.

Los monitores son parte de la API. Créalos con POST /monitors, desde el servidor MCP (create_monitor) o desde la consola en platform.usecroma.com/monitors. Los tres administran los mismos monitores.

¿Qué endpoints se pueden monitorear?

Todo endpoint que responde desde un dataset de Croma y pagina sus resultados. El catálogo los marca: GET /catalog devuelve monitorable: true en cada uno. Las consultas en vivo, que llegan a la fuente en el momento, aún no se pueden monitorear.

Crear uno

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 o por id de catálogo.
`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:

{
  "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.

{ "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.

Primeros pasos

Tipos de solicitud

Países

¿Qué endpoints se pueden monitorear?

Crear uno

La primera ejecución

Frecuencias

El filtro de relevancia

Administrarlo

Créditos y límites

​¿Qué endpoints se pueden monitorear?

​Crear uno

​La primera ejecución

​Frecuencias

​El filtro de relevancia

​Administrarlo

​Créditos y límites

¿Qué endpoints se pueden monitorear?

Crear uno

La primera ejecución

Frecuencias

El filtro de relevancia

Administrarlo

Créditos y límites