Preview

Preview the schedule entries that would be generated by a proposed schedule configuration.

Use this endpoint before updating a schedule to see who would be on-call if you saved the supplied schedule payload. The request body uses the same schedule payload shape as Update schedule, so you can send the configuration you intend to save without persisting it.

The response uses the same schedule_entries envelope as List schedule entries: scheduled contains entries produced by the rotation rules, overrides contains matching overrides, and final contains the effective schedule after overrides are applied.

The preview window is bounded to keep requests predictable. If you ask for more than 91 days, the response is capped to 91 days from entry_window_start.

POST

schedules

{id}

actions

preview_entries

Preview

curl --request POST \
  --url https://api.incident.io/v2/schedules/{id}/actions/preview_entries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entry_window_end": "2021-01-08T00:00:00Z",
  "entry_window_start": "2021-01-01T00:00:00Z",
  "schedule": {
    "annotations": {
      "incident.io/terraform/version": "version-of-terraform"
    },
    "config": {
      "rotations": [
        {
          "effective_from": "2021-08-17T13:28:57.801578Z",
          "handover_start_at": "2021-08-17T13:28:57.801578Z",
          "handovers": [
            {
              "interval": 1,
              "interval_type": "hourly"
            }
          ],
          "id": "01G0J1EXE7AXZ2C93K61WBPYEH",
          "layers": [
            {
              "id": "01G0J1EXE7AXZ2C93K61WBPYEH",
              "name": "Layer 1"
            }
          ],
          "name": "My Rotation",
          "scheduling_mode": "fair",
          "users": [
            {
              "email": "bob@example.com",
              "id": "01G0J1EXE7AXZ2C93K61WBPYEH",
              "slack_user_id": "USER123"
            }
          ],
          "working_interval": [
            {
              "end_time": "17:00",
              "start_time": "09:00",
              "weekday": "monday"
            }
          ],
          "working_intervals": [
            {
              "end_time": "17:00",
              "start_time": "09:00",
              "weekday": "monday"
            }
          ]
        }
      ]
    },
    "holidays_public_config": {
      "country_codes": [
        "abc123"
      ]
    },
    "name": "Primary On-call Schedule",
    "team_ids": [
      "01JPQA75EPNEES4479P16P4XAB"
    ],
    "timezone": "America/Los_Angeles"
  }
}
'

{
  "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"
        }
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

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

Path Parameters

string

required

The ID of the schedule to preview entries for.

Example:

"01FDAG4SAP5TYPT98WGR2N7W91"

Body

application/json

schedule

object

required

Show child attributes

Example:

{
  "annotations": {
    "incident.io/terraform/version": "version-of-terraform"
  },
  "config": {
    "rotations": [
      {
        "effective_from": "2021-08-17T13:28:57.801578Z",
        "handover_start_at": "2021-08-17T13:28:57.801578Z",
        "handovers": [
          { "interval": 1, "interval_type": "hourly" }
        ],
        "id": "01G0J1EXE7AXZ2C93K61WBPYEH",
        "layers": [
          {
            "id": "01G0J1EXE7AXZ2C93K61WBPYEH",
            "name": "Layer 1"
          }
        ],
        "name": "My Rotation",
        "scheduling_mode": "fair",
        "users": [
          {
            "email": "bob@example.com",
            "id": "01G0J1EXE7AXZ2C93K61WBPYEH",
            "slack_user_id": "USER123"
          }
        ],
        "working_interval": [
          {
            "end_time": "17:00",
            "start_time": "09:00",
            "weekday": "monday"
          }
        ],
        "working_intervals": [
          {
            "end_time": "17:00",
            "start_time": "09:00",
            "weekday": "monday"
          }
        ]
      }
    ]
  },
  "holidays_public_config": { "country_codes": ["abc123"] },
  "name": "Primary On-call Schedule",
  "team_ids": ["01JPQA75EPNEES4479P16P4XAB"],
  "timezone": "America/Los_Angeles"
}

entry_window_end

string<date-time>

The end of the window to preview entries for. Defaults to four weeks after entry_window_start.

Example:

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

entry_window_start

string<date-time>

The start of the window to preview entries for. Defaults to now.

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"
      }
    }
  ]
}

List

Schedule Overrides

⌘I

Preview

curl --request POST \
  --url https://api.incident.io/v2/schedules/{id}/actions/preview_entries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entry_window_end": "2021-01-08T00:00:00Z",
  "entry_window_start": "2021-01-01T00:00:00Z",
  "schedule": {
    "annotations": {
      "incident.io/terraform/version": "version-of-terraform"
    },
    "config": {
      "rotations": [
        {
          "effective_from": "2021-08-17T13:28:57.801578Z",
          "handover_start_at": "2021-08-17T13:28:57.801578Z",
          "handovers": [
            {
              "interval": 1,
              "interval_type": "hourly"
            }
          ],
          "id": "01G0J1EXE7AXZ2C93K61WBPYEH",
          "layers": [
            {
              "id": "01G0J1EXE7AXZ2C93K61WBPYEH",
              "name": "Layer 1"
            }
          ],
          "name": "My Rotation",
          "scheduling_mode": "fair",
          "users": [
            {
              "email": "bob@example.com",
              "id": "01G0J1EXE7AXZ2C93K61WBPYEH",
              "slack_user_id": "USER123"
            }
          ],
          "working_interval": [
            {
              "end_time": "17:00",
              "start_time": "09:00",
              "weekday": "monday"
            }
          ],
          "working_intervals": [
            {
              "end_time": "17:00",
              "start_time": "09:00",
              "weekday": "monday"
            }
          ]
        }
      ]
    },
    "holidays_public_config": {
      "country_codes": [
        "abc123"
      ]
    },
    "name": "Primary On-call Schedule",
    "team_ids": [
      "01JPQA75EPNEES4479P16P4XAB"
    ],
    "timezone": "America/Los_Angeles"
  }
}
'

{
  "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"
        }
      }
    ]
  }
}