Get monitor

GET https://incidents.betterstack.com/api/v2/monitors/{monitor_id}

URL parameters

monitor_id

required string

The ID of the monitor you want to get

Headers

Authorization

required string

Bearer $TOKEN

200

Returns a single monitor.

Response body

{
  "data": {
    "id": "123456789",
    "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
      }
    }
  }
}

404

Response body

{
  "errors": "Resource with provided ID was not found"
}

Response attributes

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.

Explore documentation

Example cURL

Explore documentation

Get monitor

Example cURL

Please accept cookies