API reference
Test a Monitor Now API
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.
Endpoint
GET/v1/monitors/testlive · provenfreeParameters
Query parameters
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.
| Name | Required | Description | Example |
|---|---|---|---|
query | no | The name, handle, URL, domain, product or keyword the monitor would follow | Monzo |
entity | no | A sense id from a preview when the name was ambiguous | bare |
purpose | no | Template id or free text | complaints |
sources | no | Platforms to search | 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. | complaints |
confirm | no | Without confirm=true the call only returns what the test would cost. With it, the test is charged like one run. | true |
endpoint | no | Endpoint identifier within the platform. | profile |
expected_run_credits | no | Refuse a confirmed preview if the per-run price changed after quoting. | 2 |
kind | no | change for a URL or endpoint request; subject/feed for existing analysis workflows. | 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. | {"handle":"torvalds"} |
platform | no | Platform for an endpoint request. | 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. | snapshot |
schedule_minutes | no | Fixed interval in minutes for the proposed monitor. | 1440 |
url | no | A page URL instead of platform/endpoint. | 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. | 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. | {"metric_fields":["/followers"]} |
relevance_enabled | no | Optional on every monitor. Enable or disable relevance filtering. Enabling requires a nonempty relevance_prompt. | 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. | Only genuine requests for recommendations; exclude promotions. |
exclusions | no | Comma-separated phrases skipped before AI; empty clears. Returned by monitor read tools. | sponsored,job opening |
Examples
Make the request
curl "https://www.monocrawl.com/v1/monitors/test?url=https%3A%2F%2Fexample.com" \ -H "x-api-key: mn_your_key_here"
TypeScript
const key = process.env.MONOCRAWL_API_KEY;
if (!key) throw new Error('Set MONOCRAWL_API_KEY on your server.');
const res = await fetch(
"https://www.monocrawl.com/v1/monitors/test?url=https%3A%2F%2Fexample.com",
{ headers: { "x-api-key": key } },
);
const body = await res.json();
if (!body.success) {
// one error shape for every endpoint — see /docs/errors
throw new Error(`${body.error.type}: ${body.error.message}`);
}
console.log(body.data, "credits left:", body.credits_remaining);Python
import os
import requests
res = requests.get(
"https://www.monocrawl.com/v1/monitors/test?url=https%3A%2F%2Fexample.com",
headers={"x-api-key": os.environ["MONOCRAWL_API_KEY"]},
timeout=60,
)
body = res.json()
if not body["success"]:
# one error shape for every endpoint — see /docs/errors
raise RuntimeError(f"{body['error']['type']}: {body['error']['message']}")
print(body["data"], "credits left:", body["credits_remaining"])Response
Response fields and example
This example is illustrative, not a captured live response. Variable-cost operations may settle a charge different from the list price below. A successful response puts the platform payload in data and reports the exact credits used, remaining balance, request id and cache status beside it.
{
"success": true,
"platform": "monitors",
"endpoint": "/v1/monitors/test",
"data": {
"kind": null,
"outcome": null,
"note": null,
"charged": 0,
"considered": 0,
"needs_confirmation": false,
"target": {},
"estimate": {},
"resolution": {},
"would_report": [],
"sample": {}
},
"credits_used": 0,
"credits_remaining": 99,
"request_id": "req_…",
"cached": false
}The example is illustrative and shows a documented subset of data. The fields below are optional across supported sources; nullable fields can also be absent. Preserve unknown values and accept additional fields.
Schema basis: reviewed response shaper. See schema coverage and validation limits.
Download the data JSON Schema. Validate response.data, not the whole envelope. A valid shape does not establish that every field or source record was returned.
| Field inside data | Type | Meaning |
|---|---|---|
kind | string | null | kind |
outcome | string | null | outcome |
note | string | null | note |
charged | number | null | charged |
considered | number | null | considered |
needs_confirmation | boolean | null | Nested response fields; optional unless explicitly documented. |
target | object | null | Nested response fields; optional unless explicitly documented. |
estimate | object | null | Nested response fields; optional unless explicitly documented. |
resolution | object | null | Nested response fields; optional unless explicitly documented. |
would_report | array | null | Nested response fields; optional unless explicitly documented. |
sample | object | boolean | null | A change-check baseline returns an operation-specific object (page title/length or sampled records). Quotes and subject/feed checks return false; inspect outcome and needs_confirmation. |
Core response fields reviewed from the public response shaper. Fields vary by requested options; additive fields remain allowed.
Failures use the typed error envelope. A confirmed uncharged or refunded failure reports zero; a pending reconciliation can report an unknown charge. Read credits_used and error.details.billing_status, and keep request_id for recovery. Response contract · Error reference