# Monitors API guide



## Endpoint reference

## monitors/analytics

`GET /v1/monitors/analytics`

Your monitoring at a glance: monitors by state, completed and pending checks, findings, alert delivery, credits used, checks served from cache and time to the first finding.

*Monitoring analytics*

| Parameter | Required | Description |
| --- | --- | --- |
| `days` | no | Window, up to 90 days — e.g. `30` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/monitors/analytics" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "window": {},
  "monitors": {},
  "runs": {},
  "findings": {},
  "delivery": {},
  "suppressed_duplicates": 0
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/monitors/analytics#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/monitors/analytics.json)


## monitors/create

`GET /v1/monitors/create`

Save a monitor and its schedule. A subject monitor follows a resolved name across platforms and records new findings; a feed monitor records new items from a review or listing endpoint; a change monitor snapshots a page or endpoint. Creating costs the listed credits. Each run reserves its quoted credits before starting; unused reserved credits are refunded. Runs pause if available account funding cannot cover the next check. No monthly monitor cap applies.

*Create a monitor*

| Parameter | Required | Description |
| --- | --- | --- |
| `kind` | no | What kind of monitor: subject (a name, handle, product or topic followed across platforms), feed (new items from one review or listing endpoint) or change (a page or endpoint snapshot, the original monitor). Defaults to subject when query is given, change otherwise. Accepted values: subject, feed, change. Case, spaces, hyphens and underscores are interchangeable. — e.g. `subject` |
| `query` | no | What to watch: a name, product, handle, domain or keyword for a subject monitor; for a feed template, its identifier — a subreddit, a video link, an app id, or for Google Maps reviews a pasted Maps link or a Place id (a link is resolved through one places search, charged once). — e.g. `Monzo` |
| `entity` | no | subject: the sense id chosen from a preview or a clarification (bare for the plain name, sense:… for a qualified one) — e.g. `bare` |
| `entity_type` | no | subject: creator_media, developer, brand, company, event or community — guides source routing Accepted values: creator_media, developer, brand, company, event, community. Case, spaces, hyphens and underscores are interchangeable. — e.g. `brand` |
| `purpose` | no | A preset id (brand_mentions, complaints, competitor_activity, switching_intent, purchase_intent, questions, developments, app_reviews, local_reviews, custom) or a short free-text purpose — e.g. `complaints` |
| `sources` | no | subject: platforms to search, comma-separated; defaults to the preset's recommendation — e.g. `reddit,x,hackernews` |
| `exclude` | no | subject: platforms to leave out — e.g. `tiktok` |
| `relationships` | no | subject: which classes of material count as findings (official_owned, employee_team, collaborator_partner, editorial_news, fan_clip, independent_audience). Default: everything except unrelated material. Accepted values (comma-separated): independent_audience, editorial_news, official_owned, employee_team, collaborator_partner, fan_clip. Case, spaces, hyphens and underscores are interchangeable. — e.g. `independent_audience,editorial_news` |
| `filters` | no | subject: deterministic purpose filters applied to findings: complaints, switching, buying, questions Accepted values (comma-separated): complaints, switching, buying, bugs_crashes, bugs_glitches, bugs_exploits, bugs_blockers, bugs_performance, requests, questions. Case, spaces, hyphens and underscores are interchangeable. — e.g. `complaints` |
| `aliases` | no | subject: other names the subject is known by, comma-separated — e.g. `@monzo,Monzo Bank` |
| `max_metered` | no | subject: how many metered platforms each run may spend on, 0-2 (default 1) — e.g. `1` |
| `lookback_days` | no | subject: how far back the first run looks (default 7); later runs continue from the last successful run — e.g. `7` |
| `feed_platform` | no | feed: platform of the review or listing endpoint — e.g. `app_store` |
| `feed_endpoint` | no | feed: endpoint id, e.g. app-reviews — e.g. `app-reviews` |
| `feed_params_json` | no | feed: JSON object of parameters for the endpoint — e.g. `{"app_id":"310633997"}` |
| `schedule_minutes` | no | Minutes between runs. The console offers 60, 360, 1440 and 10080; the API accepts any value from 15 to 43200. — e.g. `1440` |
| `monthly_cap_credits` | no | Legacy field accepted for compatibility but ignored and returned as null. It does not impose a spending cap. Account balance, quoted run cost and existing account safeguards still apply. |
| `delivery_in_app` | no | Create an in-app notification when a run finds something new (default true) — e.g. `true` |
| `delivery_webhook` | no | Emit monitor.findings to your signed webhook endpoints (default false) — e.g. `true` |
| `name` | no | Human label; suggested from the purpose and subject when omitted — e.g. `Monzo complaints` |
| `url` | no | change: page to watch. Give this OR platform+endpoint. — e.g. `https://example.com/pricing` |
| `platform` | no | change: platform of an API endpoint to watch, e.g. github. Give with endpoint. — e.g. `github` |
| `endpoint` | no | change: endpoint id to watch, e.g. repo — e.g. `repo` |
| `params_json` | no | change: JSON object of parameters passed to the watched endpoint on every run — e.g. `{"owner":"vercel","repo":"next.js"}` |
| `output` | no | subject and feed: report (each run leads with what changed and why it matters, every line with its receipts; the default for the intelligence templates) or everything (every new post, comment or review, listed; the default for feeds and follow templates) Accepted values: report, everything. Case, spaces, hyphens and underscores are interchangeable. — e.g. `report` |
| `destinations` | no | JSON array of where alerts go and how often. kind: email (the account address), endpoint (one of your Slack channels, Discord channels or webhooks by endpoint_id; omit endpoint_id for every active endpoint), push (the devices that turned push on). cadence: immediate, daily or weekly. min_severity for immediate: info (every new finding), notable or critical. The monitor page is always included unless delivery_in_app=false. Replaces delivery_email, delivery_webhook and delivery_mode when given. — e.g. `[{"kind":"endpoint","endpoint_id":"whk_…","cadence":"immediate","min_severity":"notable"},{"kind":"email","cadence":"daily"}]` |
| `feeds_json` | no | Several feeds at once, as a JSON array of {platform, endpoint, params}. Follow an account reads timelines: x/tweets (handle, metered), bluesky/user/posts (handle), youtube/channel/videos (handle or url). Every feed must be live-proven on this deployment; the review says so per feed. — e.g. `[{"platform":"bluesky","endpoint":"user/posts","params":{"handle":"name.bsky.social"}},{"platform":"youtube","endpoint":"channel/videos","params":{"handle":"name"}}]` |
| `expected_run_credits` | no | Optional quote guard: refuse creation when the resolved per-run price differs. Obtain a quote from monitors/test first. — e.g. `2` |
| `result_mode` | no | Change/endpoint monitors: snapshot saves each bounded response without AI; changes applies existing comparison rules (default). One request per check, no automatic pagination. Responses above 200 KB are not retained. — e.g. `snapshot` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `rules` | no | Optional change-monitor rules as a JSON object. Use metric_fields with up to 10 published numeric object JSON pointers (for example /followers or /stats/likes), with result_mode=changes. Unknown/nonnumeric paths are rejected before a source call or charge; missing actual values are not zero and the check is refunded. Numeric selection replaces family rules. Or use watch_fields for generic field comparisons. See /docs/monitors#metric-fields. — e.g. `{"metric_fields":["/followers"]}` |
| `relevance_enabled` | no | Optional on every monitor. Enable or disable relevance filtering. Enabling requires a nonempty relevance_prompt. — e.g. `true` |
| `relevance_prompt` | no | Up to 600 characters describing what should trigger an alert. A nonempty value enables filtering unless explicitly disabled. Empty clears it. — e.g. `Only genuine requests for recommendations; exclude promotions.` |
| `exclusions` | no | Comma-separated phrases skipped before AI; empty clears. Returned by monitor read tools. — e.g. `sponsored,job opening` |

### Useful optional inputs

- `rules`: For metric monitoring, set rules.metric_fields to published numeric JSON pointers before scheduling; missing values are not zero. Preview the estimate first. Confirmed tests use the existing source price; invalid paths are uncharged.
- `sources`: Restrict a multi-source request to the platforms useful for your task. Use dry_run to inspect the resulting quote before fetching.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/monitors/create?url=https%3A%2F%2Fexample.com%2Fpricing" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "id": "monitor_example",
  "status": "active"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/monitors/create#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/monitors/create.json)


## monitors/delete

`DELETE /v1/monitors/delete`

Permanently delete one of your monitors and its recorded run history, and cancel any check already queued for it. A Monocrawl extra: the reference catalogue catalogue has no monitor delete call, which makes its per-account monitor limit unrecoverable. This cannot be undone.

*Delete a monitor*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | yes | Monitor id — e.g. `mon_0f2c8b1d4e6a7c9b0d1e2f3a` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `confirm` | yes | Set to true to permanently delete this monitor. Send an HTTP DELETE request; GET never deletes. — e.g. `true` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl -X DELETE "https://www.monocrawl.com/v1/monitors/delete?id=mon_0f2c8b1d4e6a7c9b0d1e2f3a&confirm=true" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "id": null,
  "name": null,
  "runs_deleted": null,
  "deleted": false,
  "cancelled_checks": []
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/monitors/delete#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/monitors/delete.json)


## monitors/drafts

`GET /v1/monitors/drafts`

The proposals waiting for review. A draft is saved, edited, tested and finally activated into a monitor or discarded; nothing runs or is charged while it is a draft.

*Monitor drafts*

| Parameter | Required | Description |
| --- | --- | --- |
| `draft_id` | no | One draft; without it, every open draft — e.g. `drf_…` |
| `proposal_json` | no | With draft_id: replace the proposal (edited in the review) — e.g. `{…}` |
| `activate` | no | With draft_id: create the monitor from the proposal and close the draft — e.g. `true` |
| `discard` | no | With draft_id: close the draft without creating anything — e.g. `true` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/monitors/drafts" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "id": null,
  "status": null,
  "proposal": {},
  "items": [],
  "count": 0
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/monitors/drafts#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/monitors/drafts.json)


## monitors/export

`GET /v1/monitors/export`

Every finding in the window with its receipts — source, quote, link, author, posted time, severity, matches, story, topic, your verdict and the raw evidence row it was made from — as CSV or JSON.

*Export the evidence*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | yes | Monitor id — e.g. `mon_…` |
| `format` | no | csv (default) or json Accepted values: csv, json. Case, spaces, hyphens and underscores are interchangeable. — e.g. `csv` |
| `days` | no | Window, up to 365 days — e.g. `30` |
| `feedback` | no | Only findings with this verdict Accepted values: known, resolved, irrelevant, useful. Case, spaces, hyphens and underscores are interchangeable. — e.g. `useful` |
| `scope` | no | findings (default): the retained findings of the window. collected: every item one run collected, retained or not, with the decision and the reason; needs run_id, or takes the latest run. Runs before 5 September 2026 did not keep their collected items and say so. Accepted values: findings, collected. Case, spaces, hyphens and underscores are interchangeable. — e.g. `collected` |
| `run_id` | no | With scope=collected: the run to export. Defaults to the latest run. — e.g. `1396` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/monitors/export?id=mon_%E2%80%A6" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "format": null,
  "filename": null,
  "content_type": null,
  "body": null,
  "rows": 0,
  "truncated": false
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/monitors/export#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/monitors/export.json)


## monitors/feedback

`GET /v1/monitors/feedback`

Records your verdict on findings and remembers it: what you mark known, resolved or irrelevant is not surfaced again by later runs (the same conversation, link, wording, topic or, for irrelevant, author), and what you mark useful is kept as a positive example for the relevance filter.

*Mark findings known, resolved, irrelevant or useful*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | yes | Monitor id — e.g. `mon_…` |
| `ids` | yes | Finding ids, comma-separated — e.g. `fnd_…,fnd_…` |
| `verdict` | yes | known, resolved, irrelevant or useful Accepted values: known, resolved, irrelevant, useful. Case, spaces, hyphens and underscores are interchangeable. — e.g. `irrelevant` |
| `scope` | no | finding (default) or story: apply to the whole story the findings belong to Accepted values: finding, story. Case, spaces, hyphens and underscores are interchangeable. — e.g. `story` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/monitors/feedback?id=mon_%E2%80%A6&ids=fnd_%E2%80%A6%2Cfnd_%E2%80%A6&verdict=irrelevant" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "monitor_id": null,
  "verdict": null,
  "marked": 0,
  "remembered": 0,
  "stories_muted": 0,
  "note": null
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/monitors/feedback#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/monitors/feedback.json)


## monitors/findings

`GET /v1/monitors/findings`

The findings a subject or feed monitor has recorded, newest first: each with its platform, author, link, posted time, relationship to the subject and the purpose filters it matched. A finding is recorded once per monitor, however many runs see it.

*List monitor findings*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | yes | Monitor id — e.g. `mon_0f2c8b1d4e6a7c9b0d1e2f3a` |
| `unseen` | no | Only findings not yet marked as seen — e.g. `true` |
| `run_id` | no | Only findings first recorded by this run — e.g. `42` |
| `limit` | no | Page size, 1-200 (default 50) — e.g. `50` |
| `cursor` | no | Opaque cursor from the previous page |
| `mark_seen` | no | Mark the returned findings as seen — e.g. `true` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `limit`: Bound the returned rows to what your task needs. A smaller limit does not necessarily reduce source calls or price; inspect the quote.
- `cursor`: Continue the same source traversal with the complete returned cursor. Saved-result retrieval and a new source page can have different prices; quote the next call.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/monitors/findings?id=mon_0f2c8b1d4e6a7c9b0d1e2f3a" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "items": [],
  "count": 0,
  "cursor": null,
  "has_more": false,
  "unseen": 0
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/monitors/findings#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/monitors/findings.json)


## monitors/get

`GET /v1/monitors/get`

One monitor with its target, schedule and the summary of its most recent run.

*Get a monitor*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | yes | Monitor id — e.g. `mon_0f2c8b1d4e6a7c9b0d1e2f3a` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/monitors/get?id=mon_0f2c8b1d4e6a7c9b0d1e2f3a" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "id": null,
  "kind": null,
  "name": null,
  "description": null,
  "status": null,
  "workflow": null,
  "capped_reason": null,
  "target_label": null,
  "group_id": null,
  "last_run_at": null,
  "last_success_at": null,
  "next_run_at": null,
  "created_at": null,
  "schedule_minutes": 0,
  "estimated_credits_per_run": 0,
  "monthly_cap_credits": 0,
  "credits_spent_month": 0,
  "consecutive_failures": 0,
  "target": {},
  "subject": {},
  "delivery": {},
  "last_run": {}
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/monitors/get#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/monitors/get.json)


## monitors/health

`GET /v1/monitors/health`

A monitor's health and coverage: recent successful and failed checks, missed checks, stale sources, available coverage, delivery status and checks served from cache.

*Monitor health*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | yes | Monitor id — e.g. `mon_…` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/monitors/health?id=mon_%E2%80%A6" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "monitor_id": null,
  "state": null,
  "window": {},
  "runs": {},
  "sources": [],
  "delivery": {},
  "attention": null
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/monitors/health#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/monitors/health.json)


## monitors/index

`GET /v1/monitors`

Your monitors, newest first, with each one's schedule and next due time.

*List monitors*

| Parameter | Required | Description |
| --- | --- | --- |
| `status` | no | Filter by monitor status: active or paused Accepted values: active, paused, capped. Case, spaces, hyphens and underscores are interchangeable. — e.g. `active` |
| `cursor` | no | Opaque cursor from the previous page |
| `limit` | no | Page size, 1-100 (default 25) — e.g. `25` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `limit`: Bound the returned rows to what your task needs. A smaller limit does not necessarily reduce source calls or price; inspect the quote.
- `cursor`: Continue the same source traversal with the complete returned cursor. Saved-result retrieval and a new source page can have different prices; quote the next call.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/monitors" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "items": [],
  "count": 0,
  "cursor": null,
  "has_more": false
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/monitors/index#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/monitors/index.json)


## monitors/preview

`GET /v1/monitors/preview`

What a subject monitor would do, before it exists: the resolved subject or the senses to choose from, the recommended platforms with reasons, the schedule, the credit estimate from the price list, and a few pieces of no-cost evidence. Runs the free first pass only — no metered platform and no paid fallback is touched.

*Preview a monitor*

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | The name, handle, URL, domain, product or keyword to follow — e.g. `Monzo` |
| `entity` | no | A sense id from an earlier preview, when the name was ambiguous — e.g. `bare` |
| `entity_type` | no | Optional type hint — e.g. `brand` |
| `purpose` | no | Preset id or free text; sets the recommended sources and filters — e.g. `complaints` |
| `sources` | no | Override the recommended platforms — e.g. `reddit,x` |
| `schedule_minutes` | no | Interval used for the monthly estimate — e.g. `1440` |
| `monthly_cap_credits` | no | Legacy field accepted for compatibility but ignored and returned as null. It does not impose a spending cap. Account balance, quoted run cost and existing account safeguards still apply. |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `rules` | no | Optional change-monitor rules as a JSON object. Use metric_fields with up to 10 published numeric object JSON pointers (for example /followers or /stats/likes), with result_mode=changes. Unknown/nonnumeric paths are rejected before a source call or charge; missing actual values are not zero and the check is refunded. Numeric selection replaces family rules. Or use watch_fields for generic field comparisons. See /docs/monitors#metric-fields. — e.g. `{"metric_fields":["/followers"]}` |
| `relevance_enabled` | no | Optional on every monitor. Enable or disable relevance filtering. Enabling requires a nonempty relevance_prompt. — e.g. `true` |
| `relevance_prompt` | no | Up to 600 characters describing what should trigger an alert. A nonempty value enables filtering unless explicitly disabled. Empty clears it. — e.g. `Only genuine requests for recommendations; exclude promotions.` |
| `exclusions` | no | Comma-separated phrases skipped before AI; empty clears. Returned by monitor read tools. — e.g. `sponsored,job opening` |

### Useful optional inputs

- `rules`: For metric monitoring, set rules.metric_fields to published numeric JSON pointers before scheduling; missing values are not zero. Preview the estimate first. Confirmed tests use the existing source price; invalid paths are uncharged.
- `sources`: Restrict a multi-source request to the platforms useful for your task. Use dry_run to inspect the resulting quote before fetching.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/monitors/preview?query=Monzo" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "kind": null,
  "purpose": null,
  "preset": null,
  "name": null,
  "note": null,
  "schedule_minutes": 0,
  "monthly_cap_credits": 0,
  "can_activate": false,
  "requires_choice": false,
  "sample": false,
  "subject": {},
  "estimate": {},
  "availability": {},
  "resolution": {},
  "evidence": [],
  "feeds": []
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/monitors/preview#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/monitors/preview.json)


## monitors/propose

`GET /v1/monitors/propose`

Turns a plain-English request into a complete, editable monitor proposal: what it watches, the identifiers it found, the platforms, the matching rules and exclusions, the frequency, the delivery and the estimated cost, with the reason for each choice. Nothing is created.

*Propose a monitor from plain English*

| Parameter | Required | Description |
| --- | --- | --- |
| `text` | yes | What you want to keep an eye on, in a sentence — e.g. `Tell me when people complain about Monzo on Reddit or Hacker News` |
| `template` | no | Start from a template id instead of, or as well as, the sentence — e.g. `complaints` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/monitors/propose?text=Tell%20me%20when%20people%20complain%20about%20Monzo%20on%20Reddit%20or%20Hacker%20News" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "proposal": {},
  "notes": [],
  "requires_choice": false,
  "choices": [],
  "question": null
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/monitors/propose#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/monitors/propose.json)


## monitors/report

`GET /v1/monitors/report`

Turns a monitor's findings (or one story) into a saved research report with citations, verified facts kept apart from generated interpretation, ready to share or export as Markdown or JSON.

*Save findings as a report*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | yes | Monitor id — e.g. `mon_…` |
| `story_id` | no | Only this story's findings — e.g. `sty_…` |
| `days` | no | Findings from the last N days (default 7) — e.g. `7` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/monitors/report?id=mon_%E2%80%A6" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "report_id": null,
  "url": null,
  "findings": 0,
  "stories": 0
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/monitors/report#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/monitors/report.json)


## monitors/run

`GET /v1/monitors/run`

Queue one monitor check outside its schedule. Review the estimate before confirming. The run reserves its quoted credits, settles the actual charge within that quote and refunds unused credits. If available account funding cannot cover the estimate, no job is started and no credits are charged. No monthly monitor cap applies.

*Run a monitor now*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | yes | Monitor id — e.g. `mon_0f2c8b1d4e6a7c9b0d1e2f3a` |
| `confirm` | no | Without confirm=true the call only returns what a run would cost. With it, the run is charged and queued. — e.g. `true` |
| `expected_run_credits` | no | Refuse a confirmed manual check if its quote changed, including under the reservation lock. — e.g. `2` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/monitors/run?id=mon_0f2c8b1d4e6a7c9b0d1e2f3a" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "id": null,
  "job_id": null,
  "reason": null,
  "message": null,
  "next_run_at": null,
  "needs_confirmation": false,
  "available": false,
  "enqueued": false,
  "charged": 0,
  "estimate": {
    "credits": 0,
    "note": null
  },
  "cap": {}
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/monitors/run#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/monitors/run.json)


## monitors/runs

`GET /v1/monitors/runs`

The check history for a monitor, newest first, with what changed on each run.

*List monitor runs*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | yes | Monitor id — e.g. `mon_0f2c8b1d4e6a7c9b0d1e2f3a` |
| `status` | no | Filter by run status: ok or error Accepted values: ok, error. Case, spaces, hyphens and underscores are interchangeable. — e.g. `ok` |
| `from` | no | Only runs at or after this ISO-8601 time — e.g. `2026-01-01T00:00:00Z` |
| `to` | no | Only runs at or before this ISO-8601 time — e.g. `2026-02-01T00:00:00Z` |
| `include` | no | Add the heavy fields: snapshot and/or diff (omitted by default) — e.g. `snapshot,diff` |
| `cursor` | no | Opaque cursor from the previous page |
| `limit` | no | Page size, 1-100 (default 25) — e.g. `25` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `limit`: Bound the returned rows to what your task needs. A smaller limit does not necessarily reduce source calls or price; inspect the quote.
- `cursor`: Continue the same source traversal with the complete returned cursor. Saved-result retrieval and a new source page can have different prices; quote the next call.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/monitors/runs?id=mon_0f2c8b1d4e6a7c9b0d1e2f3a" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "items": [],
  "count": 0,
  "cursor": null,
  "has_more": false
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/monitors/runs#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/monitors/runs.json)


## monitors/settings

`GET /v1/monitors/settings`

Read or change the monitoring digest schedule and delivery preferences. Reads with no parameters; writes with any supported setting. The legacy monthly_budget_credits field is ignored; account billing limits still apply.

*Monitoring settings*

| Parameter | Required | Description |
| --- | --- | --- |
| `monthly_budget_credits` | no | Deprecated and ignored. No monthly monitor or account monitoring cap is enforced. Runs require sufficient available account funding; account billing limits still apply. |
| `digest_frequency` | no | off, daily or weekly Accepted values: off, daily, weekly. Case, spaces, hyphens and underscores are interchangeable. — e.g. `daily` |
| `digest_hour` | no | UTC hour the digest is assembled — e.g. `8` |
| `digest_email` | no | Send the digest by email — e.g. `true` |
| `digest_webhook` | no | Send the digest to subscribed webhooks — e.g. `false` |
| `digest_report` | no | Also save each digest as a research report — e.g. `false` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/monitors/settings" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "digest_frequency": null,
  "updated_at": null,
  "digest_hour": 0,
  "monthly_budget_credits": null,
  "digest_email": false,
  "digest_webhook": false,
  "digest_report": false
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/monitors/settings#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/monitors/settings.json)


## monitors/stories

`GET /v1/monitors/stories`

The developing stories a monitor's related findings have been grouped into, with counts, severity and when each was last seen.

*Monitor stories*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | yes | Monitor id — e.g. `mon_…` |
| `limit` | no | Stories, newest first — e.g. `20` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `limit`: Bound the returned rows to what your task needs. A smaller limit does not necessarily reduce source calls or price; inspect the quote.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/monitors/stories?id=mon_%E2%80%A6" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "monitor_id": null,
  "items": []
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/monitors/stories#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/monitors/stories.json)


## monitors/test

`GET /v1/monitors/test`

Run one real check for a monitor that does not exist yet and see what you would have been told about. Charged like one run and refunded down to what was retrieved; nothing is recorded and nothing is sent.

*Test a monitor now*

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | no | The name, handle, URL, domain, product or keyword the monitor would follow — e.g. `Monzo` |
| `entity` | no | A sense id from a preview when the name was ambiguous — e.g. `bare` |
| `purpose` | no | Template id or free text — e.g. `complaints` |
| `sources` | no | Platforms to search — e.g. `reddit,x` |
| `filters` | no | Purpose filters Accepted values (comma-separated): complaints, switching, buying, bugs_crashes, bugs_glitches, bugs_exploits, bugs_blockers, bugs_performance, requests, questions. Case, spaces, hyphens and underscores are interchangeable. — e.g. `complaints` |
| `confirm` | no | Without confirm=true the call only returns what the test would cost. With it, the test is charged like one run. — e.g. `true` |
| `endpoint` | no | Endpoint identifier within the platform. — e.g. `profile` |
| `expected_run_credits` | no | Refuse a confirmed preview if the per-run price changed after quoting. — e.g. `2` |
| `kind` | no | change for a URL or endpoint request; subject/feed for existing analysis workflows. — e.g. `change` |
| `monthly_cap_credits` | no | Legacy field accepted for compatibility but ignored and returned as null. It does not impose a spending cap. Account balance, quoted run cost and existing account safeguards still apply. |
| `params_json` | no | JSON object of endpoint parameters. Validated against the current registry; no credentials. — e.g. `{"handle":"torvalds"}` |
| `platform` | no | Platform for an endpoint request. — e.g. `github` |
| `result_mode` | no | snapshot or changes. Neither enables AI on an endpoint request. Accepted values: snapshot, changes. Case, spaces, hyphens and underscores are interchangeable. — e.g. `snapshot` |
| `schedule_minutes` | no | Fixed interval in minutes for the proposed monitor. — e.g. `1440` |
| `url` | no | A page URL instead of platform/endpoint. — e.g. `https://example.com` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `rules` | no | Optional change-monitor rules as a JSON object. Use metric_fields with up to 10 published numeric object JSON pointers (for example /followers or /stats/likes), with result_mode=changes. Unknown/nonnumeric paths are rejected before a source call or charge; missing actual values are not zero and the check is refunded. Numeric selection replaces family rules. Or use watch_fields for generic field comparisons. See /docs/monitors#metric-fields. — e.g. `{"metric_fields":["/followers"]}` |
| `relevance_enabled` | no | Optional on every monitor. Enable or disable relevance filtering. Enabling requires a nonempty relevance_prompt. — e.g. `true` |
| `relevance_prompt` | no | Up to 600 characters describing what should trigger an alert. A nonempty value enables filtering unless explicitly disabled. Empty clears it. — e.g. `Only genuine requests for recommendations; exclude promotions.` |
| `exclusions` | no | Comma-separated phrases skipped before AI; empty clears. Returned by monitor read tools. — e.g. `sponsored,job opening` |

### Useful optional inputs

- `rules`: For metric monitoring, set rules.metric_fields to published numeric JSON pointers before scheduling; missing values are not zero. Preview the estimate first. Confirmed tests use the existing source price; invalid paths are uncharged.
- `sources`: Restrict a multi-source request to the platforms useful for your task. Use dry_run to inspect the resulting quote before fetching.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/monitors/test?url=https%3A%2F%2Fexample.com" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "kind": null,
  "outcome": null,
  "note": null,
  "charged": 0,
  "considered": 0,
  "needs_confirmation": false,
  "target": {},
  "estimate": {},
  "resolution": {},
  "would_report": [],
  "sample": {}
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/monitors/test#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/monitors/test.json)


## monitors/test-delivery

`GET /v1/monitors/test-delivery`

Sends one clearly-marked sample alert (a short report with receipts) to the destinations given, right now, and reports what each one answered. Nothing is recorded, nothing is charged, and no real finding is involved: it proves the channel works before a monitor is switched on.

*Send a sample alert*

| Parameter | Required | Description |
| --- | --- | --- |
| `destinations` | yes | The destinations to send the sample to, as for monitors/create — e.g. `[{"kind":"endpoint","endpoint_id":"whk_…"}]` |
| `name` | no | The monitor name to show on the sample — e.g. `Monzo complaints` |
| `id` | no | The monitor the sample is sent from, when it already exists: the sample then links to that monitor’s page and takes its name. Without it, the sample links to the monitors list. — e.g. `mon_…` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/monitors/test-delivery?destinations=%5B%7B%22kind%22%3A%22endpoint%22%2C%22endpoint_id%22%3A%22whk_%E2%80%A6%22%7D%5D&id=mon_%E2%80%A6" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "sent": 0,
  "failed": 0,
  "results": [],
  "sample": false,
  "note": null
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/monitors/test-delivery#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/monitors/test-delivery.json)


## monitors/timeseries

`GET /v1/monitors/timeseries`

One numeric metric from a monitor's runs as a chartable time series.

*Monitor metric timeseries*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | yes | Monitor id — e.g. `mon_0f2c8b1d4e6a7c9b0d1e2f3a` |
| `metric` | yes | Metric key to chart; a 422 lists the metrics this monitor has recorded — e.g. `content_length` |
| `from` | no | Only points at or after this ISO-8601 time — e.g. `2026-01-01T00:00:00Z` |
| `to` | no | Only points at or before this ISO-8601 time — e.g. `2026-02-01T00:00:00Z` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/monitors/timeseries?id=mon_0f2c8b1d4e6a7c9b0d1e2f3a&metric=content_length" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "monitor_id": null,
  "metric": null,
  "from": null,
  "to": null,
  "count": 0,
  "points": []
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/monitors/timeseries#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/monitors/timeseries.json)


## monitors/trends

`GET /v1/monitors/trends`

A metric over time with the previous period and the baseline beside it, so a change can be judged against what is normal for this monitor.

*Monitor trends*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | yes | Monitor id — e.g. `mon_…` |
| `metric` | no | findings, or any numeric metric the runs record — e.g. `findings` |
| `days` | no | Window, up to 90 days — e.g. `30` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/monitors/trends?id=mon_%E2%80%A6" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "monitor_id": null,
  "metric": null,
  "days": 0,
  "points": [],
  "previous_points": [],
  "current": {},
  "previous": {},
  "comparison": {},
  "baseline": null
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/monitors/trends#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/monitors/trends.json)


## monitors/update

`GET /v1/monitors/update`

Pause, resume, rename, reschedule or re-scope one of your monitors. Give at least one field besides id.

*Update a monitor*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | yes | Monitor id — e.g. `mon_0f2c8b1d4e6a7c9b0d1e2f3a` |
| `status` | no | active to resume runs, paused to stop them. Pausing clears the next run time; resuming schedules the next run one interval from now. Accepted values: active, paused. Case, spaces, hyphens and underscores are interchangeable. — e.g. `paused` |
| `name` | no | New label; pass an empty string to clear it — e.g. `Monzo complaints` |
| `schedule_minutes` | no | New interval between runs; minimum 15, maximum 43200. Rescheduling re-times the next run from now. — e.g. `1440` |
| `monthly_cap_credits` | no | Legacy field accepted for compatibility but ignored and returned as null. It does not impose a spending cap. Account balance, quoted run cost and existing account safeguards still apply. |
| `delivery_in_app` | no | subject/feed: in-app notifications on or off — e.g. `true` |
| `delivery_webhook` | no | subject/feed: signed webhook deliveries on or off — e.g. `false` |
| `sources` | no | subject: replace the platforms searched — e.g. `reddit,hackernews` |
| `relationships` | no | subject: replace which classes of material count Accepted values (comma-separated): independent_audience, editorial_news, official_owned, employee_team, collaborator_partner, fan_clip. Case, spaces, hyphens and underscores are interchangeable. — e.g. `independent_audience` |
| `filters` | no | subject: replace the purpose filters Accepted values (comma-separated): complaints, switching, buying, bugs_crashes, bugs_glitches, bugs_exploits, bugs_blockers, bugs_performance, requests, questions. Case, spaces, hyphens and underscores are interchangeable. — e.g. `complaints` |
| `max_metered` | no | subject: metered platforms per run, 0-2 — e.g. `1` |
| `output` | no | subject and feed: report (each run leads with what changed and why it matters, every line with its receipts; the default for the intelligence templates) or everything (every new post, comment or review, listed; the default for feeds and follow templates) — e.g. `report` |
| `destinations` | no | JSON array of where alerts go and how often. kind: email (the account address), endpoint (one of your Slack channels, Discord channels or webhooks by endpoint_id; omit endpoint_id for every active endpoint), push (the devices that turned push on). cadence: immediate, daily or weekly. min_severity for immediate: info (every new finding), notable or critical. The monitor page is always included unless delivery_in_app=false. Replaces delivery_email, delivery_webhook and delivery_mode when given. — e.g. `[{"kind":"endpoint","endpoint_id":"whk_…","cadence":"immediate","min_severity":"notable"},{"kind":"email","cadence":"daily"}]` |
| `feeds_json` | no | Several feeds at once, as a JSON array of {platform, endpoint, params}. Follow an account reads timelines: x/tweets (handle, metered), bluesky/user/posts (handle), youtube/channel/videos (handle or url). Every feed must be live-proven on this deployment; the review says so per feed. — e.g. `[{"platform":"bluesky","endpoint":"user/posts","params":{"handle":"name.bsky.social"}},{"platform":"youtube","endpoint":"channel/videos","params":{"handle":"name"}}]` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `rules` | no | Optional change-monitor rules as a JSON object. Use metric_fields with up to 10 published numeric object JSON pointers (for example /followers or /stats/likes), with result_mode=changes. Unknown/nonnumeric paths are rejected before a source call or charge; missing actual values are not zero and the check is refunded. Numeric selection replaces family rules. Or use watch_fields for generic field comparisons. See /docs/monitors#metric-fields. — e.g. `{"metric_fields":["/followers"]}` |
| `relevance_enabled` | no | Optional on every monitor. Enable or disable relevance filtering. Enabling requires a nonempty relevance_prompt. — e.g. `true` |
| `relevance_prompt` | no | Up to 600 characters describing what should trigger an alert. A nonempty value enables filtering unless explicitly disabled. Empty clears it. — e.g. `Only genuine requests for recommendations; exclude promotions.` |
| `exclusions` | no | Comma-separated phrases skipped before AI; empty clears. Returned by monitor read tools. — e.g. `sponsored,job opening` |

### Useful optional inputs

- `rules`: For metric monitoring, set rules.metric_fields to published numeric JSON pointers before scheduling; missing values are not zero. Preview the estimate first. Confirmed tests use the existing source price; invalid paths are uncharged.
- `sources`: Restrict a multi-source request to the platforms useful for your task. Use dry_run to inspect the resulting quote before fetching.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/monitors/update?id=mon_0f2c8b1d4e6a7c9b0d1e2f3a" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "id": null,
  "kind": null,
  "name": null,
  "description": null,
  "status": null,
  "workflow": null,
  "capped_reason": null,
  "target_label": null,
  "group_id": null,
  "last_run_at": null,
  "last_success_at": null,
  "next_run_at": null,
  "created_at": null,
  "schedule_minutes": 0,
  "estimated_credits_per_run": 0,
  "monthly_cap_credits": 0,
  "credits_spent_month": 0,
  "consecutive_failures": 0,
  "target": {},
  "subject": {},
  "delivery": {},
  "last_run": {}
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/monitors/update#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/monitors/update.json)