Skip to main content

​
Escalation Policies API

Escalation policies define how alerts are escalated when not acknowledged within a specified time.

​
List Policies

GET /api/v1/escalation_policies
Query Parameters
ParameterTypeDescription
enabledbooleanFilter by enabled status
Response 
{
  "data": [
    {
      "id": "esc_1234567890",
      "name": "Critical Alerts Policy",
      "enabled": true,
      "steps_count": 3,
      "repeat": true,
      "repeat_after_minutes": 30,
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

​
Get Policy

GET /api/v1/escalation_policies/:id
Response 
{
  "data": {
    "id": "esc_1234567890",
    "name": "Critical Alerts Policy",
    "description": "Escalate critical alerts to engineering leadership",
    "enabled": true,
    "steps": [
      {
        "channel_id": "chan_001",
        "channel_name": "On-Call Slack",
        "delay_minutes": 0
      },
      {
        "channel_id": "chan_002",
        "channel_name": "Engineering PagerDuty",
        "delay_minutes": 5
      },
      {
        "channel_id": "chan_003",
        "channel_name": "Leadership Email",
        "delay_minutes": 15
      }
    ],
    "repeat": true,
    "repeat_after_minutes": 30,
    "max_repeats": 3,
    "created_at": "2024-01-01T00:00:00Z"
  }
}

​
Create Policy

POST /api/v1/escalation_policies
Request 
{
  "name": "Critical Alerts Policy",
  "description": "Escalate critical alerts to engineering leadership",
  "enabled": true,
  "steps": [
    {
      "channel_id": "chan_001",
      "delay_minutes": 0
    },
    {
      "channel_id": "chan_002",
      "delay_minutes": 5
    },
    {
      "channel_id": "chan_003",
      "delay_minutes": 15
    }
  ],
  "repeat": true,
  "repeat_after_minutes": 30,
  "max_repeats": 3
}
Response 
{
  "data": {
    "id": "esc_1234567890",
    "name": "Critical Alerts Policy",
    "enabled": true
  }
}

​
Update Policy

PATCH /api/v1/escalation_policies/:id
Request 
{
  "name": "Updated Policy Name",
  "steps": [
    {
      "channel_id": "chan_001",
      "delay_minutes": 0
    },
    {
      "channel_id": "chan_002",
      "delay_minutes": 10
    }
  ]
}

​
Delete Policy

DELETE /api/v1/escalation_policies/:id
Deleting an escalation policy will remove it from all alert rules that use it.

​
How Escalation Works

1

Step 1: Immediate Notification

When an alert fires, the first step (delay_minutes: 0) is notified immediately.
2

Step 2: Escalation Timer

If the alert is not acknowledged, subsequent steps are notified after their delay.
3

Step 3: Repeat (Optional)

If repeat is enabled, the entire escalation cycle repeats after repeat_after_minutes.

​
Best Practices

Start with On-Call

First step should notify the on-call engineer or team channel.

Gradual Escalation

Increase severity of notification channels in later steps.

Reasonable Delays

Give responders 5-15 minutes before escalating.

Limit Repeats

Set max_repeats to avoid notification fatigue.