List

List the schedule entries for a schedule over a window of time.

Use this endpoint to find out who is on-call for a schedule, either right now or at any point in the future. Common uses include:

Building a calendar or timeline view of who is on-call.
Looking up who was on-call at a particular moment (for example, when an incident fired).
Exporting upcoming shifts into another system, such as a payroll or scheduling tool.

The response groups entries into three lists: scheduled (the entries the rotation rules produce, before any overrides), overrides (any one-off overrides that apply in the window) and final (the effective schedule after overrides have been merged in — this is normally the list you want).

Each entry includes the rotation_id and layer_id it belongs to. Schedules can be made up of multiple rotations (for example, a primary and a secondary rotation) and each rotation can have several layers, and we return entries for every rotation and layer on the schedule.

The endpoint returns all entries that overlap with the given window. If no window is provided we default to a sensible range starting from now.

Pagination

Responses are paginated. When more entries are available than fit on a single page, the response includes a pagination_meta block with two fields:

after_url — a fully-formed URL for the next page. The simplest way to paginate is to keep following this URL until it is no longer present.
after — an opaque cursor token. To fetch the next page manually, re-issue the request with entry_window_start set to this value and entry_window_end left unchanged from the original request. Treat the token as opaque — do not parse or modify it.

Keep paginating until pagination_meta is absent from the response, at which point you have received every entry in the window.

GET

schedule_entries

List

curl --request GET \
  --url https://api.incident.io/v2/schedule_entries \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.incident.io/v2/schedule_entries"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.incident.io/v2/schedule_entries', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.incident.io/v2/schedule_entries",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.incident.io/v2/schedule_entries"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.incident.io/v2/schedule_entries")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.incident.io/v2/schedule_entries")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "pagination_meta": {
    "after": "abc123",
    "after_url": "abc123"
  },
  "schedule_entries": {
    "final": [
      {
        "end_at": "2021-08-17T13:28:57.801578Z",
        "entry_id": "01G0J1EXE7AXZ2C93K61WBPYEH",
        "fingerprint": "01G0J1EXE7AXZ2C93K61WBPYEH",
        "layer_id": "01G0J1EXE7AXZ2C93K61WBPYNH",
        "rotation_id": "01G0J1EXE7AXZ2C93K61WBPYEH",
        "start_at": "2021-08-17T13:28:57.801578Z",
        "user": {
          "email": "lisa@incident.io",
          "id": "01FCNDV6P870EA6S7TK1DSYDG0",
          "name": "Lisa Karlin Curtis",
          "role": "owner",
          "slack_user_id": "U02AYNF2XJM"
        }
      }
    ],
    "overrides": [
      {
        "end_at": "2021-08-17T13:28:57.801578Z",
        "entry_id": "01G0J1EXE7AXZ2C93K61WBPYEH",
        "fingerprint": "01G0J1EXE7AXZ2C93K61WBPYEH",
        "layer_id": "01G0J1EXE7AXZ2C93K61WBPYNH",
        "rotation_id": "01G0J1EXE7AXZ2C93K61WBPYEH",
        "start_at": "2021-08-17T13:28:57.801578Z",
        "user": {
          "email": "lisa@incident.io",
          "id": "01FCNDV6P870EA6S7TK1DSYDG0",
          "name": "Lisa Karlin Curtis",
          "role": "owner",
          "slack_user_id": "U02AYNF2XJM"
        }
      }
    ],
    "scheduled": [
      {
        "end_at": "2021-08-17T13:28:57.801578Z",
        "entry_id": "01G0J1EXE7AXZ2C93K61WBPYEH",
        "fingerprint": "01G0J1EXE7AXZ2C93K61WBPYEH",
        "layer_id": "01G0J1EXE7AXZ2C93K61WBPYNH",
        "rotation_id": "01G0J1EXE7AXZ2C93K61WBPYEH",
        "start_at": "2021-08-17T13:28:57.801578Z",
        "user": {
          "email": "lisa@incident.io",
          "id": "01FCNDV6P870EA6S7TK1DSYDG0",
          "name": "Lisa Karlin Curtis",
          "role": "owner",
          "slack_user_id": "U02AYNF2XJM"
        }
      }
    ]
  }
}

🔑 Requires the schedules.view scope.

Authorizations

Authorization

string

header

required

API key from your incident.io dashboard (Settings → API keys)

Query Parameters

schedule_id

string

required

The ID of the schedule to get entries for.

Example:

"01FDAG4SAP5TYPT98WGR2N7W91"

entry_window_start

string

The start of the window to get entries for. May also carry an opaque pagination cursor previously returned in pagination_meta.after — pass it back here unchanged to fetch the next page (leave entry_window_end unchanged from the original request).

Example:

"2021-01-01T00:00:00Z"

entry_window_end

string<date-time>

The end of the window to get entries for.

Example:

"2021-01-01T00:00:00Z"

Response

200 - application/json

OK response.

schedule_entries

object

required

The schedule entries for a window of time, grouped by where they come from.

scheduled are the entries produced by the schedule's rotation rules before any overrides are taken into account. overrides are the one-off changes that apply within the window. final is the effective schedule after overrides have been merged in — this is normally the list to use when working out who is on-call.

Show child attributes

Example:

{
  "final": [
    {
      "end_at": "2021-08-17T13:28:57.801578Z",
      "entry_id": "01G0J1EXE7AXZ2C93K61WBPYEH",
      "fingerprint": "01G0J1EXE7AXZ2C93K61WBPYEH",
      "layer_id": "01G0J1EXE7AXZ2C93K61WBPYNH",
      "rotation_id": "01G0J1EXE7AXZ2C93K61WBPYEH",
      "start_at": "2021-08-17T13:28:57.801578Z",
      "user": {
        "email": "lisa@incident.io",
        "id": "01FCNDV6P870EA6S7TK1DSYDG0",
        "name": "Lisa Karlin Curtis",
        "role": "owner",
        "slack_user_id": "U02AYNF2XJM"
      }
    }
  ],
  "overrides": [
    {
      "end_at": "2021-08-17T13:28:57.801578Z",
      "entry_id": "01G0J1EXE7AXZ2C93K61WBPYEH",
      "fingerprint": "01G0J1EXE7AXZ2C93K61WBPYEH",
      "layer_id": "01G0J1EXE7AXZ2C93K61WBPYNH",
      "rotation_id": "01G0J1EXE7AXZ2C93K61WBPYEH",
      "start_at": "2021-08-17T13:28:57.801578Z",
      "user": {
        "email": "lisa@incident.io",
        "id": "01FCNDV6P870EA6S7TK1DSYDG0",
        "name": "Lisa Karlin Curtis",
        "role": "owner",
        "slack_user_id": "U02AYNF2XJM"
      }
    }
  ],
  "scheduled": [
    {
      "end_at": "2021-08-17T13:28:57.801578Z",
      "entry_id": "01G0J1EXE7AXZ2C93K61WBPYEH",
      "fingerprint": "01G0J1EXE7AXZ2C93K61WBPYEH",
      "layer_id": "01G0J1EXE7AXZ2C93K61WBPYNH",
      "rotation_id": "01G0J1EXE7AXZ2C93K61WBPYEH",
      "start_at": "2021-08-17T13:28:57.801578Z",
      "user": {
        "email": "lisa@incident.io",
        "id": "01FCNDV6P870EA6S7TK1DSYDG0",
        "name": "Lisa Karlin Curtis",
        "role": "owner",
        "slack_user_id": "U02AYNF2XJM"
      }
    }
  ]
}

pagination_meta

object

Show child attributes

Example:

{ "after": "abc123", "after_url": "abc123" }

Schedule Entries

Preview

⌘I

List

curl --request GET \
  --url https://api.incident.io/v2/schedule_entries \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.incident.io/v2/schedule_entries"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.incident.io/v2/schedule_entries', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.incident.io/v2/schedule_entries",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.incident.io/v2/schedule_entries"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.incident.io/v2/schedule_entries")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.incident.io/v2/schedule_entries")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "pagination_meta": {
    "after": "abc123",
    "after_url": "abc123"
  },
  "schedule_entries": {
    "final": [
      {
        "end_at": "2021-08-17T13:28:57.801578Z",
        "entry_id": "01G0J1EXE7AXZ2C93K61WBPYEH",
        "fingerprint": "01G0J1EXE7AXZ2C93K61WBPYEH",
        "layer_id": "01G0J1EXE7AXZ2C93K61WBPYNH",
        "rotation_id": "01G0J1EXE7AXZ2C93K61WBPYEH",
        "start_at": "2021-08-17T13:28:57.801578Z",
        "user": {
          "email": "lisa@incident.io",
          "id": "01FCNDV6P870EA6S7TK1DSYDG0",
          "name": "Lisa Karlin Curtis",
          "role": "owner",
          "slack_user_id": "U02AYNF2XJM"
        }
      }
    ],
    "overrides": [
      {
        "end_at": "2021-08-17T13:28:57.801578Z",
        "entry_id": "01G0J1EXE7AXZ2C93K61WBPYEH",
        "fingerprint": "01G0J1EXE7AXZ2C93K61WBPYEH",
        "layer_id": "01G0J1EXE7AXZ2C93K61WBPYNH",
        "rotation_id": "01G0J1EXE7AXZ2C93K61WBPYEH",
        "start_at": "2021-08-17T13:28:57.801578Z",
        "user": {
          "email": "lisa@incident.io",
          "id": "01FCNDV6P870EA6S7TK1DSYDG0",
          "name": "Lisa Karlin Curtis",
          "role": "owner",
          "slack_user_id": "U02AYNF2XJM"
        }
      }
    ],
    "scheduled": [
      {
        "end_at": "2021-08-17T13:28:57.801578Z",
        "entry_id": "01G0J1EXE7AXZ2C93K61WBPYEH",
        "fingerprint": "01G0J1EXE7AXZ2C93K61WBPYEH",
        "layer_id": "01G0J1EXE7AXZ2C93K61WBPYNH",
        "rotation_id": "01G0J1EXE7AXZ2C93K61WBPYEH",
        "start_at": "2021-08-17T13:28:57.801578Z",
        "user": {
          "email": "lisa@incident.io",
          "id": "01FCNDV6P870EA6S7TK1DSYDG0",
          "name": "Lisa Karlin Curtis",
          "role": "owner",
          "slack_user_id": "U02AYNF2XJM"
        }
      }
    ]
  }
}