Better Uptime
Better Uptime
What is Better Uptime?
FAQ
System Status
Getting started
Frequently Asked Questions
📟 Features
Monitors
On-call rotation schedules
Incidents
Heartbeats
Status pages
Teams
🔧 API
Getting started
Monitors API
Escalation Policies API
Monitor Groups API
Heartbeats API
Heartbeat Groups API
Incidents API
Status Pages API
Status Pages Sections API
Status Page Resources API
Metadata API
⚙️ Integrations
Slack
Zapier
Microsoft Teams
Webhooks
Google Cloud
AWS
New Relic
Prometheus
Zabbix
Grafana
Datadog
Powered by GitBook

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 3 months ago
Contents
Obtaining an API token
get
Listing all existing heartbeats
get
Getting a single heartbeat
post
Creating a heartbeat
patch
Updating an existing endpoint
delete
Deleting an existing heartbeat