---
title: On-call
description: "Schedules with layered rotations and overrides, escalation policies, and pages that tell the right person through the bell, a webhook, Slack, SMS and a phone call, and escalate until someone acknowledges."
section: incidents
order: 16
audience: [user, operator, agent]
sources: [services/nodejs-cloud/lib/incidents/oncall.ts, services/nodejs-cloud/components/incidents/oncall-model.ts, services/nodejs-cloud/lib/incidents/oncall-service.ts, services/nodejs-cloud/lib/incidents/oncall-http.ts, services/nodejs-cloud/lib/incidents/paging.ts, services/nodejs-cloud/components/incidents/OnCall.tsx, services/nodejs-cloud/migrations/0160_oncall.sql, docs/adr/0055-venom-incidents.md]
features: []
---

**On-call** in the Incidents sidebar (`/incidents/oncall`) answers three questions: who is on call now, what is paging
them, and what happens if they do not answer. Everyone in the org can read it. Acknowledging a page and covering a shift
need the write role; schedules, policies and alert sources need an owner or admin.

## Schedules

A schedule is a name, a time zone and one or more **rotations** (layers).

- A rotation is an ordered list of members that take turns. A shift is a number of **calendar days** (7 by default), handed
  over at the same **local time** (9:00 by default) from a start date. Because it counts calendar days and not 24-hour
  blocks, the handoff stays at 9:00 across a daylight saving change; that week's shift is 167 or 169 hours long. A handoff
  time that does not exist that day (02:30 on the spring-forward date) happens after the gap, and one that exists twice
  happens the first time.
- **A team's members.** Instead of picking people, a rotation can be "members of team X" (an
  [org team](/docs/cloud/teams), inherited members included). The turns go in the order people joined the team, and
  someone who joins goes to the end of the line; someone who leaves drops out. The schedule follows the team without being
  saved again. Agents in the team are left out, since they can't be paged. Over MCP and REST, a rotation takes
  `team: "<team id>"` instead of `members`.
- **Layers.** The highest layer that covers a moment decides who is on call. A rotation can be restricted to some weekdays
  and hours (a business-hours layer over a nights-and-weekends one, or a Friday night window that runs past midnight); the
  layer below covers the rest.
- **Overrides** put someone on call for a window and beat every layer, for holidays and swaps. The week view shows the
  result, one bar per person, with overrides outlined.

The page opens with who is on call now for every schedule. Over MCP, `incidents_oncall_who` says the same, and `incidents_oncall_override`
covers a shift.

## Covering a shift on the calendar

With the write role you can make and move overrides on the week view itself:

- **Drag across the week** (within a day or over several) to cover that window. When you let go, a dialog asks who covers
  it; nothing changes until you confirm.
- **Drag an override's bar** to move it. Moving it to another day keeps its local times: an override from 09:00 to 17:00 on
  the Friday before a daylight saving change is 09:00 to 17:00 on the Monday after it, even though the elapsed time
  between the two is an hour more or less. The dialog lets you hand it to someone else as well.
- **Tap or click** without dragging to open the same dialog: an hour from that spot, or the override you tapped. On a
  phone this is how it works, since a drag there scrolls the page.

Times snap to the half hour on the schedule's clock (its time zone, not your browser's), and the dialog's From and Until are
in that zone too. A 23-hour or 25-hour day is drawn at its real length. A time that the spring-forward change skips lands
just after the gap; in the hour that repeats in the autumn, a drag stays in the copy of the hour you pointed at. Escape
cancels a drag.

**Add override** above the list and **Move** on each row open the same dialog without a pointer, and the line under the
week reads out a drag as it happens for screen readers. If the new window overlaps another override, the dialog says so.
The overlap is allowed, as it is over the API: while two overrides cover the same moment, the one that starts later wins.

## Escalation policies

A policy is a list of **levels**. Each level names schedules (whoever is on call at that moment), teams and members, and
the minutes to wait before the next level. A **team** target (`{kind: "team", ref: "<team id>"}`) pages the team's current
on-call: whoever the schedules with a rotation of that team have on call. When no schedule rotates the team, it pages
everyone in the team, so a team target never pages nobody while the team has people. It can repeat the whole list a number of times, and name a Slack channel. One policy
is the **default**: it is the one the alert rules and sources use unless they name another.

## Pages

A page is created by an [alert rule](/docs/incidents/alerts.md) with the action **Page the on-call** or **Open an incident**, by an
[alert source](/docs/incidents/alert-sources.md), by hand (**Page now**), or over REST. It tells level 1 and then:

- **The bell.** The page is pinned to the top of each told member's bell until it is acknowledged.
- **A webhook.** The org's webhooks that subscribe to `incidents.page` get one event for level 1 and one for each
  escalation, with the page, the level and the members told (the event is signed like every org webhook).
- **SMS and a phone call.** A level whose notifications include SMS and Phone call texts each told member's verified
  number, then calls it a few minutes later unless someone acknowledged. Replying 1 or pressing 1 acknowledges. This goes
  through [Venom Comms](/docs/comms/incidents-paging) and needs a Comms provider. A member without a verified number,
  including one who came from a team, is skipped, and the incident timeline notes how many were.
- **Slack.** If the policy names a channel, a message goes there through your org's own Slack app (the same one the error
  alerts use). The message has **Acknowledge** and
  **Escalate** buttons while the page waits for an answer. To make them work, open your Slack app's *Interactivity & Shortcuts*,
  switch it on and paste the Interactivity Request URL from the Slack page in Venom Cloud
  (`/api/integrations/slack/<id>/interactivity`); a new app made from the page's manifest has it already. The person who
  clicks must have linked their Slack user with `/venom link`, and acts with their own role: a viewer is told they cannot.
  The message is then rewritten with who acknowledged or escalated it; an escalation posts a fresh message for the next level.
- **The incident timeline,** when the page belongs to an incident.

The same alert firing again is the same page (it counts up). **Acknowledge** stops the escalation; **Escalate** moves it
to the next level now; **Resolve** closes it. The sweep cron escalates a page whose delay ran out, once per level, and when
a policy is exhausted the page stays open and stops escalating. Over MCP: `incidents_oncall_ack` (with `resolve: true` to close), and `incidents_oncall_override_move` moves an override.

## REST

`/incidents/api/v1/oncall/…`: `now`, `members`, `schedules` (and `schedules/{id}/timeline`, `schedules/{id}/overrides`),
`overrides/{id}` (`PATCH` with `startAt`, `endAt` and optionally `member` moves one; `DELETE` removes it), `policies`, `pages` (and `pages/{id}/ack|resolve|escalate`) and `sources`. See the contract in
`contracts/incidents-openapi.yaml`.
