# On-call

An **on-call schedule** decides which team member is on call at each moment. A schedule has rotation layers that hand off between members, overrides for swaps and holidays, and cover requests when someone cannot do a shift. A **Notify on-call** step in an [escalation path](/alerting/escalation-paths) pages whoever is on call when the step runs. On-call schedules are part of the Team and Business plans.

## Create a schedule

1. In the dashboard, select **Alerting → On-call**.
2. Select **New schedule**.
3. Enter a **Name**, for example `Platform on-call`. The **Description** is optional.
4. Select the **Time zone**. Handoffs and set hours use this time zone.
5. Select **Create schedule**.

A new schedule has nobody on call. Add a rotation next.

## Add a rotation

A **rotation** is a layer of the schedule. It hands off between its participants in order, at a fixed interval.

1. Open the schedule.
2. Select **Add rotation**.
3. Enter a **Name**, for example `Primary`.
4. Under **Participants**, add team members in the order of their turns.
5. Under **Hand off every**, enter a number and select **Hours**, **Days** or **Weeks**.
6. Enter the date of the **First handoff** and the **Handoff time**.
7. Select **Add rotation**.

The first participant's turn starts at the first handoff. After each interval, the next participant takes over. After the last participant, the first one starts again.

| Setting | API field | Values |
|---|---|---|
| **Participants** | `participants` | 1 to 50 team members, in order |
| **Hand off every** | `shift_length`, `shift_unit` | 1 to 720 `hours`, 1 to 90 `days`, or 1 to 12 `weeks` |
| **First handoff** | `start_date` | A date, `YYYY-MM-DD`, in the schedule's time zone |
| **Handoff time** | `handoff_time` | A time, `HH:MM`, in the schedule's time zone |
| **Only cover set hours** | `restrictions` | Optional days and a time window, see below |

`days` and `weeks` follow the calendar in the schedule's time zone. The handoff stays at the same clock time when daylight saving time starts or ends. `hours` are exact hours, so a 12-hour shift is always 12 hours long.

### Cover set hours only

Select **Only cover set hours** to limit a rotation to some days and times, for example weekdays from 09:00 to 17:00. Outside these hours, the layers below take over, or nobody is on call. If **Until** is earlier than **From**, the window runs overnight.

## Layers

A schedule can have more than one rotation. The dashboard shows them under **Rotation layers**. Where layers overlap, the top layer wins. Use this to combine a business-hours rotation on top of a round-the-clock rotation.

You can change the order of the layers. Spectate skips a participant who is no longer a member of the team.

## Add an override

An **override** puts one member on call for a period, over all layers. Use it for swaps, sick days and holidays.

1. Open the schedule.
2. Select **Override**.
3. Under **Who covers**, select the team member.
4. Enter **From** and **Until** in the schedule's time zone.
5. Optional: enter a **Note**, for example `Swapping with Bob for the release`.
6. Select **Add override**.

An override is at most 90 days long. Where overrides overlap, the newest override wins. The **Overrides** panel shows upcoming and active overrides.

## Ask for cover

A **cover request** asks the other members of a schedule to take a shift of yours. The first member to accept gets an override for the whole window. Nothing changes on the schedule until someone accepts.

1. Select **Alerting → On-call**.
2. Under **Your on-call**, select **Request cover** next to the shift.
3. Change **From** and **Until** if you need cover for part of the shift only.
4. Optional: enter a **Note**, for example the reason.
5. Select **Ask for cover**.

In Slack, use `/spectate cover`. See [cover requests in Slack](/alerting/slack#cover-requests).

Spectate asks every other member of the schedule's rotations. If the team [connected Slack](/alerting/slack) and Spectate finds the member in Slack, the member gets a direct message with **Accept** and **Can't cover**. Other members get an email. They answer under **Your on-call**, or on the schedule page under **Waiting for cover**.

These rules apply:

- You must be on call for all of the window. A window that already started covers the rest of it.
- A window is at most 90 days long. You can have one open request for the same time.
- Any member of the team can accept, also a member that Spectate did not ask. You cannot accept your own request.
- If someone accepts, Spectate tells you. If everyone says they cannot, Spectate tells you too, and the request stays open. A member who said no can still accept.
- **Send reminder** asks again the members who did not answer, at most every 30 minutes.
- If nobody accepts before the window ends, the request expires. You stay on call.
- You can cancel your own request. Owners, managers and admins can cancel any request.

The public API and the MCP server do not have cover requests yet.

## See who is on call

The schedule page shows **On call now**, the **Next handoff** and a **Timeline** of 1 week or 2 weeks. The timeline has a row for each layer, a row for overrides, and the **Final schedule** row. The **Final schedule** is who Spectate pages.

The **On-call** page lists all schedules with the person on call now. **Your on-call** shows your own shifts for the next 14 days.

With the [public API](/api-reference/on-call), `GET /v1/on-call-schedules/{schedule}/now` returns who is on call, and `GET /v1/on-call-schedules/{schedule}/timeline` returns the shifts for a period.

## Page the person on call

1. Open an [escalation path](/alerting/escalation-paths).
2. Add a **Notify on-call** step.
3. Under **Schedule**, select the on-call schedule.
4. Select **Save flow**.

Spectate finds the person on call when the step runs, not when the alert fires. If nobody is on call, Spectate skips the step and runs the next step at once. The alert's **Escalation** panel shows who Spectate paged, or why it skipped the step.

The schedule page shows the escalation paths that use the schedule under **Used by**.

### How Spectate pages a member

Spectate always sends an email to the member on call. If the team [connected Slack](/alerting/slack), Spectate also sends the alert as a direct message in Slack, with **Acknowledge** and **Resolve**. Slack pages do not use credits. To turn them off, clear **Also page me in Slack** under **On-call contact**.

Spectate also sends an SMS or calls the member if these are true:

- The member added a phone number under **On-call contact**.
- The team has [SMS and call credits](/alerting/channels#sms-and-call-credits).

Each member sets this in **Account → Profile → On-call contact**, or under **Your on-call** on the **On-call** page:

| **Page me by** | What happens | Credits |
|---|---|---|
| **Text** | Spectate sends the alert by SMS. Acknowledge it in Spectate to stop the escalation. | 1 |
| **Voice call** | Spectate calls and reads the alert. Press 1 to acknowledge it as you and stop the escalation. | 2 |

When the alert resolves, Spectate sends the paged member an email only, and updates the Slack message. See [Telegram and phone](/alerting/telegram-and-phone) for the voice call.

## Shifts in Slack

If the team connected Slack, Spectate sends each member a reminder before a shift, and a message when the shift starts and ends. The reminder has a **Request cover** button. Each member chooses with **Shift messages in Slack** under **On-call contact**:

| Choice | Messages |
|---|---|
| **Off** | None |
| **When a shift starts and ends** | At the start and at the end |
| **Also 15 minutes before** | A reminder 15 minutes before, then at the start and at the end |
| **Also 1 hour before** (default) | A reminder 1 hour before, then at the start and at the end |
| **Also 1 day before** | A reminder 1 day before, then at the start and at the end |

On the schedule page, the **Slack** panel has two more options:

- **Handover channel** announces each handover in a Slack channel.
- **Keep an on-call user group** creates a Slack user group, for example `@platform-oncall`. Spectate keeps it set to whoever is on call, or to everyone on the schedule.

See [on-call in Slack](/alerting/slack#on-call-in-slack).

## Who can do what

| Action | Owner, manager, admin | Member |
|---|---|---|
| See schedules | Yes | Yes |
| Create and change schedules and rotations | Yes | No |
| Delete schedules | Yes | No |
| Add an override | For any member | For themselves only |
| Remove an override | Any override | Overrides for themselves, or that they added |
| Ask for cover of their own shift | Yes | Yes |
| Accept a cover request | Yes, not their own | Yes, not their own |
| Cancel a cover request | Any request | Their own requests |
| Change the schedule's **Slack** settings | Yes | No |

## Plans

On-call schedules and **Notify on-call** steps are part of the Team and Business plans, and of the trial. The Starter plan does not include them. See [plans and billing](/account/plans-and-billing) and [pricing](https://spectate.net/pricing).