Explore documentation
  1. Welcome to Incidents 👋
  2. Frequently Asked Questions
  3. On-call scheduling and alerting
    1. Get started
    2. Slack and other integrations ↗
    3. Tag on-call in Slack
    4. Mobile apps ↗
    5. Connecting external calendars
    6. Advanced guide
  4. Incident management
    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. Incidents API
    1. Getting an API token
    2. Pagination
    3. Monitors
    4. Heartbeats
    5. 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
      5. Escalation policy groups
      6. Severities
      7. Severity groups
      8. Incidents
      9. Comments
    6. Status pages
    7. Metadata
    8. Integrations
    9. Team members
    10. Organization roles
    11. Usage
    12. Reporting

Remove escalation policy

Permanently deletes an existing escalation policy. A policy still used by monitors, heartbeats, integrations or other resources can't be deleted until you point them to another escalation policy.

DELETE https://incidents.betterstack.com/api/v3/policies/{policy_id}

URL parameters

policy_id
required integer

The ID of the escalation policy you want to delete

Headers

Authorization
required string

Bearer $TOKEN

204

Returns empty body

422

The escalation policy is still in use and wasn't deleted. Point the resources using it to another escalation policy, then try again.

Response body

{
  "errors": "Cannot remove this escalation policy because it is used in 1 monitor and 1 heartbeat."
}
503

We couldn't check whether the escalation policy is in use, so it wasn't deleted. Try again in a moment.

Response body

{
  "errors": "Couldn't remove this escalation policy. Please try again in a moment."
}

Example cURL

Example
curl --request DELETE \
  --url https://incidents.betterstack.com/api/v3/policies/456 \
  --header "Authorization: Bearer $TOKEN"


Previous article

Update escalation policy

Next article

List escalation policy groups