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

Update heartbeat

Update an existing heartbeat configuration. Send only the parameters you wish to change (e.g. name)

PATCH 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

Content-type
string

application/json

Body parameters

name
string

The name of the service for this heartbeat.

period
integer

How often we should expect this heartbeat, in seconds. Minimum value: 30 seconds, and it must be shorter than one year.

grace
integer

How late a heartbeat can arrive, in seconds, before we consider it missed. Minimum value: 0 seconds, and it must be shorter than one year. We recommend setting this to about 20% of period.

call
boolean

Should we call the on-call person?

sms
boolean

Should we send an SMS to the on-call person?

email
boolean

Should we send an e-mail to the on-call person?

push
boolean

Should we send a push notification to the on-call person?

critical_alert
boolean

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

team_wait
integer

How long to wait, in seconds, before escalating the incident to the whole team. Leave blank to disable escalating to the entire team.

heartbeat_group_id
string

Set this attribute if you want to add this heartbeat to a heartbeat group

sort_index
integer

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

maintenance_days
array of strings

An array of maintenance days to set. If a maintenance window is overnight both affected days should be set. Allowed values are ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun'] or any subset of these days.

maintenance_from
string

Start of the maintenance window each day. We won't check your website during this window. Example: '01:00'

maintenance_to
string

End of the maintenance window each day. Example: '03:00'

maintenance_timezone
string

The timezone to use for the maintenance window each day. Defaults to UTC. The accepted values can be found in the Rails TimeZone documentation. https://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html

paused
boolean

Set to true to pause monitoring — we won't notify you about downtime. Set to false to resume monitoring

server_timezone
string

Optional IANA timezone (e.g. Europe/Berlin) used for DST-aware missed-beat detection. Requires period >= 3600 (1 hour). Pass an empty string or null to clear

policy_id
string

Set the escalation policy for the monitor.

200

Response body

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

Example cURL

Example
curl --request PATCH \
  --url https://incidents.betterstack.com/api/v2/heartbeats/12345 \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Testing heartbeat, with an update"
}'


Previous article

Create a heartbeat

Next article

Remove heartbeat