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
    4. Heartbeats
      1. Heartbeats API
        1. List heartbeats GET
        2. Get heartbeat GET
        3. Heartbeat availability GET
        4. Create heartbeat POST
        5. Update heartbeat PATCH
        6. Remove heartbeat DELETE
      2. Heartbeat groups API
    5. On-call & incidents
    6. Status pages
    7. Metadata
    8. Integrations
    9. Team members
    10. Organization roles
    11. Usage
    12. Reporting

Get a single heartbeat

Returns a single heartbeat by ID.

GET https://incidents.betterstack.com/api/v2/heartbeats/{heartbeat_id}

URL parameters

heartbeat_id
required string

The ID of your requested heartbeat

Headers

Authorization
required string

Bearer $TOKEN

200

Returns the requested heartbeat.

Response body

{
  "data": {
    "id": "12345",
    "type": "heartbeat",
    "attributes": {
      "url": "https://incidents.betterstack.com/api/v1/heartbeat/abcd1234abcd1234abcd1234",
      "name": "Testing heartbeat",
      "period": 10800,
      "grace": 300,
      "call": false,
      "sms": false,
      "email": true,
      "push": true,
      "critical_alert": false,
      "team_wait": 180,
      "heartbeat_group_id": null,
      "policy_id": null,
      "team_name": "Test team",
      "sort_index": null,
      "paused_at": null,
      "paused": false,
      "server_timezone": null,
      "maintenance_from": "01:02:00",
      "maintenance_to": "03:04:00",
      "maintenance_timezone": "Amsterdam",
      "maintenance_days": [
        "mon",
        "tue",
        "wed",
        "thu",
        "fri",
        "sat",
        "sun"
      ],
      "created_at": "2020-05-05T11:41:49.327Z",
      "updated_at": "2020-12-10T15:00:15.089Z",
      "status": "up"
    },
    "relationships": {
      "policy": {
        "data": null
      }
    }
  }
}

Response attributes

id
string

The ID of the heartbeat.

type
string

Always heartbeat.

attributes.url
string

The URL your service requests to report a heartbeat.

attributes.name
string

The name of the service for this heartbeat.

attributes.period
integer

How often we expect the heartbeat, in seconds.

attributes.grace
integer

How late a heartbeat can arrive before we consider it missed, in seconds.

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.heartbeat_group_id
integer or null

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

attributes.team_name
string

The team the heartbeat is in.

attributes.sort_index
integer or null

A sort value you can set through the API. The dashboard doesn't use it to order heartbeats.

attributes.paused
boolean

Whether the heartbeat is paused.

attributes.paused_at
string or null

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

attributes.status
string

paused when the heartbeat was paused, pending when it was just created and waits for the first request, maintenance when it's in its maintenance window, up when requests arrive on time, validating when requests arrive on time again and the incident waits to be resolved, or down when a request didn't arrive on time.

attributes.policy_id
string or null

The ID of the escalation policy for the heartbeat, or null when none is set.

attributes.server_timezone
string or null

The IANA time zone, like Europe/Berlin, used for DST-aware missed-beat detection. Only kept for a period of at least one hour.

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.created_at
string

When the heartbeat was created, in ISO 8601 format.

attributes.updated_at
string

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

relationships.policy.data
object or null

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

Example cURL

Example
curl --request GET \
  --url https://incidents.betterstack.com/api/v2/heartbeats/12345 \
  --header "Authorization: Bearer $TOKEN"


Previous article

List heartbeats

Next article

Get a heartbeat's availability summary