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. Post mortems
    3. Metadata & Catalog
    4. Screening alerts
    5. 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
    5. On-call & incidents
      1. On-call schedule
        1. List on-call schedules GET
        2. Get on-call schedule GET
        3. Create on-call schedule POST
        4. Update on-call schedule PATCH
        5. Remove on-call schedule DELETE
      2. On-call schedule events
      3. On-call schedule rotations
      4. Escalation policies
      5. Escalation policy groups
      6. Severities
      7. Severity groups
      8. Incidents
      9. Comments
    6. Status pages
    7. Metadata
    8. Integrations
    9. Team members
    10. Organization roles
    11. Usage
    12. Reporting

List on-call schedules

List all on-call schedules.

GET https://incidents.betterstack.com/api/v2/on-calls

Query parameters

team_name
string

Filter on-call schedules belonging to a specified team when using global API token.

page
integer

The page number to return, starting with 1.

per_page
integer

Number of results per page. Defaults to 50, maximum 250.

Headers

Authorization
required string

Bearer $TOKEN

200

Returns the list of existing on-call schedules including their current on-calls.

Response body

{
  "data": [
    {
      "id": "12345",
      "type": "on_call_calendar",
      "attributes": {
        "name": null,
        "default_calendar": true,
        "team_name": "Production"
      },
      "relationships": {
        "on_call_users": {
          "data": [
            {
              "id": "2345",
              "type": "user",
              "meta": {
                "email": "tomas@betterstack.com",
                "on_holiday": false,
                "holiday_ends_at": null
              }
            }
          ]
        }
      }
    },
    {
      "id": "12346",
      "type": "on_call_calendar",
      "attributes": {
        "name": "Tier 2",
        "default_calendar": false,
        "team_name": "Production"
      },
      "relationships": {
        "on_call_users": {
          "data": [
            {
              "id": "2345",
              "type": "user",
              "meta": {
                "email": "tomas@betterstack.com",
                "on_holiday": false,
                "holiday_ends_at": null
              }
            }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "id": "2345",
      "type": "user",
      "attributes": {
        "first_name": "Tomas",
        "last_name": "Hromada",
        "email": "tomas@betterstack.com",
        "phone_numbers": [
          "+420737123456"
        ]
      }
    }
  ],
  "pagination": {
    "first": "https://incidents.betterstack.com/api/v2/on-calls?page=1",
    "last": "https://incidents.betterstack.com/api/v2/on-calls?page=1",
    "prev": null,
    "next": null
  }
}

Response attributes

id
string

The ID of the on-call schedule.

type
string

Always on_call_calendar.

attributes.name
string or null

The name of the on-call schedule.

attributes.default_calendar
boolean

Whether this is the team's default on-call schedule.

attributes.team_name
string

The team the on-call schedule belongs to.

relationships.on_call_users.data
array

The people on call now.

relationships.on_call_users.data[].id
string

The ID of the on-call person.

relationships.on_call_users.data[].type
string

Always user.

relationships.on_call_users.data[].meta.email
string

The e-mail of the on-call person.

relationships.on_call_users.data[].meta.on_holiday
boolean

Whether the person is in holiday mode now. People on holiday stay listed, but we don't alert them until it ends.

relationships.on_call_users.data[].meta.holiday_ends_at
string or null

When their holiday ends, as an ISO 8601 date-time in UTC, like 2026-10-26T14:00:00Z. null when they aren't on holiday.

included
array

The on-call people, with their contact details.

included[].id
string

The ID of the on-call person.

included[].type
string

Always user.

included[].attributes.first_name
string or null

The person's first name.

included[].attributes.last_name
string or null

The person's last name.

included[].attributes.email
string

The person's e-mail.

included[].attributes.phone_numbers
array

The person's phone numbers, such as +420737123456.

pagination.first
string

The URL of the first page. Read more about pagination.

pagination.last
string

The URL of the last page.

pagination.prev
string or null

The URL of the previous page, or null on the first page.

pagination.next
string or null

The URL of the next page, or null on the last page.

Example cURL

Example
curl --request GET \
  --url "https://incidents.betterstack.com/api/v2/on-calls" \
  --header 'authorization: Bearer $TOKEN'


Previous article

Remove heartbeat group

Next article

Get on-call schedule