List heartbeats in a group

GET https://incidents.betterstack.com/api/v2/heartbeat-groups/{heartbeat_group_id}/heartbeats

URL parameters

heartbeat_group_id

required string

The ID of the heartbeat group you want to get heartbeats from.

Query parameters

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 a paginated list of heartbeats in the specified group.

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": 9525,
        "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-10T14:40:23.436Z",
        "status": "up"
      },
      "relationships": {
        "policy": {
          "data": null
        }
      }
    }
  ],
  "pagination": {
    "first": "https://incidents.betterstack.com/api/v2/heartbeat-groups/9525/heartbeats?page=1",
    "last": "https://incidents.betterstack.com/api/v2/heartbeat-groups/9525/heartbeats?page=1",
    "prev": null,
    "next": null
  }
}

Response attributes

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.

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.

Explore documentation

Example cURL

Explore documentation

List heartbeats in a group

Example cURL

Please accept cookies