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

Get a heartbeat's availability summary

Returns availability summary for a specific heartbeat.

GET https://incidents.betterstack.com/api/v2/heartbeats/{heartbeat_id}/availability

URL parameters

heartbeat_id
required string

The ID of your requested heartbeat

Query parameters

from
string

Start date (e.g., 2021-01-26)

to
string

End date (e.g., 2021-01-27)

Headers

Authorization
required string

Bearer $TOKEN

200

Returns the availability summary since the heartbeat was created or for the specified date range.

Response body

{
  "data": {
    "id": "824910",
    "type": "heartbeat_availability",
    "attributes": {
      "availability": 99.98,
      "total_downtime": 335,
      "number_of_incidents": 5,
      "longest_incident": 194,
      "average_incident": 67
    }
  }
}
400

When the optional from and to dates are invalid (e.g., the start date is in the future or the end date is before the start date).

Response body

{
  "errors": "The data range is invalid. The date format could not be parsed, the start time is in the future, or the end time is before the start time."
}

Response attributes

id
string

The ID of the heartbeat.

type
string

Always heartbeat_availability.

attributes.availability
number

The share of time the heartbeat was up, as a percentage rounded to 4 decimal places.

attributes.total_downtime
integer

The total downtime, in seconds.

attributes.number_of_incidents
integer

The number of incidents.

attributes.longest_incident
integer

The duration of the longest incident, in seconds.

attributes.average_incident
integer

The average incident duration, in seconds.

Example cURL

Example
curl --request GET \
  --url https://incidents.betterstack.com/api/v2/heartbeats/123456789/availability?from=2021-01-26&to=2021-01-27 \
  --header "Authorization: Bearer $TOKEN"


Previous article

Get a single heartbeat

Next article

Create a heartbeat