API reference

Run a Monitor Now API

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.

Read as Markdown Use with an AI agent

Endpoint

GET/v1/monitors/runlive · provenfree

Try in Playground

Parameters

Query parameters

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.

Name	Required	Description	Example
`id`	yes	Monitor id	`mon_0f2c8b1d4e6a7c9b0d1e2f3a`
`confirm`	no	Without confirm=true the call only returns what a run would cost. With it, the run is charged and queued.	`true`
`expected_run_credits`	no	Refuse a confirmed manual check if its quote changed, including under the reservation lock.	`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.	`1`

Examples

Make the request

curl

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

TypeScript

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/run?id=mon_0f2c8b1d4e6a7c9b0d1e2f3a",
  { 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

python

import os
import requests

res = requests.get(
    "https://www.monocrawl.com/v1/monitors/run?id=mon_0f2c8b1d4e6a7c9b0d1e2f3a",
    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.

200 · application/json

{
  "success": true,
  "platform": "monitors",
  "endpoint": "/v1/monitors/run",
  "data": {
    "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": {}
  },
  "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
`id`	`string \| null`	id
`job_id`	`string \| null`	job id
`reason`	`string \| null`	reason
`message`	`string \| null`	message
`next_run_at`	`string \| null`	next run at
`needs_confirmation`	`boolean \| null`	needs confirmation
`available`	`boolean \| null`	available
`enqueued`	`boolean \| null`	enqueued
`charged`	`number \| null`	Nested response fields; optional unless explicitly documented.
`estimate`	`object \| null`	Nested response fields; optional unless explicitly documented.
`estimate.credits`	`number \| null`	Nested response fields; optional unless explicitly documented.
`estimate.note`	`string \| null`	Nested response fields; optional unless explicitly documented.
`cap`	`object \| null`	Nested response fields; optional unless explicitly documented.

Core response fields reviewed from the public response shaper. Fields vary by requested options; additive fields remain allowed.

A request for confirmation is a quote, not a completed check. Enqueued checks settle asynchronously.

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

Run a Monitor Now API

Query parameters

Make the request

Response fields and example

Useful next calls

First call in under a minute