Monitor settings Beta
Used as the body when you create or update a monitor, and returned as settings when you get one. When creating, only url is required. When updating, send only what you want to change.
| Field | Type | Default | Allowed values and notes |
|---|---|---|---|
type | string | "http" | What to check: http, httpcustom, tcp, udp, ping, dns, smtp, pop3 or imap. See Check types. Existing monitors are http. |
url | string | required | For http and httpcustom, an http:// or https:// URL, up to 2048 characters. For every other type, a bare host such as mail.example.com, up to 255 characters, with any scheme or path stripped and a port moved into port (host is accepted as well as url). No username or password in the URL; use authUsername and authPassword. Private, local and blocked addresses are refused. A monitor clashes with another only when the type, host and port all match. |
name | string | "" | Up to 200 characters. |
intervalMinutes | integer | 15 | 1, 5, 15, 30 or 60. If regions includes anything other than default, the interval must be 15 or more. |
regions | string[] | ["default"] | At least one of default (United Kingdom), na (North America) and eu (Europe). With more than one, checks take turns between them. Other codes, such as apac and latam, may be listed by options as unavailable and are refused. |
timeoutSeconds | integer | 30 | 5, 10, 15, 20 or 30. A check that takes longer fails. |
shouldContain | string | "" | Text the page must contain to count as up. Exact and case-sensitive. Up to 500 characters. Empty means no check. |
shouldNotContain | string | "" | Text the page must not contain to count as up. Exact and case-sensitive. Up to 500 characters. |
postData | string | "" | When set, the check sends a POST with this body instead of a GET. Up to 2000 characters. Sent as application/x-www-form-urlencoded unless you set a Content-Type in requestHeaders. Only allowed when regions is ["default"] (United Kingdom only). |
requestHeaders | object[] | [] | Extra headers as { "name": "…", "value": "…" }, up to 20. Values up to 1000 characters. Headers that are set automatically, such as Host, Content-Length and Connection, can't be used. |
authUsername | string | "" | Username for HTTP basic authentication on the web types, and the mailbox to sign in as on an smtp check. Up to 200 characters. Clearing it also removes the stored password. |
authPassword | string | none | Password for HTTP basic authentication, or for the smtp sign-in. Up to 300 characters. Write-only: stored encrypted and never returned; read hasAuthPassword instead. On update, leave it out to keep the stored password, or send "" to remove it. |
hasAuthPassword | boolean | false | Read-only. Whether a password is stored. |
verifyCertificate | boolean | true | When true, an invalid TLS certificate makes the check fail. |
sslDownDays | integer | 0 | 0, 1, 3, 7, 14 or 30. Treat the site as down this many days before its certificate expires. 0 turns this off. |
port | integer | null | null | 1 to 65535. Required for tcp and udp. For smtp, pop3 and imap it falls back to the standard port for the encryption chosen (25, 110, 143 plain or with STARTTLS; 465, 995, 993 with tls). Ignored by the web types and ping. |
sendString | string | "" | For tcp and udp: what to send once connected, up to 500 characters. \r, \n and \t are sent as real characters. |
expectString | string | "" | Up to 500 characters. For tcp and udp, the reply must contain it. For smtp, pop3 and imap, it is matched against the greeting. |
encryption | string | "none" | none, tls (encrypted from the start) or starttls (upgraded after the greeting). Mail types only. |
dnsRecordType | string | "A" | For dns: A, AAAA, CNAME, MX, TXT, NS or SOA. |
dnsExpected | string | "" | For dns: the answer must contain this, ignoring case and a trailing dot. Up to 500 characters. |
dnsNameserver | string | "" | For dns: ask this nameserver instead of the default resolver. Up to 255 characters, and it must be a public address. |
customField | string | "" | For httpcustom: the field to read from the JSON or XML the endpoint returns, as a dotted path such as status.state. Required for that type. Up to 200 characters. |
customExpected | string | "" | For httpcustom: the value that field must hold, ignoring case and surrounding spaces. Up to 200 characters. Empty means the field only has to exist. |
importance | string | "high" | high or low. |
alertAfterMinutes | integer | 0 | 0, 1, 2, 3, 5, 10, 15, 30 or 60. How long an outage must last before an alert is sent. 0 alerts as soon as the outage is confirmed. |
resendEveryMinutes | integer | 0 | 0, 5, 10, 15, 30, 60, 120, 360 or 1440. Repeat the alert this often while the site stays down. 0 sends it once. |
notifyBackUp | boolean | true | Send an alert when the site is back up. |
alertMessage | string | "" | Your own text, added to alert emails. Up to 500 characters. |
recipients | integer[] | the key's owner | Ids of the users in your workspace who get alert emails. Ids are returned in recipients on Get a monitor. Send [] for no email alerts. On update, leave it out to keep the current list. |
contacts | string[] | [] | Ids of the alert contacts to alert, up to 200. Each looks like ct_5b8d1f0a9c2e4d6f7a83. On update, leave it out to keep the current list. |
teams | string[] | [] | Ids of the alert teams to alert, up to 200. Each looks like tm_2c7e91a4b6d0f3e85a17. On update, leave it out to keep the current list. |
tags | string[] | [] | Tag names, up to 20, each up to 80 characters. New tags are created as needed. Duplicates (ignoring case) are dropped. On update, leave it out to keep the current tags, or send a list to replace them. |
Which settings apply depends on the type. Locations (regions), the certificate settings, the text checks, postData and requestHeaders are for the web types only. Check types lists what each type uses.
A monitor alerts its recipients, its contacts and everyone in its teams. The three lists are merged and de-duplicated by address, so nobody gets the same alert twice. See Alerting.
Where a field only takes certain numbers, any other number returns 400. Booleans also accept 1, "1" and "true"; anything else counts as false.
Example: a monitor with authentication and headers
Request body
- {
- "url": "https://staging.example.com/health",
- "name": "Staging health",
- "intervalMinutes": 5,
- "timeoutSeconds": 10,
- "shouldContain": "\"status\":\"ok\"",
- "requestHeaders": [{ "name": "Accept", "value": "application/json" }],
- "authUsername": "monitor",
- "authPassword": "s3cret-value",
- "importance": "low",
- "resendEveryMinutes": 60,
- "alertMessage": "Staging is down. Check the deploy log first.",
- "recipients": [42, 57],
- "tags": ["staging"]
- }
Related
- Create a monitor: send these as the body
- Update a monitor: change any of them later
- Setting options: the allowed values, from the API