Escalation policies

An escalation policy is the rule for what to do if no one acknowledges an incident. It’s an ordered list of levels; each level fires its targets, waits its timeout, and if no acknowledgment arrives, the next level fires.

What starts an escalation

An escalation runs when an incident opens on a service that has an escalation policy, whether a monitor opened it or you created it by hand. The policy is attached to the service, not to the monitor or the notification group, so an incident with no service, or whose service has no policy, never escalates.

Anatomy

Each level has a timeout_minutes and its targets: users (target_user_ids), on-call schedules (target_schedule_ids), or both, as in “page Alice and whoever’s on the platform schedule, wait 5 minutes, then move on.” Levels are numbered 1 to N and run in that order; see levels are positions for how adding, deleting and reordering renumber them.

On the policy, repeat_count sets how many more passes to run after the first, and on_exhausted sets what happens when nobody acknowledges: notify_owners (default), stop or escalate_to_policy. Every field is in the reference.

Lifecycle

Incident opens
     │
     ▼
┌─ Level 1 ──────────────────┐
│ targets: [on_call_primary] │
│ timeout: 5 min             │
└────────┬───────────────────┘
         │
   no ack within 5 min
         │
         ▼
┌─ Level 2 ──────────────────┐
│ targets: [on_call_backup]  │
│ timeout: 10 min            │
└────────┬───────────────────┘
         │
   no ack within 10 min
         │
         ▼
┌─ Level 3 ──────────────────┐
│ targets: [eng_manager]     │
│ timeout: 15 min            │
└────────┬───────────────────┘
         │
   no ack within 15 min
         │
         ▼
   repeat (per repeat_count), then on_exhausted

When a level starts, it pages each target through that person’s own notification rules. On-call schedules resolve at that moment, so handoffs work transparently. The timeout counts from when the level starts, so time spent paging does not lengthen it.

A rule whose contact method cannot page (an unverified SMS number, a bounced email address, no SMS left on the account) is skipped. A user no rule can reach is paged at their sign-in email instead. Both are recorded on the incident.

A level that reaches nobody is skipped

When a level starts and nothing would go out to any of its targets (no targets, nobody on call, every target left the account, or every address bounced including the sign-in email), it is skipped at once instead of waiting out its timeout, and the next level starts. The incident records an escalation_unreachable event naming the level and why each target was out of reach. The readiness check uses the same definition.

A level that reaches anyone at all, through a working rule, a rule delayed past the timeout or the sign-in email fallback, is not skipped. If a whole round of levels reaches nobody, or the policy has no levels, the policy runs out at once and on_exhausted applies.

What a page says

Every page names the incident, its service and the monitors in it, and why this person is being paged: the level and pass, the policy, and the on-call schedule that put them there. For example, an email reads “You are paged by level 2 of 3 of the escalation policy “Platform”, pass 2 of 3, as on call for Primary on-call.” SMS carries a short form such as L2/3 via Primary on-call, and Slack adds the line under the incident fields.

When nobody acknowledges

A policy runs out when its last level times out on the last pass, or as soon as no level reaches anyone. What happens then is the policy’s on_exhausted:

`on_exhausted`	What happens
`notify_owners` (default)	Every owner and admin of the account gets one email saying the policy ran out and nobody owns the incident.
`stop`	Nothing is sent.
`escalate_to_policy`	The policy named in `escalate_to_policy_id` runs once, from its first level. When it runs out too, the owners and admins get the email, whatever that policy’s own `on_exhausted` says.

In every case the incident records an escalation_exhausted event, and the dashboard shows a banner on the incident until someone acknowledges it.

escalate_to_policy follows one hop only: the fallback never hands over again, so two policies that fall back to each other cannot loop. Reopening the incident starts over on the service’s own policy. A policy that another policy falls back to cannot be deleted until you give those policies another fallback.

Acknowledging stops it

Acknowledging or resolving the incident cancels the escalation: neither its pending timeout nor any per-user delayed page will fire. Every route into acknowledgment does this:

POST /incident/{id}/acknowledge and POST /incident/{id}/resolve
the acknowledge and resolve links in a paged responder’s email and SMS
the dashboard’s incident page
acknowledging the monitor outage that opened the incident
automatic recovery, when the monitor that opened the incident comes back

Running out is different. An exhausted policy stops only the level cycling, so a per-user rule’s delayed page (delay_minutes) that was already scheduled still fires while the incident is unacknowledged.

When an incident changes while it escalates

Severity goes up. Raising an incident from minor to major or critical pages the current level again, and an acknowledged incident goes back to triggered.
It moves to another service. The old service’s escalation is canceled and the new service’s policy starts at level one, but only while the incident is triggered. See move an incident to another service.
You add participants. Adding a user, a schedule or a policy as participants pages each person through their own notification rules.

Targets vs notification groups

Notification groups are the raw fanout: “this monitor’s alerts go to these channels.” Channel-level. No escalation.
Escalation policies are the routing for incidents: “if no one acks, move on.” User and schedule level, hooking into per-user notification rules.

A monitor’s alert always goes to its notification groups, and nothing in a group starts an escalation. A common setup: the group sends a Slack message for visibility, and the service’s escalation policy pages the on-call.

Repeat cycles

repeat_count is how many more times the policy runs through its levels after the first pass, from 0 to 20, default 0. When the last level times out, the policy goes back to level 1 for another pass. When the repeats are used up, the escalation becomes exhausted and on_exhausted applies.

`repeat_count`	Behavior
`0` (default)	One pass through every level, then `on_exhausted`.
`1`	Two passes, then `on_exhausted`.
`3`	Four passes, then `on_exhausted`.
`20`	The maximum: 21 passes.

When to use multiple policies

One per service if your on-call rotations differ by service ownership.
One per environment if prod and staging page different people.