## 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)