Monitors API

Manage your monitors using simple HTTP API.
Do you need help with the integration? 
Let us know at [email protected].
Obtaining an API token
Please, see Obtaining an API token.
get
Listing all existing monitors
https://betteruptime.com/api/v2/monitors
Returns list of all your monitors.
Request
Response
Request
Headers
Authorization
required
string
Bearer YOUR_API_TOKEN
Query Parameters
url
optional
string
Filter monitors by their URL property
pronounceable_name
optional
string
Filter monitors by their pronounceable name property
Response
200: OK
Returns list of existing monitors

The status attribute can have one of the following values:
  paused - the monitor was paused
  pending - the monitor was just created and it's waiting for the first check
  maintenance - the monitor is paused because it is currently in its maintenance period
  up - checks are passing
  validating - service seems to be back up, but the recovery_period since the last failed check still hasn't passed
  down - checks are failing

If an escalation policy is set (policy_id) then the simple escalation policy settings (call, sms, email, push) are ignored.
{
  "data": [
    {
      "id": "2",
      "type": "monitor",
      "attributes": {
        "url": "https://betteruptime.com",
        "pronounceable_name": "BetterUptime homepage",
        "monitor_type": "keyword",
        "monitor_group_id": "12345",
        "last_checked_at": "2020-09-01T14:17:46.000Z",
        "status": "up",
        "required_keyword": "We call you",
        "verify_ssl": true,
        "check_frequency": 30,
        "call": true,
        "sms": true,
        "email": true,
        "push": true,
        "team_wait": null,
        "http_method": "get",
        "request_timeout": 15,
        "recovery_period": 0,
        "request_headers": [
          {
            "id": "123",
            "name": "Content-Type",
            "value": "application/xml"
          }
        ],
        "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"],
        "port": null,
        "confirmation_period": 120,
        "expected_status_codes": []
      }
    }
  ],
  "pagination": {
    "first": "https://betteruptime.com/api/v2/monitors?page=1",
    "last": "https://betteruptime.com/api/v2/monitors?page=16",
    "prev": null,
    "next": "https://betteruptime.com/api/v2/monitors?page=2"
  }
}
Example cURL
Example: Filter by URL
Example cURL
curl --request GET \
  --url https://betteruptime.com/api/v2/monitors \
  --header 'Authorization: Bearer YOUR_API_TOKEN'
Example: Filter by URL
curl --request GET \
  --url https://betteruptime.com/api/v2/monitors?url=https://google.com \
  --header 'Authorization: Bearer YOUR_API_TOKEN'
get
Getting a single monitor
https://betteruptime.com/api/v2/monitors/:monitor_id
Request
Response
Request
Path Parameters
monitor_id
required
string
The ID of the monitor you want to get
Headers
Authorization
required
string
Bearer YOUR_API_TOKEN
Response
200: OK
The status attribute can have one of the following values:
  paused - the monitor was paused
  pending - the monitor was just created and it's waiting for the first check
  maintenance - the monitor is paused because it is currently in its maintenance period
  up - checks are passing
  validating - service seems to be back up, but the recovery_period since the last failed check still hasn't passed
  down - checks are failing

If an escalation policy is set (policy_id), then the simple escalation policy settings (call, sms, email, phone) are ignored.
{
  "data": {
    "id": "123456789",
    "type": "monitor",
    "attributes": {
      "url": "https://betteruptime.com",
      "pronounceable_name": "BetterUptime homepage",
      "monitor_type": "keyword",
      "monitor_group_id": "12345",
      "last_checked_at": "2020-09-01T14:17:46.000Z",
      "status": "up",
      "required_keyword": "We call you",
      "verify_ssl": true,
      "check_frequency": 30,
      "call": true,
      "sms": true,
      "email": true,
      "push": true,
      "team_wait": null,
      "http_method": "get",
      "request_timeout": 15,
      "recovery_period": 0,
      "request_headers": [
        {
          "id": "123",
          "name": "Content-Type",
          "value": "application/xml"
        }
      ],
      "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"],
      "port": null,
      "confirmation_period": 120,
      "expected_status_codes": []
    }
  }
}
404: Not Found
{
  "errors": "Resource with provided ID was not found"
}
Example cURL
Example cURL
curl --request GET \
  --url https://betteruptime.com/api/v2/monitors/123456789 \
  --header 'Authorization: Bearer YOUR_API_TOKEN'
get
Getting monitor's response times
https://betteruptime.com/api/v2/monitors/:monitor_id/response-times
Returns the response times for the monitor.
Request
Response
Request
Path Parameters
monitor_id
required
string
The ID of the monitor you're interested in
Headers
Authorization
required
string
Bearer YOUR_API_TOKEN
Response
200: OK
The response times are grouped by the server's region.
{
  "data": {
    "id": "270985",
    "type": "monitor_response_times",
    "attributes": {
      "regions": [
        {
          "region": "us",
          "response_times": [
            {
              "at": "2021-01-24T15:06:03.727Z",
              "response_time": 1.25366666666667
            },
            {
              "at": "2021-01-24T15:06:33.658Z",
              "response_time": 1.239
            },
            {
              "at": "2021-01-24T15:07:05.097Z",
              "response_time": 1.26
            },
            {
              "at": "2021-01-24T15:07:34.961Z",
              "response_time": 1.20933333333333
            }
          ]
        },
        {
          "region": "eu",
          "response_times": [
            {
              "at": "2021-01-24T15:06:03.727Z",
              "response_time": 0.58966666666667
            },
            {
              "at": "2021-01-24T15:06:33.658Z",
              "response_time": 0.611
            },
            {
              "at": "2021-01-24T15:07:05.097Z",
              "response_time": 0.53
            },
            {
              "at": "2021-01-24T15:07:34.961Z",
              "response_time": 0.546
            }
          ]
        }
      ]
    }
  }
}
Example cURL
Example cURL
curl --request GET \
  --url https://betteruptime.com/api/v2/monitors/123456789/response-times \
  --header 'Authorization: Bearer YOUR_API_TOKEN'
get
Getting monitor's availability summary
https://betteruptime.com/api/v2/monitors/:monitor_id/sla
Returns the summary of availability and incidents recoreded by the monitor.
Request
Response
Request
Path Parameters
monitor_id
required
string
The ID of the monitor you're interested in
Headers
Authorization
required
string
Bearer YOUR_API_TOKEN
Query Parameters
from
optional
string
Start date (e.g., 2021-01-26)
to
optional
string
End date (e.g., 2021-01-27)
Response
200: OK
Returns the availability summary since the monitor was created or for the specified date range.

The values of total_downtime, longest_incident, and average_incident are in seconds.
{
  "data": {
    "id": "258338",
    "type": "monitor_sla",
    "attributes": {
      "availability": 99.98,
      "total_downtime": 600,
      "number_of_incidents": 3,
      "longest_incident": 300,
      "average_incident": 200
    }
  }
}
400: Bad Request
When the optional from and to dates are invalid (e.g., the start date is in the future or the end date is before the start date).
{
  "errors": "The data range is invalid. The date format could not be parsed, the start time is in the future, or the end time is after the start time."
}
Example cURL
Example cURL
curl --request GET \
  --url https://betteruptime.com/api/v2/monitors/123456789/sla?from=2021-01-26&to=2021-01-27 \
  --header 'Authorization: Bearer YOUR_API_TOKEN'
post
Creating a new monitor
https://betteruptime.com/api/v2/monitors
Returns a newly created monitor or validation errors.
Request
Response
Request
Headers
Authorization
required
string
Bearer YOUR_API_TOKEN
Content-Type
required
string
application/json
Form Data Parameters
url
required
string
URL of your website or the host you want to ping (see monitor_type below).
expected_status_codes
optional
array
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.
request_headers
optional
array
An optional array of custom HTTP headers for the request. Set the name and value properties to form a complete header (see example below).
domain_expiration
optional
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
optional
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
optional
string
Set the escalation policy for the monitor.
follow_redirects
optional
boolean
Should we automatically follow redirects when sending the HTTP request?
monitor_type
required
string
Valid values: 
status — We will check your website for 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 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)
required_keyword
optional
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.
call
optional
boolean
Should we call the on-call person?
sms
optional
boolean
Should we send an SMS to the on-call person?
email
optional
boolean
Should we send an email to the on-call person?
push
optional
boolean
Should we send a push notification to the on-call person?
team_wait
optional
integer
How long to wait before escalating the incident alert to the team. Leave blank to disable escalating to the entire team.
paused
optional
boolean
Set to true to pause monitoring — we won't notify you about downtime.

Set to false to resume monitoring.
port
optional
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
optional
array
An array of regions to set. Allowed values are ["us", "eu", "as", "au"] or any subset of these regions.
monitor_group_id
optional
string
Set this attribute if you want to add this monitor to a monitor group.
pronounceable_name
optional
string
Pronounceable name of the monitor. We will use this when we call you. Try to make it tongue-friendly, please?
recovery_period
optional
integer
How long the monitor must be up to automatically mark an incident as resolved after being down.
verify_ssl
optional
boolean
Should we verify SSL certificate validity?
check_frequency
optional
integer
How often should we check your website?
In seconds.
confirmation_period
optional
integer
How long should we wait after observing a failure before we start a new incident?
http_method
optional
string
HTTP Method used to make a request.

Valid options: GET, HEAD, POST, PUT, PATCH
request_timeout
optional
integer
How long to wait before timing out the request? In seconds.
request_body
optional
string
Request body for POST, PUT, PATCH requests.
auth_username
optional
string
Basic HTTP authentication username to include with the request.
auth_password
optional
string
Basic HTTP authentication password to include with the request.
maintenance_from
optional
string
Start of the maintenance window each day. We won't check your website during this window.

In UTC timezone. Example: "01:00:00"
maintenance_to
optional
string
End of the maintenance window each day.

In UTC timezone. Example: "03:00:00"
Response
201: Created
Returns newly created monitor
{
  "data": {
    "id": "238",
    "type": "endpoint",
    "attributes": {
      "url": "https://betteruptime.com",
      "pronounceable_name": "BetterUptime homepage",
      "monitor_type": "keyword",
      "monitor_group_id": "12345",
      "last_checked_at": "2020-09-01T14:17:46.000Z",
      "status": "up",
      "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"],
      "port": null,
      "expected_status_codes": []
    }
  }
}
422: Unprocessable Entity
Validation failed
{
  "errors": {
    "base": [
      "URL is invalid."
    ]
  }
}
Example cURL
Example cURL
curl --request POST \
  --url https://betteruptime.com/api/v2/monitors \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
	"monitor_type": "status",
	"url": "https://facebook.com",
	"pronounceable_name": "Facebook homepage",
	"email": true,
	"sms": true,
	"call": true,
	"check_frequency": 30,
	"request_headers": [
	  {
	    "name": "X-Custom-Header",
	    "value": "custom header value"
	  }
	]
}'
patch
Updating an existing monitor
https://betteruptime.com/api/v2/monitors/:monitor_id
Update existing monitor configuration.
Send only parameters you wish to change (eg. url)
Request
Response
Request
Path Parameters
monitor_id
required
string
The ID of the monitor you want to update
Headers
Authorization
required
string
Bearer YOUR_API_TOKEN
Content-Type
required
string
application/json
Form Data Parameters
url
optional
string
URL of your website or the host you want to ping (see monitor_type below).
expected_status_codes
optional
array
An array of status codes you expect to receive from your website. We will only consider this list if the monitor_type is expected_status_code.
request_headers
optional
array
Add, update, or delete custom headers.

To create a new header, specify only the name and value properties.

To update an existing header, include the id of the header as well.

To delete an existing header, specify the id of the header and add the _destroy boolean flag.

See the example below where all of these operations are shown.
domain_expiration
optional
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
optional
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
optional
string
Change the escalation policy for the monitor.
follow_redirects
optional
boolean
Should we follow redirects when sending the HTTP request?
monitor_type
optional
string
Valid values: 
status — We will check your website for 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 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)
required_keyword
optional
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.
call
optional
boolean
Should we call the on-call person?
sms
optional
boolean
Should we send an SMS to the on-call person?
email
optional
boolean
Should we send an email to the on-call person?
push
optional
boolean
Should we send a push notification to the on-call person?
team_wait
optional
integer
How long to wait before escalating the incident alert to the team. Leave blank to disable escalating to the entire team.
paused
optional
boolean
Set to true to pause monitoring — we won't notify you about downtime.

Set to false to resume monitoring.
port
optional
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
optional
array
An array of regions to set. Allowed values are ["us", "eu", "as", "au"] or any subset of these regions.
monitor_group_id
optional
string
Set this attribute if you want to add this monitor to a monitor group.
pronounceable_name
optional
string
Pronounceable name of the monitor. We will use this when we call you. Try to make it tongue-friendly, please?
recovery_period
optional
integer
How long the monitor must be up to automatically mark an incident as resolved after being down.
verify_ssl
optional
boolean
Should we verify SSL certificate validity?
check_frequency
optional
integer
How often should we check your website?
In seconds.
confirmation_period
optional
integer
How long should we wait after observing a failure before we start a new incident?
http_method
optional
string
HTTP Method used to make a request.

Valid options: GET, POST, PUT, PATCH, HEAD
request_timeout
optional
integer
How long to wait before timing out the request? 
In seconds.
request_body
optional
string
Request body for POST, PUT, PATCH requests.
auth_username
optional
string
Basic HTTP authentication username to include with the request.
auth_password
optional
string
Basic HTTP authentication password to include with the request.
maintenance_from
optional
string
Start of the maintenance window each day. We won't check your website during this window.

In UTC timezone. Example: "01:00:00"
maintenance_to
optional
string
End of the maintenance window each day.

In UTC timezone. Example: "03:00:00"
Response
200: OK
Returns updated monitor data
{
  "data": {
    "id": "2",
    "type": "monitor",
    "attributes": {
      "url": "https://betteruptime.com",
      "pronounceable_name": "BetterUptime homepage",
      "monitor_type": "keyword",
      "monitor_group_id": "12345",
      "last_checked_at": "2020-09-01T14:17:46.000Z",
      "status": "up",
      "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"],
      "port": null,
      "expected_status_codes": []
    }
  }
}
422: Unprocessable Entity
Validation failed
{
  "errors": {
    "base": [
      "URL is invalid."
    ]
  }
}
Example cURL — Change check_frequency only
Example cURL - Manage Custom Request Headers
Example cURL — Change check_frequency only
curl --request PATCH \
  --url https://betteruptime.com/api/v2/monitors/225493 \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
	"check_frequency": 60
}'
Example cURL - Manage Custom Request Headers
curl --request PATCH \
  --url https://betteruptime.com/api/v2/monitors/225493 \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
	"request_headers": [
	  { "name": "X-Create-New-Header", "value": "New Header Value" },
	  { "id": "123", "name": "X-Update-Existing-Header-Name" },
	  { "id": "456", "_destroy": true }
	]
}'
delete
Deleting an existing monitor
https://betteruptime.com/api/v2/monitors/:monitor_id
Permanently deletes an existing monitor.
Request
Response
Request
Path Parameters
monitor_id
required
string
The ID of the monitor you want to delete
Headers
Authorization
required
string
Bearer YOUR_API_TOKEN
Response
204: No Content
Returns empty body
​
Example cURL
Example cURL
curl --request DELETE \
  --url https://betteruptime.com/api/v2/monitors/225493 \
  --header 'Authorization: Bearer YOUR_API_TOKEN'