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 — IANA name (
America/Los_Angeles,Europe/Berlin,UTC). Allhandoff_timeandhandoff_dayvalues are interpreted in this timezone. - 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 highest priority (lowest
layer_number) downward. 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-priority layers shadow lower-priority 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.
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, on handoff_day (0=Sun, 6=Sat) at handoff_time. |
custom_days | 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–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. Overlapping overrides are first-defined-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 1 (priority): effective_from/effective_until covers Asia-Pacific awake hours, participants are APAC engineers. Layer 2: EMEA hours, EMEA engineers. Layer 3: 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.