Monitors

A monitor is a saved query on one dataset 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, from the MCP server (create_monitor) or from the console at platform.usecroma.com/monitors. All three manage the same monitors.

Which endpoints can be monitored?

Every endpoint that answers from a Croma dataset and pages its results. The catalog marks them: GET /catalog returns monitorable: true on each one. Live lookups, which query the source at request time, cannot be monitored yet.

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 or catalog id.
`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 200 rows) and sends a welcome email with that count and the next run time. From then on, every run reports only rows that were not seen before.

Schedules

`cadence`	Runs
`source`	Right after the dataset’s own refresh completes. For a daily source that is once a day, as soon as new data has landed.
`hourly`	Every hour, on the hour.
`daily`	Every day at `at` (HH:MM, default 08:00) in `timezone` (default the dataset’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. 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 (a dataset request). 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

Which endpoints can be monitored?

Create one

The first run

Schedules

The relevance filter

Manage it

Credits and limits

​Which endpoints can be monitored?

​Create one

​The first run

​Schedules

​The relevance filter

​Manage it

​Credits and limits

Which endpoints can be monitored?

Create one

The first run

Schedules

The relevance filter

Manage it

Credits and limits