On-call schedules
An on-call schedule is a named rotation of users that, given any timestamp, returns the user who is currently on call. Escalation policies reference schedules instead of hard-coded user lists, so when the rotation hands off, paging follows automatically.
When to use schedules
Section titled “When to use schedules”- You want pages to follow a rotation rather than always hitting the same person.
- You have responders in multiple timezones and want the page to land where it’s awake.
- You want to handle holiday cover and one-off swaps cleanly.
If you only have one engineer, you don’t need a schedule: just point your escalation policy at that user directly.
How a schedule produces “who’s on call”
Section titled “How a schedule produces “who’s on call””Each schedule has:
- A name (
Primary on-call,Eng manager backup). - A timezone, an IANA name (
America/Los_Angeles,Europe/Berlin,UTC). Allhandoff_timeandhandoff_dayvalues are interpreted in this timezone, so a 09:00 handoff stays at 09:00 local across DST changes. - One or more layers, stacked in priority order.
- Zero or more overrides: hard “user X is on from time A to time B” entries.
When asked who’s on call at time T:
- Apply overrides first. If any override covers
T, that user is on call. Done. - Otherwise walk layers from the highest
layer_numberdownward. For each layer in itseffective_from/effective_untilwindow, compute whose turn it is given the rotation type. The first layer that returns a user wins.
This means higher-layer_number layers shadow lower ones during their effective windows. Useful pattern: a “weekend coverage” layer with effective_from/effective_until set to weekend hours, sitting on top of a base “weekday rotation” layer with a lower layer_number.
Layer rotation types
Section titled “Layer rotation types”rotation_type | Behavior |
|---|---|
daily | Hand off every day at handoff_time. |
weekly | Hand off once a week at handoff_time, on handoff_day (0=Sunday .. 6=Saturday) when one is set. |
custom | Hand off every rotation_interval_days days at handoff_time. |
participants is an ordered list of user UUIDs; the rotation walks the list and wraps around.
Overrides
Section titled “Overrides”An override beats every layer. Use them for:
- Holiday cover: “Bob is covering for Alice from Dec 22 to Jan 2.”
- Swap weekends: “I’ll take next weekend if you take this one.”
- Filling gaps: if an effective window leaves a hole, an override patches it.
Overrides are time-bounded with start_at and end_at. When overrides overlap, the most recently created one wins.
Common patterns
Section titled “Common patterns”Single weekly rotation
Section titled “Single weekly rotation”One layer, rotation_type: weekly, handoff_day: 1 (Monday), handoff_time: 09:00, participants: [alice, bob, carol]. Each engineer is on for one week starting Monday morning.
Follow-the-sun
Section titled “Follow-the-sun”Three layers, all rotation_type: weekly. Layer 3 (highest priority): effective_from/effective_until covers Asia-Pacific awake hours, participants are APAC engineers. Layer 2: EMEA hours, EMEA engineers. Layer 1: Americas hours, Americas engineers. The escalation policy points at this one schedule and gets the awake engineer for free.
Primary + secondary
Section titled “Primary + secondary”Two separate schedules: Primary and Secondary. Escalation policy: level 1 → Primary, level 2 → Secondary. Each schedule rotates independently.
Pricing
Section titled “Pricing”On-call schedules are included on every paid plan. Free tier is limited to a single non-rotating responder list.