Unit Oncall logo markUnit Oncall
Back to Home

Escalation policy configuration

Unit Oncall does not have a standalone "escalation policy" resource. Escalation is configured inside the Schedule that handles an alert: the same fields that define rotation also decide how long Unit Oncall waits for each responder, how many rounds to attempt, and who to notify as the final fallback.

This page collects all of those fields in one place so you can reason about escalation on its own. See Schedule for the full Schedule reference.

Fields (on the Schedule)

FieldTypeRequiredDefaultNotes
rotation_timeout_secondsnumberYes—Seconds Unit Oncall waits for a responder before moving on to the next member. Range: 30–300.
rotation_roundsnumberYes—How many full rounds through the member list Unit Oncall attempts before giving up. Range: 1–5.
final_escalation_user_emailstringNo—Email of the user notified after the last round fails. Must be a member of the Schedule's Team.
membersarrayYes—The on-call rotation. Each entry is { user_id, rotation_order } or { user_email, rotation_order }. Members must belong to the Team.
configurationsarrayNo[]Overlay rotations effective only inside a date range. Up to 10; date ranges must not overlap; each overlay needs at least one member.

How escalation runs

When an alert is routed to a Schedule:

  1. Unit Oncall takes the first member by rotation_order and notifies them.
  2. If the member does not respond within rotation_timeout_seconds, Unit Oncall moves to the next member in order.
  3. After the last member in the list, the round is finished. Unit Oncall starts the next round, up to rotation_rounds total rounds.
  4. If every round finishes without a response, Unit Oncall escalates to final_escalation_user_email (the final fallback). If final_escalation_user_email is not set, no extra notification is sent after the last round.

A few details to keep in mind:

  • The number of attempts per alert is bounded by members × rotation_rounds, so set rotation_timeout_seconds and rotation_rounds so the total wait is acceptable.
  • final_escalation_user_email is resolved against the Team's members only. An email that is not a member of the Team is rejected (email_not_found).
  • Members in members (and any overlay) are also resolved against the Team's members. Non-members are rejected (not_team_member).
  • If an overlay is active for the current date, its members replace the base members for that period; rotation_timeout and rotation_rounds still come from the Schedule.

Validation rules

  • rotation_timeout_seconds is rejected outside 30–300.
  • rotation_rounds is rejected outside 1–5.
  • members must contain at least one entry.
  • final_escalation_user_email, when provided, must belong to a current Team member.
  • configurations: at most 10 overlays, no date-range overlaps, each overlay must have at least one member.

Examples

A small team with a single round and a fallback user:

{
  "name": "Backend on-call",
  "rotation_period": "weekly",
  "rotation_timeout_seconds": 120,
  "rotation_rounds": 1,
  "final_escalation_user_email": "lead@example.com",
  "members": [
    { "user_email": "alice@example.com", "rotation_order": 1 },
    { "user_email": "bob@example.com",   "rotation_order": 2 }
  ]
}

Three rounds, longer per-member wait, no final fallback:

{
  "name": "Platform on-call",
  "rotation_period": "weekly",
  "rotation_timeout_seconds": 300,
  "rotation_rounds": 3,
  "members": [
    { "user_email": "carol@example.com", "rotation_order": 1 },
    { "user_email": "dave@example.com",  "rotation_order": 2 },
    { "user_email": "erin@example.com",  "rotation_order": 3 }
  ]
}

Rotation with a holiday overlay:

{
  "name": "EU on-call",
  "rotation_period": "weekly",
  "rotation_timeout_seconds": 180,
  "rotation_rounds": 2,
  "final_escalation_user_email": "eu-lead@example.com",
  "members": [
    { "user_email": "fred@example.com",  "rotation_order": 1 },
    { "user_email": "gina@example.com",  "rotation_order": 2 }
  ],
  "configurations": [
    {
      "effective_date": "2026-12-23",
      "end_date":       "2027-01-03",
      "members": [
        { "user_email": "henri@example.com", "rotation_order": 1 }
      ]
    }
  ]
}

Related

  • Schedule — full Schedule reference, including timezone, labels, and VoIP call behavior.
  • Team — both rotation members and the final-escalation user must be members of the Team.
  • Maintenance window — pause escalation for a Schedule during planned work.