Escalation Policies

An escalation policy is an ordered sequence of notification steps triggered when an alert is not acknowledged within a per-step timeout. Monitors reference one policy; policies reference notification channels, schedules, and teams.

Endpoints

Method	Path	Description	Scope
GET	/api/v1/escalation-policies	List.	escalation_policies
POST	/api/v1/escalation-policies	Create.	escalation_policies
GET	/api/v1/escalation-policies/{id}	Read.	escalation_policies
PATCH	/api/v1/escalation-policies/{id}	Update metadata.	escalation_policies
DELETE	/api/v1/escalation-policies/{id}	Delete. Fails if any monitor references it.	escalation_policies
PUT	/api/v1/escalation-policies/{id}/steps	Replace step sequence.	escalation_policies

Policy document

{
  "id": "01HXEP...",
  "name": "Platform oncall",
  "description": "Pages platform oncall first, then falls back to the whole team.",
  "repeat_count": 2,
  "repeat_delay_seconds": 900,
  "steps": [
    {
      "id": "01HXSTEP1...",
      "position": 1,
      "wait_seconds": 0,
      "targets": [
        {"type": "schedule", "id": "01HXSCHED..."}
      ]
    },
    {
      "id": "01HXSTEP2...",
      "position": 2,
      "wait_seconds": 300,
      "targets": [
        {"type": "channel", "id": "01HXCHAN...", "name": "slack:#platform-fallback"}
      ]
    }
  ]
}

Replace steps

PUT /api/v1/escalation-policies/{id}/steps

{
  "steps": [
    { "position": 1, "wait_seconds": 0,   "targets": [{"type": "schedule", "id": "01HX..."}] },
    { "position": 2, "wait_seconds": 300, "targets": [{"type": "user",     "id": "usr_bob"}] },
    { "position": 3, "wait_seconds": 900, "targets": [{"type": "team",     "id": "01HX..."}] }
  ]
}

PUT replaces the entire step sequence atomically. The server assigns new ids; if you need stable IDs across edits, preserve existing step IDs in the request (send them on the matching step objects).

Target types

Type	Payload
user	{"type": "user", "id": "usr_..."}
team	{"type": "team", "id": "01HX..."}
schedule	{"type": "schedule", "id": "01HX..."}; resolves to the on-call user at dispatch time.
channel	{"type": "channel", "id": "01HX..."}; bypasses user mapping, pings the channel directly.

Step semantics

• wait_seconds is measured from the previous step’s dispatch, not from alert fire time.
• If repeat_count > 0 and the alert remains un-ack’d after the last step, the policy restarts from step 1 after repeat_delay_seconds.
• Escalation halts as soon as the alert is acknowledged or resolved.