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