Create a new monitor

POST https://uptime.betterstack.com/api/v2/monitors

Headers

Authorization

required string

Bearer $TOKEN

Content-Type

string

application/json

Body parameters

team_name

string

Required if using global API token to specify the team which should own the resource

monitor_type

string

Valid values:
status — We will check your website for a 2XX HTTP status code.
expected_status_code — We will check if your website returned one of the values in expected_status_codes.
keyword — We will check if your website contains the required_keyword.
keyword_absence — We will check if your website doesn't contain the required_keyword.
ping — We will ping your host specified in the url parameter.
tcp — We will test a TCP port at your host specified in the url parameter (port is required).
udp — We will test a UDP port at your host specified in the url parameter (port and required_keyword are required).
smtp — We will check for a SMTP server at the host specified in the url parameter (port is required, and can be one of 25, 465, 587, or a combination of those ports separated by a comma).
pop — We will check for a POP3 server at the host specified in the url parameter (port is required, and can be 110, 995, or both).
imap — We will check for an IMAP server at the host specified in the url parameter (port is required, and can be 143, 993, or both).
dns — We will check for a DNS server at the host specified in the url parameter (request_body is required, and should contain the domain to query the DNS server with).
playwright — We will run the scenario defined by playwright_script, identified in the UI by scenario_name.

url

string

The URL of your website or the host you want to ping. See monitor_type below.

pronounceable_name

string

The name of the monitor

boolean

Send email alerts

sms

boolean

Send SMS alerts

call

boolean

Phone call alerts

push

boolean

Should we send a push notification to the on-call person?

check_frequency

integer (30)

Check frequency (in seconds)

request_headers

array of objects

The request headers that will be send with the check

expected_status_codes

array of integers

An array of status codes you expect to receive from your website. These status codes are considered only if the monitor_type is expected_status_code.

domain_expiration

integer

How many days before the domain expires do you want to be alerted? Valid values are 1, 2, 3, 7, 14, 30, and 60.

ssl_expiration

integer

How many days before the SSL certificate expires do you want to be alerted? Valid values are 1, 2, 3, 7, 14, 30, and 60.

policy_id

string

Set the escalation policy for the monitor.

follow_redirects

boolean

Should we automatically follow redirects when sending the HTTP request?

required_keyword

string

Required if monitor_type is set to keyword or udp. We will create a new incident if this keyword is missing on your page.

team_wait

integer

How long to wait before escalating the incident alert to the team. Leave blank to disable escalating to the entire team. In seconds.

paused

boolean

Set to true to pause monitoring — we won't notify you about downtime. Set to false to resume monitoring.

port

string

Required if monitor_type is set to tcp, udp, smtp, pop, or imap. tcp and udp monitors accept any ports, while smtp, pop, and imap accept only the specified ports corresponding with their servers (e.g. 25,465,587 for smtp).

regions

array of strings

An array of regions to set. Allowed values are ['us', 'eu', 'as', 'au'] or any subset of these regions.

monitor_group_id

string

Set this attribute if you want to add this monitor to a monitor group.

recovery_period

integer

How long the monitor must be up to automatically mark an incident as resolved after being down. In seconds.

verify_ssl

boolean

Should we verify SSL certificate validity?

confirmation_period

integer

How long should we wait after observing a failure before we start a new incident? In seconds.

http_method

string

HTTP Method used to make a request. Valid options: GET, HEAD, POST, PUT, PATCH

request_timeout

integer

How long to wait before timing out the request? In seconds. When monitor_type is set to playwright, this determines the Playwright scenario timeout instead.

request_body

string

Request body for POST, PUT, PATCH requests. Required if monitor_type is set to dns (domain to query the DNS server with).

auth_username

string

Basic HTTP authentication username to include with the request.

auth_password

string

Basic HTTP authentication password to include with the request.

maintenance_days

array of strings

An array of maintenance days to set. If a maintenance window is overnight both affected days should be set. Allowed values are ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun'] or any subset of these days.

maintenance_from

string

Start of the maintenance window each day. We won't check your website during this window. Example: '01:00:00'

maintenance_to

string

End of the maintenance window each day. Example: '03:00:00'

maintenance_timezone

string

The timezone to use for the maintenance window each day. Defaults to UTC. The accepted values can be found in the Rails TimeZone documentation. https://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html

remember_cookies

boolean

Do you want to keep cookies when redirecting?

playwright_script

string

For Playwright monitors, the JavaScript source code of the scenario.

scenario_name

string

For Playwright monitors, the scenario name identifying the monitor in the UI.

201

Returns newly created monitor

Response body

{
  "data": {
    "id": "238",
    "type": "endpoint",
    "attributes": {
      "url": "https://uptime.betterstack.com",
      "pronounceable_name": "Uptime homepage",
      "monitor_type": "keyword",
      "monitor_group_id": "12345",
      "last_checked_at": "2020-09-01T14:17:46.000Z",
      "status": "up",
      "policy_id": null,
      "team_name": "Test team",
      "required_keyword": "We call you",
      "verify_ssl": true,
      "check_frequency": 30,
      "call": true,
      "sms": true,
      "email": true,
      "team_wait": null,
      "http_method": "get",
      "request_timeout": 15,
      "recovery_period": 0,
      "request_body": "",
      "paused_at": null,
      "created_at": "2020-02-18T13:38:16.586Z",
      "updated_at": "2020-09-08T13:10:20.202Z",
      "ssl_expiration": 7,
      "domain_expiration": 14,
      "regions": [
        "us",
        "eu",
        "as",
        "au"
      ],
      "maintenance_days": [
        "mon",
        "tue",
        "wed",
        "thu",
        "fri",
        "sat",
        "sun"
      ],
      "port": null,
      "expected_status_codes": [

      ]
    }
  }
}

422

Validation failed

Response body

{
  "errors": {
    "base": [
      "URL is invalid."
    ]
  }
}

Explore documentation

Example cURL

Don't have your API token yet?

Looking for the details of a specific parameter?