Heartbeats API

Manage your heartbeats using simple HTTP API.
Do you need help with the integration? 
Let us know at [email protected].
Obtaining an API token
Please, see Obtaining an API token.
get
Listing all existing heartbeats
https://betteruptime.com/api/v2/heartbeats
Returns the list of your heartbeats.
Request
Response
Request
Headers
Authorization
required
string
Bearer YOUR_API_TOKEN
Response
200: OK
The status attribute can have one of the following values:
paused - the heartbeat was paused
pending - the heartbeat was just created and it's waiting for the first request
up - heartbeat received a request on time
down - heartbeat did not receive a request on time
{
  "data": [
    {
      "id": "12345",
      "type": "heartbeat",
      "attributes": {
        "url": "https://betteruptime.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,
        "sort_index": null,
        "paused_at": null,
        "created_at": "2020-05-05T11:41:49.327Z",
        "updated_at": "2020-12-10T14:40:23.436Z",
        "status": "up"
      }
    }
  ],
  "pagination": {
    "first": "https://betteruptime.com/api/v2/heartbeats?page=1",
    "last": "https://betteruptime.com/api/v2/heartbeats?page=1",
    "prev": null,
    "next": null
  }
}
Example cURL
Example cURL
curl --request GET \
  --url https://betteruptime.com/api/v2/heartbeats \
  --header 'Authorization: Bearer YOUR_API_TOKEN'
get
Getting a single heartbeat
https://betteruptime.com/api/v2/heartbeats/:heartbeat_id
Returns a single heartbeat.
Request
Response
Request
Path Parameters
heartbeat_id
required
string
The ID of your requested heartbeat
Headers
Authorization
required
string
Bearer YOUR_API_TOKEN
Response
200: OK
The requested heartbeat.

The status attribute can have one of the following values:
paused - the heartbeat was paused
pending - the heartbeat was just created and it's waiting for the first request
up - heartbeat received a request on time 
down - heartbeat did not receive a request on time
{
  "data": {
    "id": "12345",
    "type": "heartbeat",
    "attributes": {
      "url": "https://betteruptime.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,
      "sort_index": null,
      "paused_at": null,
      "created_at": "2020-05-05T11:41:49.327Z",
      "updated_at": "2020-12-10T15:00:15.089Z",
      "status": "up"
    }
  }
}
Example cURL
Example cURL
curl --request GET \
  --url https://betteruptime.com/api/v2/heartbeats/12345 \
  --header 'Authorization: Bearer YOUR_API_TOKEN'
post
Creating a heartbeat
https://betteruptime.com/api/v2/heartbeats
Returns a newly created heartbeat or validation errors.
Request
Response
Request
Headers
Authorization
required
string
Bearer YOUR_API_TOKEN
Content-Type
required
string
application/json
Form Data Parameters
name
required
string
A name of the service for this heartbeat.
period
required
integer
How often should we expect this heartbeat?
In seconds
Minimum value: 30 seconds
grace
required
integer
Heartbeats can fluctuate; specify this value to control what is still acceptable
Minimum value: 0 seconds
We recommend setting this to approx. 20% of period
call
optional
boolean
Should we call the on-call person?
sms
optional
boolean
Should we send an SMS to the on-call person?
email
optional
boolean
Should we send an email to the on-call person?
push
optional
boolean
Should we send a push notification to the on-call person?
team_wait
optional
integer
How long should we wait before escalating the incident alert to the team?
Leave blank to disable escalating to the entire team.
heartbeat_group_id
optional
string
Set this attribute if you want to add this heartbeat to a heartbeat group.
sort_index
optional
integer
An index controlling the position of a heartbeat in the heartbeat group.
paused
optional
boolean
Set to true to pause monitoring — we won't notify you about downtime.
Set to false to resume monitoring
Response
201: Created
Returns a newly created heartbeat
{
  "data": {
    "id": "12345",
    "type": "heartbeat",
    "attributes": {
      "url": "https://betteruptime.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,
      "sort_index": null,
      "paused_at": null,
      "created_at": "2020-05-05T11:41:49.327Z",
      "updated_at": "2020-12-10T15:00:15.089Z"
    }
  }
}
422: Unprocessable Entity
Validation failed
{
  "errors": {
    "name": [
      "Can't be blank."
    ]
  }
}
Example cURL
Example cURL
curl --request POST \
  --url https://betteruptime.com/api/v2/heartbeats \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
	"name": "Testing heartbeat",
	"period": 10800,
	"grace": 300
}'
patch
Updating an existing endpoint
https://betteruptime.com/api/v2/heartbeats/:heartbeat_id
Update an existing heartbeat configuration.
Send only the parameters you wish to change (e.g. name)
Request
Response
Request
Path Parameters
heartbeat_id
required
string
The ID of the heartbeat you want to update
Headers
Authorization
required
string
Bearer YOUR_API_TOKEN
Content-Type
required
string
application/json
Form Data Parameters
name
optional
string
A name of the service for this heartbeat.
period
optional
integer
How often should we expect this heartbeat?
In seconds
Minimum value: 30 seconds
grace
optional
integer
Heartbeats can fluctuate; specify this value to control what is still acceptable
Minimum value: 0 seconds
We recommend setting this to approx. 20% of period
call
optional
boolean
Should we call the on-call person?
sms
optional
boolean
Should we send an SMS to the on-call person?
email
optional
boolean
Should we send an email to the on-call person?
push
optional
boolean
Should we send a push notification to the on-call person?
team_wait
optional
integer
How long should we wait before escalating the incident alert to the team?
Leave blank to disable escalating to the entire team.
heartbeat_group_id
optional
string
Set this attribute if you want to add this heartbeat to a heartbeat group.
sort_index
optional
integer
An index controlling the position of a heartbeat in the heartbeat group.
paused
optional
boolean
Set to true to pause monitoring — we won't notify you about downtime.
Set to false to resume monitoring
Response
200: OK
{
  "data": {
    "id": "12345",
    "type": "heartbeat",
    "attributes": {
      "url": "https://betteruptime.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,
      "sort_index": null,
      "paused_at": null,
      "created_at": "2020-05-05T11:41:49.327Z",
      "updated_at": "2020-12-10T15:00:15.089Z"
    }
  }
}
Example cURL
Example cURL
curl --request PATCH \
  --url https://betteruptime.com/api/v2/heartbeats/12345 \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
	"name": "Testing heartbeat, with an update"
}'
delete
Deleting an existing heartbeat
https://betteruptime.com/api/v2/heartbeats/:heartbeat_id
Request
Response
Request
Path Parameters
heartbeat_id
required
string
The ID of the heartbeat you want to delete
Headers
Authorization
required
string
Bearer YOUR_API_TOKEN
Response
204: No Content
No content
​
Example cURL
Example cURL
curl --request DELETE \
  --url https://betteruptime.com/api/v2/heartbeats/12345 \
  --header 'Authorization: Bearer YOUR_API_TOKEN'
🔧 API - Previous
Monitor Groups API
Next - 🔧 API
Heartbeat Groups API
Last updated 4 weeks ago
Heartbeats API

Do you need help with the integration?

Obtaining an API token

getListing all existing heartbeats

getGetting a single heartbeat

postCreating a heartbeat

patchUpdating an existing endpoint

deleteDeleting an existing heartbeat

get
Listing all existing heartbeats

get
Getting a single heartbeat

post
Creating a heartbeat

patch
Updating an existing endpoint

delete
Deleting an existing heartbeat
