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. Connecting external calendars
    4. 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. Monitors
    3. Heartbeats
    4. On-call & incidents
      1. On-call schedule
      2. On-call schedule events
      3. On-call schedule rotations
      4. Escalation policies
      5. Escalation policy groups
      6. Severities
      7. Severity groups
      8. Incidents
        1. List incidents GET
        2. Get incident GET
        3. List incident timeline GET
        4. Create incident POST
        5. Acknowledge incident POST
        6. Resolve incident POST
        7. Reopen incident POST
        8. Escalate incident POST
        9. Remove incident DELETE
        10. Response attributes
      9. Comments
    5. Status pages
    6. Metadata
    7. Integrations
    8. Team members
    9. Organization roles
    10. Usage
    11. Reporting

Escalate incident

This will escalate an ongoing incident to another team member, a team, different escalation policy, or the whole organization.

POST https://incidents.betterstack.com/api/v3/incidents/{incident_id}/escalate

URL parameters

incident_id
required string

The ID of the incident you want to get

Headers

Authorization
required string

Bearer $TOKEN

Body parameters

escalation_type
required string

Who should we escalate this incident to?
Possible values: User, Team, Schedule, Policy, and Organization

user_email
string

Define which team member to escalate to.
Either user_email or user_id required when escalating to User.

user_id
integer

Define which team member to escalate to.
Either user_email or user_id required when escalating to User.

team_name
string

Define which team to escalate to.
Either team_name or team_id required when escalating to Team.

team_id
integer

Define which team to escalate to.
Either team_name or team_id required when escalating to Team.

schedule_id
integer

Define which on-call calendar to escalate to. Required when escalating to Schedule.

policy_id
integer

Define which escalation policy to escalate to. Required when escalating to Policy.

call
boolean

Should we call?
Can be used when escalating to User, Team, Schedule, or Organization.

sms
boolean

Should we send an SMS?
Can be used when escalating to User, Team, Schedule, or Organization.

email
boolean

Should we send an email?
Can be used when escalating to User, Team, Schedule, or Organization.

push
boolean

Should we send a push notification?
Can be used when escalating to User, Team, Schedule, or Organization.

critical_alert
boolean

Should we send a critical push notification that ignores the mute switch and Do not Disturb mode?
Can be used when escalating to User, Team, Schedule, or Organization.

metadata
object

An object with metadata keys as the object keys and either a single metadata value or an array of metadata values as the object values. Each value is a plain string or an object with the attributes described on the metadata API response params page. All values under one key must be of the same type and must not repeat. When escalating, repeated values and values already on the incident are skipped, and so is a value whose type differs from the key's existing values or from the first value sent for that key.

200

Returned when an incident was escalated successfully

Response body

{
  "data": {
    "id": "123456789",
    "type": "incident",
    "attributes": {
      "name": "uptime homepage",
      "url": "https://uptime.betterstack.com/",
      "http_method": "get",
      "cause": "Status 500",
      "incident_group_id": null,
      "started_at": "2020-03-09T17:37:56.662Z",
      "acknowledged_at": "2020-03-09T18:37:56.662Z",
      "acknowledged_by": "Elon Musk",
      "resolved_at": null,
      "resolved_by": null,
      "response_content": "\n404 Not Found\n\nNot Found\nThe requested URL /fail was not found on this server.\n",
      "response_options": "{}",
      "regions": [
        "us",
        "eu",
        "as",
        "au"
      ],
      "response_url": null,
      "screenshot_url": null,
      "origin_url": null,
      "escalation_policy_id": null,
      "call": true,
      "sms": true,
      "email": true,
      "push": true
    },
    "relationships": {
      "monitor": {
        "data": {
          "id": "2",
          "type": "monitor"
        }
      }
    }
  }
}
409

Returned when an incident was already resolved

Response body

{
  "errors": "Cannot escalate a resolved incident."
}

Example cURL

User Team Schedule Policy Organization With metadata 
curl --request POST \
  --url https://incidents.betterstack.com/api/v3/incidents/123456/escalate \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "escalation_type": "User",
    "user_email": "mail@example.com",
    "email": true,
    "push": true
  }'
curl --request POST \
  --url https://incidents.betterstack.com/api/v3/incidents/123456/escalate \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "escalation_type": "Team",
    "team_name": "My Team",
    "email": true,
    "push": true
  }'
curl --request POST \
  --url https://incidents.betterstack.com/api/v3/incidents/123456/escalate \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "escalation_type": "Schedule",
    "schedule_id": 123,
    "call": true,
    "push": true,
    "critical_alert": true
  }'
curl --request POST \
  --url https://incidents.betterstack.com/api/v3/incidents/123456/escalate \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "escalation_type": "Policy",
    "policy_id": 123
  }'
curl --request POST \
  --url https://incidents.betterstack.com/api/v3/incidents/123456/escalate \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "escalation_type": "Organization",
    "push": true
  }'
curl --request POST \
  --url https://incidents.betterstack.com/api/v3/incidents/123456/escalate \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "escalation_type": "User",
    "user_email": "mail@example.com",
    "email": true,
    "push": true,
    "metadata": {
      "Affected Services": [
        {
          "value": "Homepage"
        },
        {
          "value": "Login"
        }
      ],
      "On-call Calendar": [
        {
          "type": "Schedule",
          "name": "Primary calendar"
        }
      ]
    }
  }'


Previous article

Reopen incident

Next article

Remove incident