Escalation policy reference

The full request schemas live in the auto-generated API Reference. This page is the human-readable cheat sheet.

Escalation policy

Field	Type	Default	Description
`name`	string	required	Human label, shown in dashboards and per-incident views.
`repeat_count`	int	`3`	How many full passes through the levels to run before giving up. See repeat cycles. Not range-validated.

Escalation level

Field	Type	Default	Description
`level_number`	int	next-free	Sort order within the policy. Lower runs first. Auto-assigned to `max(existing) + 1` if omitted.
`timeout_minutes`	int	required	How long to wait for any responder ack at this level before advancing. Whole minutes only. Not range-validated.
`target_user_ids`	uuid[]	`[]`	Page these specific users. Each user’s notification rules + contact methods determine the actual delivery.
`target_schedule_ids`	uuid[]	`[]`	Page whoever is on-call in these on-call schedules at firing time.

A level with no resolvable targets pages nobody, but it still waits out its timeout and still advances.

Level numbering rules

The engine starts at the level numbered exactly 1 and then looks for 2, 3, and so on. Two failure modes follow, and neither reports an error:

No level 1. The policy never pages at all.
A gap (levels 1 and 3, say). Level 1 pages, then the policy looks for level 2, finds nothing, and stalls. No further timeout is scheduled.

Omitting level_number on create auto-assigns max + 1, which is always safe. If you have set numbers by hand, use the reorder endpoint to renumber to a clean 1..N.

Duplicate level_number values are accepted, but only the first matching level is ever paged.

Step types: practical recipes

Page the on-call rotation

{ "timeout_minutes": 5, "target_schedule_ids": ["<primary>"] }

The most common first level. Resolves at firing time, so handoffs work transparently.

Page a specific person

{ "timeout_minutes": 10, "target_user_ids": ["<eng-manager>"] }

Use for fixed targets like “the engineering manager always gets paged at level 2.”

Page on-call + a backup person

{
  "timeout_minutes": 5,
  "target_schedule_ids": ["<primary>"],
  "target_user_ids": ["<sre-lead>"]
}

Both fire in parallel. First ack from anyone wins.

Page on-call + secondary on-call

{
  "timeout_minutes": 10,
  "target_schedule_ids": ["<primary>", "<secondary>"]
}

Both schedules’ current responders get paged. Useful when you want a second pair of eyes from level 1.

Final-level “page everyone”

{ "timeout_minutes": 30, "target_user_ids": ["<eng-mgr>", "<vp-eng>", "<cto>"] }

Reserve for critical incidents that have already burned through 30+ minutes without an ack. If you hit this regularly, fix the on-call rotation, not the escalation.

Reorder endpoint

PUT /escalation_policy/{policy_id}/level/reorder accepts a level_ids array in desired order and rewrites every level’s level_number to match.

{ "level_ids": ["<id-1>", "<id-2>", "<id-3>"] }

The array must contain exactly the existing levels: no adds, no removes. It rewrites every level_number to a contiguous 1..N, which is the safe way to repair a policy with gaps.

How targets are paged

A level’s targets are resolved and de-duplicated, then each user is paged through their own notification rules for the incident’s urgency.

Incident severity	Urgency used
`critical`	high
`major`	high
`minor`	low

This mapping is fixed and cannot be overridden per policy. A targeted user with no rule matching that urgency is not paged at all, which is the most common reason a level appears to do nothing.

Two further limits on delivery, both worth knowing before you design a chain:

phone_call contact methods have no transport and are skipped at send time.
A contact method’s verified flag is not checked before paging.

See notifications for both.

Escalation state values

Value	Meaning
`active`	Cycling through levels.
`acknowledged`	Acked or resolved. Paging stopped and pending schedules deleted.
`exhausted`	Repeat cycles are used up. Level cycling stopped, but a per-user delayed page that was already scheduled can still fire.

Escalation policy reference