Monitores

Un monitor es una consulta guardada sobre un endpoint de Croma 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, pidiéndoselo a Claude o a cualquier cliente MCP (Monitores desde Claude) o desde la consola en platform.usecroma.com/monitors, donde describes el monitor con tus palabras o llenas un formulario. Los tres administran los mismos monitores.

¿Qué endpoints se pueden monitorear?

Todo endpoint de datos, sin importar cómo se sirva: la lista está en Fuentes monitoreables, con lo que vigila cada uno, qué reporta cada ejecución y cada cuánto se revisa. GET /catalog marca los mismos endpoints con monitorable: true. Solo quedan por fuera las herramientas de búsqueda web, extracción, generación e investigación, los endpoints en lote y las versiones retiradas. Una fuente nueva se puede monitorear el día que sale. Lo que reporta una ejecución depende del endpoint:

Una búsqueda (pagina sus resultados) reporta los resultados que antes no estaban.
La consulta de un registro (un proceso por radicado, una empresa por NIT, un vehículo por placa, los antecedentes de una persona) reporta lo que cambió en ese registro. Ver Vigilar un registro.

Y cuándo corre depende de cómo se sirve, que es lo que dice su served_from:

served_from: "dataset": Croma los actualiza con una frecuencia propia, así que un monitor puede seguir esa actualización (cadence: "source") y cada ejecución gasta un crédito.
served_from: "live": consultan a la fuente en el momento, así que el monitor corre por reloj, daily o weekly, y cada ejecución gasta los créditos de una consulta en vivo.

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, 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:

{
  "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 500 filas, o el registro tal como está) y envía un correo de bienvenida con ese conteo y la próxima ejecución. Desde entonces, cada ejecución reporta solo lo que no se había visto.

Vigilar un registro

Un monitor sobre la consulta de un registro lee el registro completo en cada ejecución y lo compara con la lectura anterior. De una ejecución pueden salir dos cosas:

El registro cambió. La coincidencia trae changes: cada valor distinto, por su ruta en el registro, con lo que era y lo que es ahora.
Una lista del registro creció. Cada elemento nuevo (una actuación nueva en un proceso, un comparendo nuevo en una placa, un filing nuevo de una empresa) es una coincidencia propia, reportada como un resultado nuevo de una búsqueda.

{
  "record_key": "record@8d0c1e5a-…",
  "record": { "found": true, "registration_number": "05001310300120240012300", "primary_case": { "court": "Juzgado 2 Civil del Circuito de Medellín" } },
  "changes": [
    { "path": "primary_case.court", "before": "Juzgado 1 Civil del Circuito de Medellín", "after": "Juzgado 2 Civil del Circuito de Medellín" }
  ]
}

Los valores que cambian en cada lectura sin que cambie el registro (la hora de la consulta, un certificado expedido para esa consulta) quedan por fuera de la comparación, así que un monitor nunca reporta una hora nueva como novedad.

Frecuencias

`cadence`	Corre
`source`	Justo después de que termina la actualización del endpoint. En una fuente diaria, una vez al día, apenas llegan datos nuevos. Solo endpoints servidos desde dataset.
`hourly`	Cada hora, en punto.
`daily`	Cada día a las `at` (HH:MM, por defecto 08:00) en `timezone` (por defecto la de la fuente).
`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. Un endpoint served_from: "live" no tiene actualización propia que seguir, así que acepta daily o weekly y rechaza cadence: "source" con invalid_param. 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: uno en una búsqueda servida desde dataset, la tarifa en vivo en una que consulta a la fuente. 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

Monitores

¿Qué endpoints se pueden monitorear?

Crear uno

La primera ejecución

Vigilar un registro

Frecuencias

El filtro de relevancia

Administrarlo

Créditos y límites

​¿Qué endpoints se pueden monitorear?

​Crear uno

​La primera ejecución

​Vigilar un registro

​Frecuencias

​El filtro de relevancia

​Administrarlo

​Créditos y límites

¿Qué endpoints se pueden monitorear?

Crear uno

La primera ejecución

Vigilar un registro

Frecuencias

El filtro de relevancia

Administrarlo

Créditos y límites