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 /v2/schedule_entries

List

cURL

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

200

{
  "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": "[e-mail]",
          "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": "[e-mail]",
          "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": "[e-mail]",
          "id": "01FCNDV6P870EA6S7TK1DSYDG0",
          "name": "Lisa Karlin Curtis",
          "role": "owner",
          "slack_user_id": "U02AYNF2XJM"
        }
      }
    ]
  }
}

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": "[e-mail]",
        "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": "[e-mail]",
        "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": "[e-mail]",
        "id": "01FCNDV6P870EA6S7TK1DSYDG0",
        "name": "Lisa Karlin Curtis",
        "role": "owner",
        "slack_user_id": "U02AYNF2XJM"
      }
    }
  ]
}

pagination_meta · object

Show child attributes

Example:

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