Monitors

A monitor is a saved query on one Croma endpoint that Croma evaluates on a schedule and emails to up to three addresses. You describe what to watch the same way you would query the endpoint; Croma keeps the schedule, remembers what it already reported, and sends only what appeared since the last run.

Monitors are a feature of the API. Create them with POST /monitors, by asking Claude or any MCP client (Monitors from Claude) or from the console at platform.usecroma.com/monitors, where you describe the monitor in plain words or fill in a form. All three manage the same monitors.

Which endpoints can be monitored?

Every data endpoint, whichever way it is served: see Monitorable sources for the list, with what each one watches, what a run reports and when it is checked. GET /catalog marks the same endpoints with monitorable: true. Only the web search, extraction, generation and research tools, the batch endpoints and retired versions are left out. A new source is monitorable the day it ships. What a run reports depends on the endpoint:

A search (it pages its results) reports the results that were not there before.
A lookup of one record (a case by radicado, a company by NIT, a vehicle by plate, a person’s records) reports what changed in that record. See Watching one record.

And when it runs depends on how it is served, which its served_from says:

served_from: "dataset": Croma refreshes these on a schedule of their own, so a monitor can follow that refresh (cadence: "source") and each run spends one credit.
served_from: "live": these query the source when asked, so a monitor runs them on the clock, daily or weekly, and each run spends the credits of one live request.

Create one

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"
  }'

Field	Meaning
`endpoint`	The endpoint to watch, by path, catalog id or MCP tool name (`anm_notices_search`).
`query`	The request body the monitor sends on every run, validated exactly as a direct request would be. `page` and `per_page` are not allowed.
`schedule`	When to run. See below. Default `{ "cadence": "source" }`.
`recipients`	One to three email addresses.
`notify`	`always` (default) sends an email on every run, including one that found nothing new; `on_new` only when there is something to report.
`language`	`es` (default) or `en`, for the emails.
`relevance`	Optional. A plain-language instruction that filters new results before they are sent. See below.

The response is the monitor with its compiled schedule:

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

The first run

Right after creation the monitor runs once to record what already matches today (up to 500 rows, or the record as it stands) and sends a welcome email with that count and the next run time. From then on, every run reports only what was not seen before.

Watching one record

A monitor on a lookup reads the whole record on every run and compares it with the last reading. Two things can come out of a run:

The record moved. The match carries changes: each value that differs, by its path in the record, with what it was and what it is now.
A list in the record grew. Each new item (a new action on a case, a new fine on a plate, a new filing of a company) is a match of its own, reported like a new search result.

{
  "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" }
  ]
}

Values that change on every read without the record changing (the time the source was consulted, a certificate issued for that request) are left out of the comparison, so a monitor never reports a new timestamp as news.

Schedules

`cadence`	Runs
`source`	Right after the endpoint’s own refresh completes. For a daily source that is once a day, as soon as new data has landed. Dataset-served endpoints only.
`hourly`	Every hour, on the hour.
`daily`	Every day at `at` (HH:MM, default 08:00) in `timezone` (default the source’s).
`weekly`	Every `weekday` (default monday) at `at`.

A monitor can never check a source more often than the source refreshes: a daily dataset refuses hourly with schedule_faster_than_source. A served_from: "live" endpoint has no refresh of its own to follow, so it takes daily or weekly and refuses cadence: "source" with invalid_param. When a source run has to go ahead without the day’s refresh (the source did not publish), the run and its email say so: source_stale is true and the email reads “the source has not published new data since…”, never a plain “nothing new”.

The relevance filter

With relevance set, every new row is judged against your instruction before the email goes out. Rows the filter discards are never lost: they stay in the monitor with relevant: false and the email says how many were left out. If the filter is unavailable, the rows are sent flagged as unreviewed rather than dropped.

{ "relevance": "solo avisos sobre suspensión o caducidad del título" }

GET /monitors/{id}/matches?relevant=false lists what was discarded, with the reason for each row.

Manage it

Call	What it does
`GET /monitors`	Your monitors, with each one’s last run.
`GET /monitors/{id}`	One monitor.
`PATCH /monitors/{id}`	Change anything but the endpoint. `{ "status": "paused" }` pauses, `{ "status": "active" }` resumes.
`POST /monitors/{id}/run`	Run now, outside the schedule.
`GET /monitors/{id}/runs`	Every run: when, what it found, whether the email went out.
`GET /monitors/{id}/matches`	Every reported row, with the relevance verdict.
`DELETE /monitors/{id}`	Removes the monitor, its schedule, runs and matches.

Every email carries an unsubscribe link for its recipient. A monitor left with no recipients is paused.

Credits and limits

Each run spends the same credits as one request to the endpoint: one for a dataset-served search, the live rate for one that queries the source. Creating and managing monitors is free. When the organization has no credits left, the run is recorded as skipped_plan_limit, the recipients are told once a day, and the schedule stays in place. An organization can have up to 20 monitors, each with up to 3 recipients. A run reports up to 500 new rows; beyond that it is flagged truncated.

Get Started

Request types

Countries

Monitors

Which endpoints can be monitored?

Create one

The first run

Watching one record

Schedules

The relevance filter

Manage it

Credits and limits

​Which endpoints can be monitored?

​Create one

​The first run

​Watching one record

​Schedules

​The relevance filter

​Manage it

​Credits and limits

Which endpoints can be monitored?

Create one

The first run

Watching one record

Schedules

The relevance filter

Manage it

Credits and limits