Create a monitor

POST

/api/v1/monitors

Docs menu

Re-checks the same pages on a schedule. Give check_id to copy the pages, domain and mode from a completed check, or give pages and client_domain. Every schedule ends: daily after 90 days, weekly after 365, day7_day30 at day 30. Set notify_email to get one summary email when pages change; it is off by default for monitors made by API.

Key
Bearer key, test or live
Scope
monitors:write
Idempotency
Header recommended

Headers

Idempotency-Keystringoptional

Makes a retry safe: the same key with the same request returns the first answer. See Idempotency.

Request body

JSON. A field this endpoint does not know is refused with unknown_parameter.

schedulestringrequired

dailyweeklyday7_day30

check_idstringoptional

Copy the pages, domain and mode from this completed check.

pagesarray of stringoptional
client_domainstringoptional
textstring or nulloptional
modestringoptional

Default: auto

autotextlink_check

notify_emailbooleanoptional

Email a summary when a page changes. Default false through the API.

metadataobjectoptional

Your own notes: up to 20 keys, each key up to 40 characters, each value up to 500.

project_idstring or nulloptional

Tag the monitor, and every check it runs, to one of your client projects.

Response

201. The monitor.

idstring

mon_...

objectstring

monitor

livemodeboolean
statusstring

activepausedended

pause_codestring or null

insufficient_balancelimit_reachedby_requesthost_opted_out

schedulestring

dailyweeklyday7_day30

modestring

textlink_check

client_domainstring
pagesarray of string
source_check_idstring or null
notify_emailboolean

Email a summary when a page changes. Off by default for monitors made by API, on for monitors made in the console.

next_run_atstring or null
last_run_atstring or null
last_check_idstring or null
runs_completedinteger
ends_atstring

Every schedule has an end: daily 90 days, weekly 365 days, day7_day30 at day 30.

metadataobject

Your own notes: up to 20 keys, each key up to 40 characters, each value up to 500.

created_atstring
ended_atstring or null
project_idstring or null

The client project it is tagged to, in the same workspace; null when none.

Errors

CodeStatusMeaning
missing_scope403The API key does not have the scope this endpoint needs.
body_not_json400The request body must be a JSON object.
unknown_parameter400The request has a parameter this endpoint does not accept.
parameter_missing400A required parameter is missing.
schedule_unknown400The schedule must be daily, weekly or day7_day30.
pages_empty400Give at least one page address.
too_many_pages400This check has more pages than your account may send in one check.
no_usable_page400None of the page addresses could be used. Each one is listed under rejected with its reason.
client_domain_invalid400The client domain is not a public web domain, such as example.com.
check_not_completed409The check has not completed.
not_found404No such object.
monitor_limit429The account has as many monitors or monitored pages as it may have.
insufficient_balance402The balance is too low for this request.
new_account_spend_limit429A new account may spend a limited number of credits in 24 hours. The limit lifts as the account ages.
country_blocked403We cannot serve this country.
account_not_onboarded403Finish the account details in the console first.
live_mode_closed403Live mode is not open yet. Test keys work now.

Any request can also fail with missing_api_key, invalid_api_key, api_key_revoked, rate_limited or internal_error. See Errors.

In test mode