MegalaniaDocs
Sign inApply for the beta
ProductThe climbPricingMCP for agentsPrivacyDevelopersQuickstartDocsBlogSign in
Docs menu
  1. Docs
  2. Reference
  3. Monitors
Reference

Monitors

llms.txt

GET /v1/monitors

List your monitors and your plan limits.

Your monitors and the limits block (monitors and checks used against your plan). cursor is the next_cursor of the last page.

Parameters

name in required type or values what it is
cursor query no string The next_cursor of the previous page, unchanged. Absent means the first page.
limit query no integer, 1 to 100; default 50 Rows per page, 1 to 100.
q query no string Part of the monitor name, at most 128 characters.
status query no active, paused, failing
sort query no next_run, last_change, credits; default next_run

Answers

status what it means
200 Your monitors.
400 bad_parameter. error.field names the parameter; the message says which values work. An unknown query key is this 400 too.
401 bad_token. The key is missing, not valid, expired, revoked, of an unknown prefix or wrong length, or sent as the api_key query parameter, which no route accepts.
429 rate_limited. Too many requests to this endpoint right now. Wait Retry-After seconds, then send the same request again.
500 internal. Our bug. Try again in a minute; if it stays, report the X-Request-Id.
503 busy. A store we need did not answer, or is not configured on this server. Send the same request again after the Retry-After seconds.

POST /v1/monitors

Create a monitor.

Watches one page or a list of up to 100 pages on a schedule. Checks run on the batch path: each delivered page costs its normal price plus monitor_check (1 credit); failed, blocked and skipped checks are free. Plan caps are checked here: monitors_max, the plan’s fastest schedule and monitor_checks_month. There is no Idempotency-Key: a retried create makes a second monitor.

Body

field required type or values what it is
name yes string Your label. Required on create; quote and test fill in their own.
target no page, list Default page for one URL, list for more. site is refused in the beta.
urls yes array of string
scope no main, fields; default main main compares the page text as markdown; fields compares the extract rules one by one. selector is refused in the beta.
extract no string With scope fields, required. name:css rules joined by |, as on POST /v1.
ignore no array of object
notify no changed, every_run; default changed
webhook_url no string or null https only. Signed like batch.completed.
every no 1h, 6h, 12h, 1d, 7d A preset. Send every, or cron with timezone. Start times are spread by up to 5 minutes.
cron no string Five parts (minute hour day month weekday), numbers, *, ranges, steps and lists only. No faster than your plan allows.
timezone no string An IANA name. Needed with cron.
max_credits_month no integer or null The monitor pauses when a check would pass it, and starts again on the 1st (UTC).
goal no null Not offered in the beta. Any value but null is refused.

Answers

status what it means
201 The monitor, with estimate.
400 bad_parameter. error.field names the parameter; the message says which values work. An unknown query key is this 400 too.
401 bad_token. The key is missing, not valid, expired, revoked, of an unknown prefix or wrong length, or sent as the api_key query parameter, which no route accepts.
403 monitor_limit, monitor_checks_exceeded, forbidden_target or wrong_scope.
429 rate_limited. Too many requests to this endpoint right now. Wait Retry-After seconds, then send the same request again.
500 internal. Our bug. Try again in a minute; if it stays, report the X-Request-Id.
503 busy. A store we need did not answer, or is not configured on this server. Send the same request again after the Retry-After seconds.

POST /v1/monitors/quote

Price a monitor before you save it.

Takes the create body (name optional) and answers credits a month. The page price comes from monitor_id’s own checks in the last 30 days, else a range: low and high are the cheapest and the dearest route your plan allows. price_source says which.

Parameters

name in required type or values what it is
monitor_id query no string When you edit a monitor, its id, so the price uses its last 30 days.

Body

field required type or values what it is
name no string Your label. Required on create; quote and test fill in their own.
target no page, list Default page for one URL, list for more. site is refused in the beta.
urls yes array of string
scope no main, fields; default main main compares the page text as markdown; fields compares the extract rules one by one. selector is refused in the beta.
extract no string With scope fields, required. name:css rules joined by |, as on POST /v1.
ignore no array of object
notify no changed, every_run; default changed
webhook_url no string or null https only. Signed like batch.completed.
every no 1h, 6h, 12h, 1d, 7d A preset. Send every, or cron with timezone. Start times are spread by up to 5 minutes.
cron no string Five parts (minute hour day month weekday), numbers, *, ranges, steps and lists only. No faster than your plan allows.
timezone no string An IANA name. Needed with cron.
max_credits_month no integer or null The monitor pauses when a check would pass it, and starts again on the 1st (UTC).
goal no null Not offered in the beta. Any value but null is refused.

Answers

status what it means
200 The estimate.
400 bad_parameter. error.field names the parameter; the message says which values work. An unknown query key is this 400 too.
401 bad_token. The key is missing, not valid, expired, revoked, of an unknown prefix or wrong length, or sent as the api_key query parameter, which no route accepts.
403 forbidden_target.
429 rate_limited. Too many requests to this endpoint right now. Wait Retry-After seconds, then send the same request again.
500 internal. Our bug. Try again in a minute; if it stays, report the X-Request-Id.
503 busy. A store we need did not answer, or is not configured on this server. Send the same request again after the Retry-After seconds.

POST /v1/monitors/test

Run a dry test of up to 3 pages.

Fetches the first 3 pages of the body now, billed like a batch (failures free, no monitor_check), and answers what the monitor would compare. Waits up to 60 s; still running after that answers 202 with test_id, then send the same body to POST /v1/monitors/test/{id}. A finished test is read once and erased. At most 3 tests run at once: a fourth is 429 rate_limited with Retry-After: 30.

Body

field required type or values what it is
name no string Your label. Required on create; quote and test fill in their own.
target no page, list Default page for one URL, list for more. site is refused in the beta.
urls yes array of string
scope no main, fields; default main main compares the page text as markdown; fields compares the extract rules one by one. selector is refused in the beta.
extract no string With scope fields, required. name:css rules joined by |, as on POST /v1.
ignore no array of object
notify no changed, every_run; default changed
webhook_url no string or null https only. Signed like batch.completed.
every no 1h, 6h, 12h, 1d, 7d A preset. Send every, or cron with timezone. Start times are spread by up to 5 minutes.
cron no string Five parts (minute hour day month weekday), numbers, *, ranges, steps and lists only. No faster than your plan allows.
timezone no string An IANA name. Needed with cron.
max_credits_month no integer or null The monitor pauses when a check would pass it, and starts again on the 1st (UTC).
goal no null Not offered in the beta. Any value but null is refused.

Answers

status what it means
200 The test.
202 Still running.
400 bad_parameter. error.field names the parameter; the message says which values work. An unknown query key is this 400 too.
401 bad_token. The key is missing, not valid, expired, revoked, of an unknown prefix or wrong length, or sent as the api_key query parameter, which no route accepts.
403 forbidden_target.
429 rate_limited. Too many requests to this endpoint right now. Wait Retry-After seconds, then send the same request again.
500 internal. Our bug. Try again in a minute; if it stays, report the X-Request-Id.
503 busy. A store we need did not answer, or is not configured on this server. Send the same request again after the Retry-After seconds.

POST /v1/monitors/test/{id}

Read a dry test that was still running.

Send the same body as the test. 202 while it runs; 200 once, then the test is erased and answers 404.

Parameters

name in required type or values what it is
id path yes string The test_id of POST /v1/monitors/test.

Body

field required type or values what it is
name no string Your label. Required on create; quote and test fill in their own.
target no page, list Default page for one URL, list for more. site is refused in the beta.
urls yes array of string
scope no main, fields; default main main compares the page text as markdown; fields compares the extract rules one by one. selector is refused in the beta.
extract no string With scope fields, required. name:css rules joined by |, as on POST /v1.
ignore no array of object
notify no changed, every_run; default changed
webhook_url no string or null https only. Signed like batch.completed.
every no 1h, 6h, 12h, 1d, 7d A preset. Send every, or cron with timezone. Start times are spread by up to 5 minutes.
cron no string Five parts (minute hour day month weekday), numbers, *, ranges, steps and lists only. No faster than your plan allows.
timezone no string An IANA name. Needed with cron.
max_credits_month no integer or null The monitor pauses when a check would pass it, and starts again on the 1st (UTC).
goal no null Not offered in the beta. Any value but null is refused.

Answers

status what it means
200 The test.
202 Still running.
400 bad_parameter. error.field names the parameter; the message says which values work. An unknown query key is this 400 too.
401 bad_token. The key is missing, not valid, expired, revoked, of an unknown prefix or wrong length, or sent as the api_key query parameter, which no route accepts.
404 not_found. No monitor with that id in your account.
429 rate_limited. Too many requests to this endpoint right now. Wait Retry-After seconds, then send the same request again.
500 internal. Our bug. Try again in a minute; if it stays, report the X-Request-Id.
503 busy. A store we need did not answer, or is not configured on this server. Send the same request again after the Retry-After seconds.

GET /v1/monitors/{id}

Read one monitor.

An id of another account answers 404, never 403.

Parameters

name in required type or values what it is
id path yes string

Answers

status what it means
200 The monitor.
400 bad_parameter. error.field names the parameter; the message says which values work. An unknown query key is this 400 too.
401 bad_token. The key is missing, not valid, expired, revoked, of an unknown prefix or wrong length, or sent as the api_key query parameter, which no route accepts.
404 not_found. No monitor with that id in your account.
429 rate_limited. Too many requests to this endpoint right now. Wait Retry-After seconds, then send the same request again.
500 internal. Our bug. Try again in a minute; if it stays, report the X-Request-Id.
503 busy. A store we need did not answer, or is not configured on this server. Send the same request again after the Retry-After seconds.

DELETE /v1/monitors/{id}

Delete a monitor, its snapshots and its diffs.

Works with any key of the account, a scrape key or an account key. Cancels a check in flight (its queued pages are refunded), erases every snapshot and diff, then deletes the monitor and its history. If the snapshots cannot be erased, it answers 503 busy with Retry-After and deletes nothing. It cannot be undone.

Parameters

name in required type or values what it is
id path yes string

Answers

status what it means
204 Deleted.
400 bad_parameter. error.field names the parameter; the message says which values work. An unknown query key is this 400 too.
401 bad_token. The key is missing, not valid, expired, revoked, of an unknown prefix or wrong length, or sent as the api_key query parameter, which no route accepts.
404 not_found. No monitor with that id in your account.
429 rate_limited. Too many requests to this endpoint right now. Wait Retry-After seconds, then send the same request again.
500 internal. Our bug. Try again in a minute; if it stays, report the X-Request-Id.
503 busy. A store we need did not answer, or is not configured on this server. Send the same request again after the Retry-After seconds.

PATCH /v1/monitors/{id}

Edit, pause or resume a monitor.

Send only what changes. paused true pauses; paused false resumes and checks monitor_checks_month again. Any edit brings back dropped pages. Changing scope, ignore or the scrape parameters starts the snapshots over (the next check is new, not changed) and answers 409 monitor_running while a check runs. null clears webhook_url, max_credits_month or one scrape parameter. A plan downgrade keeps existing schedules until you change them; the monthly checks cap still applies to scheduled checks, run now and any edit that adds checks. A scheduled check over the cap is skipped for free and pauses the monitor with checks_cap until the 1st (UTC).

Parameters

name in required type or values what it is
id path yes string

Body

field required type or values what it is
paused no boolean
name no string Your label. Required on create; quote and test fill in their own.
target no page, list Default page for one URL, list for more. site is refused in the beta.
urls yes array of string
scope no main, fields; default main main compares the page text as markdown; fields compares the extract rules one by one. selector is refused in the beta.
extract no string With scope fields, required. name:css rules joined by |, as on POST /v1.
ignore no array of object
notify no changed, every_run; default changed
webhook_url no string or null https only. Signed like batch.completed.
every no 1h, 6h, 12h, 1d, 7d A preset. Send every, or cron with timezone. Start times are spread by up to 5 minutes.
cron no string Five parts (minute hour day month weekday), numbers, *, ranges, steps and lists only. No faster than your plan allows.
timezone no string An IANA name. Needed with cron.
max_credits_month no integer or null The monitor pauses when a check would pass it, and starts again on the 1st (UTC).
goal no null Not offered in the beta. Any value but null is refused.

Answers

status what it means
200 The monitor.
400 bad_parameter. error.field names the parameter; the message says which values work. An unknown query key is this 400 too.
401 bad_token. The key is missing, not valid, expired, revoked, of an unknown prefix or wrong length, or sent as the api_key query parameter, which no route accepts.
403 monitor_checks_exceeded. Only an edit that adds checks to this monitor, or resuming a monitor paused by you or after failed checks, is refused; a rename passes after a plan downgrade.
404 not_found. No monitor with that id in your account.
409 monitor_running. A check is running; edit urls, target, scope, ignore or the scrape parameters after it ends.
429 rate_limited. Too many requests to this endpoint right now. Wait Retry-After seconds, then send the same request again.
500 internal. Our bug. Try again in a minute; if it stays, report the X-Request-Id.
503 busy. A store we need did not answer, or is not configured on this server. Send the same request again after the Retry-After seconds.

POST /v1/monitors/{id}/run

Run a check now.

Moves the next check to now. It is billed like a scheduled check and counts toward max_credits_month. 409 monitor_running while a check runs, 409 monitor_paused on a paused monitor, 409 monitor_too_soon when the last check is closer than your plan’s fastest schedule (Retry-After in seconds).

Parameters

name in required type or values what it is
id path yes string

Answers

status what it means
202 Queued.
400 bad_parameter. error.field names the parameter; the message says which values work. An unknown query key is this 400 too.
401 bad_token. The key is missing, not valid, expired, revoked, of an unknown prefix or wrong length, or sent as the api_key query parameter, which no route accepts.
403 monitor_checks_exceeded. This month’s page checks plus this run’s pages would pass your plan’s monthly checks.
404 not_found. No monitor with that id in your account.
409 monitor_running, monitor_paused, or monitor_too_soon (the last check was sooner than your plan’s fastest schedule; Retry-After says when).
429 rate_limited. Too many requests to this endpoint right now. Wait Retry-After seconds, then send the same request again.
500 internal. Our bug. Try again in a minute; if it stays, report the X-Request-Id.
503 busy. A store we need did not answer, or is not configured on this server. Send the same request again after the Retry-After seconds.

GET /v1/monitors/{id}/checks

List the checks of a monitor.

Newest first. History is kept 30 days.

Parameters

name in required type or values what it is
id path yes string
cursor query no string The next_cursor of the last page (a check id).
limit query no integer, 1 to 100; default 50 Rows per page, 1 to 100.
outcome query no new, same, changed, failed, skipped

Answers

status what it means
200 The checks.
400 bad_parameter. error.field names the parameter; the message says which values work. An unknown query key is this 400 too.
401 bad_token. The key is missing, not valid, expired, revoked, of an unknown prefix or wrong length, or sent as the api_key query parameter, which no route accepts.
404 not_found. No monitor with that id in your account.
429 rate_limited. Too many requests to this endpoint right now. Wait Retry-After seconds, then send the same request again.
500 internal. Our bug. Try again in a minute; if it stays, report the X-Request-Id.
503 busy. A store we need did not answer, or is not configured on this server. Send the same request again after the Retry-After seconds.

GET /v1/monitors/{id}/checks/{check_id}

Read one check with its diff.

The diff object carries each page’s outcome, its url, and its diff (markdown) or fields (JSON). Over 1 MB the diffs are left out (diff_omitted); read one page with page=N, or download the whole object from download_url.

Parameters

name in required type or values what it is
id path yes string
check_id path yes string
page query no integer Return only this page of the check, by position.

Answers

status what it means
200 The check.
400 bad_parameter. error.field names the parameter; the message says which values work. An unknown query key is this 400 too.
401 bad_token. The key is missing, not valid, expired, revoked, of an unknown prefix or wrong length, or sent as the api_key query parameter, which no route accepts.
404 not_found. No monitor with that id in your account.
429 rate_limited. Too many requests to this endpoint right now. Wait Retry-After seconds, then send the same request again.
500 internal. Our bug. Try again in a minute; if it stays, report the X-Request-Id.
503 busy. A store we need did not answer, or is not configured on this server. Send the same request again after the Retry-After seconds.

GET /v1/monitors/{id}/pages/{position}/snapshot

Download the current snapshot of one page.

A short-lived download link to what the next check compares against.

Parameters

name in required type or values what it is
id path yes string
position path yes integer The page’s place in urls, from 1.

Answers

status what it means
200 The link.
400 bad_parameter. error.field names the parameter; the message says which values work. An unknown query key is this 400 too.
401 bad_token. The key is missing, not valid, expired, revoked, of an unknown prefix or wrong length, or sent as the api_key query parameter, which no route accepts.
404 not_found. No monitor with that id in your account.
429 rate_limited. Too many requests to this endpoint right now. Wait Retry-After seconds, then send the same request again.
500 internal. Our bug. Try again in a minute; if it stays, report the X-Request-Id.
503 busy. A store we need did not answer, or is not configured on this server. Send the same request again after the Retry-After seconds.