Explore documentation
  1. Welcome to Uptime 👋
  2. Frequently Asked Questions
  3. On-call scheduling and alerting
    1. Get started
    2. Slack and other integrations ↗
    3. Connecting external calendars
    4. Advanced guide
  4. Incidents
    1. Get started
    2. Post mortems
    3. Metadata & Catalog
    4. Screening alerts
    5. Reporting ↗
  5. Monitoring
    1. Get started
    2. Working with monitors
    3. Customizing monitors
    4. Monitor types
  6. Status pages
    1. Get started
    2. Advanced guide
  7. Uptime API
    1. Getting an API token
    2. Monitors
    3. Heartbeats
    4. On-call & incidents
      1. On-call schedule
      2. On-call schedule events
      3. On-call schedule rotations
      4. Escalation policies
        1. List escalation policies GET
        2. Get escalation policy GET
        3. Create escalation policy POST
        4. Update escalation policy PATCH
        5. Remove escalation policy DELETE
        6. Response attributes
      5. Escalation policy groups
      6. Severities
      7. Severity groups
      8. Incidents
      9. Comments
    5. Status pages
    6. Metadata
    7. Integrations
    8. Team members
    9. Reporting

Create escalation policy

Returns either a newly created escalation policy, or validation errors.

POST https://uptime.betterstack.com/api/v3/policies

Headers

Authorization
required string

Bearer $TOKEN

Content_Type
string

application/json

Body parameters

team_name
string

Required if using global API token to specify the team which should own the resource

name
required string

The name of this Policy.

repeat_count
integer

How long in seconds to wait before each repetition.

repeat_delay
integer

Incident token that can be used for manually reporting incidents.

steps
Array of PolicyStep

An array of escalation policy steps. See the list of escalation policy API parameters for details.

fallback_policy_id
integer

The ID of an escalation policy to escalate to once this policy has run all its steps and repeats without being acknowledged. Must belong to the same organization. Defaults to null (no further escalation).

201

Returns newly created escalation policy

Response body

{
  "data": {
    "id": "456789",
    "type": "policy",
    "attributes": {
      "name": "Standard Escalation Policy",
      "repeat_count": 3,
      "repeat_delay": 1800,
      "incident_token": "AND63ccyT18oKcSFnbJfxlFi1",
      "policy_group_id": null,
      "team_name": "Test Team",
      "steps": [
        {
          "type": "escalation",
          "urgency_id": 123456,
          "step_members": [
            {
              "type": "current_on_call"
            }
          ],
          "wait_before": 0
        },
        {
          "type": "escalation",
          "urgency_id": 123456,
          "step_members": [
            {
              "type": "entire_team"
            }
          ],
          "wait_before": 600
        }
      ]
    }
  }
}

Example cURL

Escalation policy Branching Instructions 
curl -X "POST" "https://uptime.betterstack.com/api/v3/policies/" \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{
  "name": "Standard Escalation Policy",
  "repeat_count": 3,
  "repeat_delay": 1800,
  "steps": [
    {
      "type": "escalation",
      "wait_before": 0,
      "urgency_id": "'$SEVERITY_ID'",
      "step_members": [
        { "type": "current_on_call" }
      ]
    },
    {
      "type": "escalation",
      "wait_before": 600,
      "urgency_id": "'$SEVERITY_ID'",
      "step_members": [
        { "type": "entire_team" }
      ]
    }
  ]
}'
curl -X "POST" "https://uptime.betterstack.com/api/v3/policies/" \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{
  "name": "Business Hours Branching",
  "steps": [
    {
      "type": "time_branching",
      "wait_before": 0,
      "timezone": "America/New_York",
      "days": ["mon", "tue", "wed", "thu", "fri"],
      "time_from": "09:00",
      "time_to": "17:00",
      "policy_metadata_key": "business_hours_policy"
    },
    {
      "type": "metadata_branching",
      "wait_before": 0
      "metadata_key": "urgency",
      "metadata_values": [
        {
          "type": "String",
          "value": "low"
        }
      ],
      "action_type": "do_not_escalate",
    },
    {
      "type": "escalation",
      "wait_before": 300,
      "urgency_id": "'$SEVERITY_ID'",
      "step_members": [
        { "type": "current_on_call" },
        { "type": "all_slack_integrations" }
      ]
    }
  ]
}'
curl -X "POST" "https://uptime.betterstack.com/api/v3/policies/" \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{
  "name": "Policy with Instructions and Todo list",
  "steps": [
    {
      "type": "instructions",
      "wait_before": 0,
      "instructions_comment": "IMMEDIATE ACTIONS:\n1. Check system status at status.example.com\n2. Verify in monitoring dashboard\n3. Check #incidents Slack channel\n4. If database-related, run: kubectl get pods -n production",
      "instructions_reminder_enabled": false
    },
    {
      "type": "escalation",
      "wait_before": 0,
      "urgency_id": "'$SEVERITY_ID'",
      "step_members": [
        { "type": "current_on_call" },
        { "type": "all_slack_integrations" }
      ]
    },
    {
      "type": "instructions",
      "wait_before": 900,
      "instructions_comment": "ESCALATION REQUIRED:\n- [] Page backup on-call\n- [] Start incident bridge: dial 1-800-XXX-XXXX, code: 12345#\n- [] Update status page\n- [] Notify stakeholders via #incident-comms",
      "instructions_reminder_enabled": true,
      "instructions_reminder_interval_hours": 2
    },
    {
      "type": "escalation",
      "wait_before": 300,
      "urgency_id": "'$SEVERITY_ID'",
      "step_members": [
        { "type": "entire_team" },
        { "type": "user", "email": "manager@example.com" }
      ]
    }
  ]
}'


Previous article

Get escalation policy

Next article

Update escalation policy