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

Create a heartbeat

Returns either a newly created heartbeat, or validation errors.

POST https://incidents.betterstack.com/api/v2/heartbeats

Headers

Authorization
required string

Bearer $TOKEN

Content-type
string

application/json

Body parameters

team_name
string

Required if using global API token to specify the team which should own the resource

name
required string

The name of the service for this heartbeat.

period
required integer

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

grace
required 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? Defaults to false.

sms
boolean

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

email
boolean

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

push
boolean

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

critical_alert
boolean

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

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
integer

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.

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)

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. Defaults to every day.

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

policy_id
integer

Set the escalation policy for the monitor.

metadata
object

An object with metadata keys as the object keys and either a single metadata value or an array of metadata values as the object values. Each value is a plain string or an object with the attributes described in creating a metadata record. All values under one key must be of the same type and must not repeat. The metadata attribute can only be set when creating the heartbeat, and existing metadata is changed through the metadata API.

201

Returns a newly created 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,
      "team_wait": 180,
      "heartbeat_group_id": null,
      "team_name": "Test team",
      "sort_index": null,
      "paused_at": null,
      "server_timezone": null,
      "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"
    }
  }
}
422

Validation failed

Response body

{
  "errors": {
    "name": [
      "Can't be blank."
    ]
  }
}

Example cURL

Example Example with metadata 
curl --request POST \
  --url https://incidents.betterstack.com/api/v2/heartbeats \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
	"name": "Testing heartbeat",
	"period": 10800,
	"grace": 300
}'
curl --request POST \
  --url https://incidents.betterstack.com/api/v2/heartbeats \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
	"name": "Testing heartbeat",
	"period": 10800,
	"grace": 300,
	"metadata": {
	  "Environment": { "value": "production" },
	  "Owner": [
	    {
	      "type": "Team",
	      "name": "Platform"
	    }
	  ]
	}
}'


Previous article

Get a heartbeat's availability summary

Next article

Update heartbeat