Explore documentation
  1. Welcome to Incidents 👋
  2. Frequently Asked Questions
  3. On-call scheduling and alerting
    1. Get started
    2. Slack and other integrations ↗
    3. Tag on-call in Slack
    4. Mobile apps ↗
    5. Connecting external calendars
    6. Advanced guide
  4. Incident management
    1. Get started
    2. AI SRE investigations
    3. Post mortems
    4. Metadata & Catalog
    5. Screening alerts
    6. Reporting ↗
  5. Monitoring
    1. Get started
    2. Working with monitors
    3. Customizing monitors
    4. Monitor types
  6. Status pages
    1. Get started
    2. Advanced guide
  7. Incidents API
    1. Getting an API token
    2. Pagination
    3. Monitors
      1. Monitors API
        1. List monitors GET
        2. Get monitor GET
        3. Monitor response times GET
        4. Monitor availability GET
        5. Create monitor POST
        6. Update monitor PATCH
        7. Remove monitor DELETE
      2. Monitor groups API
    4. Heartbeats
    5. On-call & incidents
    6. Status pages
    7. Metadata
    8. Integrations
    9. Team members
    10. Organization roles
    11. Usage
    12. Reporting

List monitors

Returns list of all your monitors.

GET https://incidents.betterstack.com/api/v2/monitors

Query parameters

team_name
string

Filter monitors belonging to a specified team when using global API token.

url
string

Filter monitors by their URL property.

pronounceable_name
string

Filter monitors by their pronounceable name property.

page
integer

The page number to return, starting with 1.

per_page
integer

Number of results per page. Defaults to 50, maximum 250.

Headers

Authorization
required string

Bearer $TOKEN

200

Returns list of existing monitors.

Response body

{
  "data": [
    {
      "id": "2",
      "type": "monitor",
      "attributes": {
        "url": "https://uptime.betterstack.com",
        "pronounceable_name": "Uptime homepage",
        "auth_username": null,
        "auth_password": null,
        "monitor_type": "keyword",
        "monitor_group_id": 12345,
        "last_checked_at": "2020-09-01T14:17:46.000Z",
        "status": "up",
        "policy_id": null,
        "expiration_policy_id": null,
        "team_name": "Test team",
        "required_keyword": "We call you",
        "verify_ssl": true,
        "check_frequency": 30,
        "effective_check_frequency": 30,
        "effective_check_frequency_reason": null,
        "call": true,
        "sms": true,
        "email": true,
        "push": true,
        "critical_alert": false,
        "team_wait": null,
        "http_method": "get",
        "request_timeout": 15,
        "recovery_period": 0,
        "request_headers": [
          {
            "id": "123",
            "name": "Content-Type",
            "value": "application/xml"
          }
        ],
        "request_body": "",
        "follow_redirects": true,
        "remember_cookies": true,
        "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_from": "01:02:00",
        "maintenance_to": "03:04:00",
        "maintenance_timezone": "Amsterdam",
        "maintenance_days": [
          "mon",
          "tue",
          "wed",
          "thu",
          "fri",
          "sat",
          "sun"
        ],
        "port": null,
        "confirmation_period": 120,
        "expected_status_codes": [],
        "environment_variables": {},
        "proxy_host": null,
        "proxy_port": null,
        "paused": false,
        "playwright_script": null,
        "ip_version": null,
        "checks_version": "v2"
      },
      "relationships": {
        "policy": {
          "data": null
        },
        "expiration_policy": {
          "data": null
        }
      }
    }
  ],
  "pagination": {
    "first": "https://incidents.betterstack.com/api/v2/monitors?page=1",
    "last": "https://incidents.betterstack.com/api/v2/monitors?page=16",
    "prev": null,
    "next": "https://incidents.betterstack.com/api/v2/monitors?page=2"
  }
}

Response attributes

id
string

The ID of the monitor.

type
string

Always monitor.

attributes.url
string

The URL of your website, or the host for Server and Port monitors. For playwright monitors, the scenario name.

attributes.pronounceable_name
string

The name of the monitor, or its URL without the scheme when none is set. We use it when we call you.

attributes.monitor_type
string

What the monitor checks: status, expected_status_code, keyword, keyword_absence, ping, tcp, udp, smtp, pop, imap, dns, or playwright. Create a monitor describes each type.

attributes.monitor_group_id
integer or null

The ID of the monitor group the monitor is in, or null when it's in no group.

attributes.last_checked_at
string or null

When the last check ran, in ISO 8601 format.

attributes.status
string

up when checks are passing, down when they are failing, validating when the service seems back up but the recovery_period since the last failed check hasn't passed yet, paused when the monitor was paused, pending when it was just created and waits for the first check, or maintenance when it's in its maintenance window.

attributes.policy_id
string or null

The ID of the escalation policy for the monitor. When it's set, the call, sms, email, and push settings are ignored.

attributes.expiration_policy_id
integer or null

The ID of the escalation policy for SSL certificate and domain expiration alerts. null means we send an e-mail to the entire team.

attributes.team_name
string

The team the monitor is in.

attributes.required_keyword
string or null

The keyword that keyword, keyword_absence, and udp monitors look for.

attributes.verify_ssl
boolean

Whether we verify the SSL certificate.

attributes.call
boolean

Whether we call the on-call person.

attributes.sms
boolean

Whether we send an SMS to the on-call person.

attributes.email
boolean

Whether we send an e-mail to the on-call person.

attributes.push
boolean

Whether we send a push notification to the on-call person.

attributes.critical_alert
boolean

Whether we send a critical push notification that ignores the mute switch and Do Not Disturb mode.

attributes.team_wait
integer or null

How long to wait before escalating the incident alert to the whole team, in seconds. null means we don't escalate to the team.

attributes.http_method
string

The HTTP method of the request, in lowercase: get, head, post, put, patch, or options.

attributes.request_timeout
integer

How long we wait before the request times out. In milliseconds for ping, tcp, udp, smtp, pop, imap, and dns monitors, in seconds for other types. For playwright monitors, the scenario timeout in seconds.

attributes.recovery_period
integer

How long the monitor must be up before we resolve an incident automatically, in seconds.

attributes.check_frequency
integer

How often you set the monitor to be checked, in seconds.

attributes.effective_check_frequency
integer

How often we actually check the monitor, in seconds. It's longer than check_frequency when effective_check_frequency_reason is set.

attributes.effective_check_frequency_reason
string or null

Why effective_check_frequency differs from check_frequency: slowed_down while we temporarily check less often after repeated 429 responses or timeouts, plan_minimum when your plan's shortest check frequency is longer, or request_timeout when the timeout is longer. null when both are the same.

attributes.request_headers
array

Custom HTTP headers we send with the check.

attributes.request_headers[].id
string

The ID of the header. Send it on update to change or remove this header.

attributes.request_headers[].name
string

The name of the header, like Content-Type.

attributes.request_headers[].value
string

The value of the header, like application/json.

attributes.request_body
string or null

The body of the request. For dns monitors, the domain to query.

attributes.auth_username
string or null

The basic HTTP authentication username.

attributes.auth_password
string or null

The basic HTTP authentication password.

attributes.follow_redirects
boolean

Whether we follow redirects.

attributes.remember_cookies
boolean

Whether we keep cookies when following redirects.

attributes.paused
boolean

Whether the monitor is paused.

attributes.paused_at
string or null

When the monitor was paused, in ISO 8601 format, or null when it isn't paused.

attributes.created_at
string

When the monitor was created, in ISO 8601 format.

attributes.updated_at
string

When the monitor was last updated, in ISO 8601 format.

attributes.ssl_expiration
integer or null

How many days before the SSL certificate expires we alert you: 1, 2, 3, 7, 14, 30, or 60. null means we don't check it.

attributes.domain_expiration
integer or null

How many days before the domain expires we alert you: 1, 2, 3, 7, 14, 30, or 60. null means we don't check it.

attributes.regions
array

The regions we check from, any of us, eu, as, au. Lists every region when none were set.

attributes.port
string or null

The port for tcp, udp, smtp, pop, and imap monitors. Several ports are separated by commas, like 25,465,587.

attributes.confirmation_period
integer

How long we wait after observing a failure before we start an incident, in seconds.

attributes.expected_status_codes
array

The HTTP status codes that count as up for expected_status_code monitors.

attributes.maintenance_from
string or null

Start of the daily maintenance window when we don't check, like 01:00:00, or null when no window is set.

attributes.maintenance_to
string or null

End of the daily maintenance window, like 03:00:00, or null when no window is set.

attributes.maintenance_timezone
string or null

The time zone of the maintenance window, as a Rails time zone name like Amsterdam. null means UTC.

attributes.maintenance_days
array

The days the maintenance window applies to, any of mon, tue, wed, thu, fri, sat, sun. Lists every day when none were set.

attributes.environment_variables
object

The environment variables of a playwright scenario, as name and value pairs.

attributes.playwright_script
string or null

The JavaScript source code of the scenario for playwright monitors.

attributes.scenario_name
string

The scenario name identifying the monitor in the UI. Returned only for playwright monitors.

attributes.proxy_host
string or null

The host of the proxy server we send the check through, which can include credentials like user:pass@proxy.example.com.

attributes.proxy_port
integer or null

The port of the proxy server.

attributes.ip_version
string or null

ipv4 or ipv6 when we use only that IP version, or null when we use both.

attributes.checks_version
string

Always v2. Kept for backward compatibility.

relationships.policy.data
object or null

The escalation policy of the monitor as id and type, where type is policy, or null when none is set.

relationships.expiration_policy.data
object or null

The escalation policy for SSL certificate and domain expiration alerts as id and type, where type is policy, or null when none is set.

pagination.first
string

The URL of the first page. Read more about pagination.

pagination.last
string

The URL of the last page.

pagination.prev
string or null

The URL of the previous page, or null on the first page.

pagination.next
string or null

The URL of the next page, or null on the last page.


Example cURL

List all Filter by URL 
curl --request GET \
  --url "https://incidents.betterstack.com/api/v2/monitors" \
  --header "Authorization: Bearer $TOKEN"
curl --request GET \
  --url "https://incidents.betterstack.com/api/v2/monitors?url=https://google.com" \
  --header "Authorization: Bearer $TOKEN"


Previous article

Pagination

Next article

Get monitor