Monitor settings reference
Every monitor has a set of shared settings plus the settings of its own type (method, keywords, ports, queries and so on). This page lists the shared ones with their API fields. Type-specific settings are on each type’s page (see Choosing a monitor type) and, field by field, in the operator monitor fields reference.
Monitor types
Section titled “Monitor types”Type (API type) |
What it checks | Runs from |
|---|---|---|
http |
A website or URL over HTTP(S) (the Website monitor) | Public locations |
api |
An HTTP API endpoint | Public locations |
ping |
ICMP reachability and round-trip time | Public locations |
port |
A TCP port, optionally with TLS | Public locations |
waterfall |
Page load in a real browser (Page speed; pageSpeed is accepted as an alias) |
Browser locations |
tran |
A scripted browser transaction | Browser locations |
cntCheck |
Page content in a real browser (Content check) | Browser locations |
sslExp |
SSL certificate expiry | Internal network, every 6 h |
domainExp |
Domain registration expiry | Internal network, every 6 h |
dnsbl |
DNS blacklists | Internal network, every 6 h |
webRisk |
Google Web Risk listing | Internal network, every 12 h |
database |
A database query | Private network |
counter |
A server load counter | Private network |
snmp |
An SNMP value | Private network |
GET /monitor/type (no token needed) lists every type with its label, minimum interval and, with a token, whether
your plan can create it. GET /monitor/type/{type} returns the full settings schema of one type.
Shared settings
Section titled “Shared settings”| Setting | API field | Type / allowed values | Default | What it does for you |
|---|---|---|---|---|
| Type | type |
One of the tokens above | - (required) | Which check runs. Cannot be changed after creation (422 type_immutable). |
| Address | url |
Absolute http(s) URL for types that fetch one; a host or IP for ping; host:port for port |
- (required for most types) | What is checked. Two monitors may watch the same address with different settings; saving one whose type, address and settings all match an existing monitor is refused with 409 duplicate_monitor. |
| Name | name |
Text, up to 255 characters | the address | The label on the dashboard, in alerts and on status pages. |
| Check interval | interval |
Seconds; one of the values your plan allows (GET /account -> limits.intervals) |
your account default | How often the monitor runs. Faster intervals depend on your plan (422 invalid_interval lists the allowed ones; 422 interval_below_type_floor for a type’s own minimum). |
| Cron schedule | cronSchedule |
A cron expression; null returns to the interval |
none | Runs on a schedule instead of an interval (plan feature). Check one with POST /monitor/validate-cron. Not available for the fixed-cadence types. |
| Enabled | enabled |
true / false |
true |
false pauses the monitor: no checks and no alerts. |
| Tags | tags (replace), addTags, removeTags (update only) |
Free-form strings | none | Organise and filter monitors; target bulk edits, webhooks and status page bulk-add by tag. |
| Locations | locations.pools, locations.fallback, locations.excludedAgents |
See Locations | pools: required on an API create for location-based types (the app pre-fills your account defaults); fallback starve |
Where the checks run from. Refused for the internal-network types. |
| Recheck strategy | recheck.strategy, recheck.minNumDown |
"" (default: majority vote), minNumDown (with 1-10 locations; the editor offers 1-7), noRecheck, fullAgreement, downFullAgreement |
majority vote | How a suspected failure is confirmed before it becomes an incident. See down detection. |
| SLA target | slaTarget |
Percentage, for example 99.9 |
none | The target uptime summaries measure the monitor against. |
| Full log | fullLog |
true / false (plan feature) |
false |
Logs checks in 5-minute groups instead of 60-minute groups, keeping more detail in the check log. |
| Public statistics | openStat |
true / false |
false |
Makes the monitor’s statistics page and uptime badge readable without signing in. |
| Attached sub-checks | attached.dnsbl, attached.sslExp, attached.domainExp, attached.webRisk |
true / false or a settings object |
off | Runs blacklist, certificate, domain or Web Risk checks alongside an HTTP monitor. See attached sub-checks. |
| Over-limit handling | onOverlimit (write only) |
fail / disable (bulk also stop) |
fail |
When the plan has no room: refuse the write, or create the monitor disabled. |
| Type settings | settings |
An object whose members depend on type |
type defaults | Method, keywords, timeouts, assertions and so on. |
Created along with the monitor in the same request (optional): contacts[] (inline contacts, ref + type +
address), alertSubscriptions[] (contactIds or contactRefs + alertTypes: up, down,
repeatedlyDown) and reportSubscriptions[] (contactIds or contactRefs + frequency: daily, weekly,
monthly, quarterly, yearly). Creating inline contacts needs contact:write and an Idempotency-Key.
Read-only members of a monitor: id, state (up, down, paused, maintenance), since (when the current
state began), created, updated.
Fixed-cadence types
Section titled “Fixed-cadence types”Four types schedule themselves; an interval or cronSchedule sent for them is replaced by the fixed cadence (the
answer carries a warning):
| Type | Cadence |
|---|---|
SSL certificate expiry (sslExp) |
Every 6 hours |
Domain expiry (domainExp) |
Every 6 hours |
DNS blacklist (dnsbl) |
Every 6 hours |
Web Risk (webRisk) |
Every 12 hours |
Assertions
Section titled “Assertions”HTTP and API monitors can carry assertion rules (settings.asserts or settings.assertsSource, with
settings.assertMode) that check status, headers, body, timings and more. See the
assertion language reference.