Create

Create an escalation.

An escalation pages people, either according to an escalation path, or directly to specific users. You must provide either an escalation_path_id OR user_ids, but not both.

When escalating via an escalation path, the escalation will follow the configured path with its levels and timeouts, using your default alert priority.

When escalating directly to users, they will receive a high-urgency notification, based on their notification rules.

This endpoint is rate-limited to 60 requests per minute, since it is intended for interactive use cases (for example someone clicking a “escalate to team” button in your internal developer platform). To escalate based on automated alerts, we recommend sending events to an alert source instead.

POST

escalations

Create

curl --request POST \
  --url https://api.incident.io/v2/escalations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "Database CPU has been above 90% for 5 minutes",
  "escalation_path_id": "01H0J1EXE7AXZ2C93K61WBPYEH",
  "idempotency_key": "2024-01-15-abc123",
  "incident_id": "01H0J1EXE7AXZ2C93K61WBPYEH",
  "title": "Production database experiencing high CPU",
  "user_ids": [
    "01H0J1EXE7AXZ2C93K61WBPYEH",
    "01H0J1EXE7AXZ2C93K61WBPYEI"
  ]
}
'

import requests

url = "https://api.incident.io/v2/escalations"

payload = {
    "description": "Database CPU has been above 90% for 5 minutes",
    "escalation_path_id": "01H0J1EXE7AXZ2C93K61WBPYEH",
    "idempotency_key": "2024-01-15-abc123",
    "incident_id": "01H0J1EXE7AXZ2C93K61WBPYEH",
    "title": "Production database experiencing high CPU",
    "user_ids": ["01H0J1EXE7AXZ2C93K61WBPYEH", "01H0J1EXE7AXZ2C93K61WBPYEI"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    description: 'Database CPU has been above 90% for 5 minutes',
    escalation_path_id: '01H0J1EXE7AXZ2C93K61WBPYEH',
    idempotency_key: '2024-01-15-abc123',
    incident_id: '01H0J1EXE7AXZ2C93K61WBPYEH',
    title: 'Production database experiencing high CPU',
    user_ids: ['01H0J1EXE7AXZ2C93K61WBPYEH', '01H0J1EXE7AXZ2C93K61WBPYEI']
  })
};

fetch('https://api.incident.io/v2/escalations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.incident.io/v2/escalations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'description' => 'Database CPU has been above 90% for 5 minutes',
    'escalation_path_id' => '01H0J1EXE7AXZ2C93K61WBPYEH',
    'idempotency_key' => '2024-01-15-abc123',
    'incident_id' => '01H0J1EXE7AXZ2C93K61WBPYEH',
    'title' => 'Production database experiencing high CPU',
    'user_ids' => [
        '01H0J1EXE7AXZ2C93K61WBPYEH',
        '01H0J1EXE7AXZ2C93K61WBPYEI'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.incident.io/v2/escalations"

	payload := strings.NewReader("{\n  \"description\": \"Database CPU has been above 90% for 5 minutes\",\n  \"escalation_path_id\": \"01H0J1EXE7AXZ2C93K61WBPYEH\",\n  \"idempotency_key\": \"2024-01-15-abc123\",\n  \"incident_id\": \"01H0J1EXE7AXZ2C93K61WBPYEH\",\n  \"title\": \"Production database experiencing high CPU\",\n  \"user_ids\": [\n    \"01H0J1EXE7AXZ2C93K61WBPYEH\",\n    \"01H0J1EXE7AXZ2C93K61WBPYEI\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.incident.io/v2/escalations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"description\": \"Database CPU has been above 90% for 5 minutes\",\n  \"escalation_path_id\": \"01H0J1EXE7AXZ2C93K61WBPYEH\",\n  \"idempotency_key\": \"2024-01-15-abc123\",\n  \"incident_id\": \"01H0J1EXE7AXZ2C93K61WBPYEH\",\n  \"title\": \"Production database experiencing high CPU\",\n  \"user_ids\": [\n    \"01H0J1EXE7AXZ2C93K61WBPYEH\",\n    \"01H0J1EXE7AXZ2C93K61WBPYEI\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.incident.io/v2/escalations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"description\": \"Database CPU has been above 90% for 5 minutes\",\n  \"escalation_path_id\": \"01H0J1EXE7AXZ2C93K61WBPYEH\",\n  \"idempotency_key\": \"2024-01-15-abc123\",\n  \"incident_id\": \"01H0J1EXE7AXZ2C93K61WBPYEH\",\n  \"title\": \"Production database experiencing high CPU\",\n  \"user_ids\": [\n    \"01H0J1EXE7AXZ2C93K61WBPYEH\",\n    \"01H0J1EXE7AXZ2C93K61WBPYEI\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "escalation": {
    "created_at": "2021-08-17T13:28:57.801578Z",
    "creator": {
      "alert": {
        "id": "01GW2G3V0S59R238FAHPDS1R66",
        "title": "*errors.withMessage: PG::Error failed to connect"
      },
      "user": {
        "email": "lisa@incident.io",
        "id": "01FCNDV6P870EA6S7TK1DSYDG0",
        "name": "Lisa Karlin Curtis",
        "role": "owner",
        "slack_user_id": "U02AYNF2XJM"
      },
      "workflow": {
        "id": "01FCNDV6P870EA6S7TK1DSYDG0",
        "name": "My little workflow"
      }
    },
    "escalation_path_id": "01G0J1EXE7AXZ2C93K61WBPYEH",
    "events": [
      {
        "channels": [
          {
            "microsoft_teams_channel_id": "abc123",
            "microsoft_teams_team_id": "abc123",
            "slack_channel_id": "abc123",
            "slack_team_id": "abc123"
          }
        ],
        "event": "entered_grace_period",
        "id": "01G0J1EXE7AXZ2C93K61WBPYEH",
        "occurred_at": "2021-08-17T13:28:57.801578Z",
        "urgency": "high",
        "users": [
          {
            "email": "lisa@incident.io",
            "id": "01FCNDV6P870EA6S7TK1DSYDG0",
            "name": "Lisa Karlin Curtis",
            "role": "owner",
            "slack_user_id": "U02AYNF2XJM"
          }
        ]
      }
    ],
    "id": "01G0J1EXE7AXZ2C93K61WBPYEH",
    "priority": {
      "name": "P1"
    },
    "related_alerts": [
      {
        "alert_group_ids": [
          "01GW2G3V0S59R238FAHPDS1R66"
        ],
        "alert_source_id": "01GW2G3V0S59R238FAHPDS1R66",
        "created_at": "2021-08-17T13:28:57.801578Z",
        "deduplication_key": "4293868629",
        "description": "CPU on the payments service has exceeded 75 percent for 5 minutes",
        "id": "01GW2G3V0S59R238FAHPDS1R66",
        "resolved_at": "2021-08-17T14:28:57.801578Z",
        "source_url": "https://www.my-alerting-platform.com/alerts/my-alert-123",
        "status": "firing",
        "title": "*errors.withMessage: PG::Error failed to connect",
        "updated_at": "2021-08-17T13:28:57.801578Z"
      }
    ],
    "related_incidents": [
      {
        "external_id": 123,
        "id": "01FDAG4SAP5TYPT98WGR2N7W91",
        "name": "Our database is sad",
        "reference": "INC-123",
        "status_category": "triage",
        "summary": "Our database is really really sad, and we don't know why yet.",
        "visibility": "public"
      }
    ],
    "status": "pending",
    "title": "Database CPU is high",
    "updated_at": "2021-08-17T13:28:57.801578Z"
  }
}

🔑 Requires the escalations.create scope.

Authorizations

Authorization

string

header

required

API key from your incident.io dashboard (Settings → API keys)

Body

application/json

idempotency_key

string

required

Unique key to prevent duplicate escalations. If this key has already been used, the existing escalation will be returned.

Example:

"2024-01-15-abc123"

title

string

required

The title of the escalation. This message will be included in all notifications about this escalation.

Example:

"Production database experiencing high CPU"

description

string

Additional details about the escalation

Example:

"Database CPU has been above 90% for 5 minutes"

escalation_path_id

string

ID of the escalation path to follow

Example:

"01H0J1EXE7AXZ2C93K61WBPYEH"

incident_id

string

ID of an incident to associate with this escalation. The linked incident will appear in the escalation's related_incidents field.

Example:

"01H0J1EXE7AXZ2C93K61WBPYEH"

user_ids

string[]

IDs of users to escalate directly to

Example:

[
  "01H0J1EXE7AXZ2C93K61WBPYEH",
  "01H0J1EXE7AXZ2C93K61WBPYEI"
]

Response

201 - application/json

Created response.

escalation

object

required

Show child attributes

List

Show

⌘I

Create

curl --request POST \
  --url https://api.incident.io/v2/escalations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "Database CPU has been above 90% for 5 minutes",
  "escalation_path_id": "01H0J1EXE7AXZ2C93K61WBPYEH",
  "idempotency_key": "2024-01-15-abc123",
  "incident_id": "01H0J1EXE7AXZ2C93K61WBPYEH",
  "title": "Production database experiencing high CPU",
  "user_ids": [
    "01H0J1EXE7AXZ2C93K61WBPYEH",
    "01H0J1EXE7AXZ2C93K61WBPYEI"
  ]
}
'

import requests

url = "https://api.incident.io/v2/escalations"

payload = {
    "description": "Database CPU has been above 90% for 5 minutes",
    "escalation_path_id": "01H0J1EXE7AXZ2C93K61WBPYEH",
    "idempotency_key": "2024-01-15-abc123",
    "incident_id": "01H0J1EXE7AXZ2C93K61WBPYEH",
    "title": "Production database experiencing high CPU",
    "user_ids": ["01H0J1EXE7AXZ2C93K61WBPYEH", "01H0J1EXE7AXZ2C93K61WBPYEI"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    description: 'Database CPU has been above 90% for 5 minutes',
    escalation_path_id: '01H0J1EXE7AXZ2C93K61WBPYEH',
    idempotency_key: '2024-01-15-abc123',
    incident_id: '01H0J1EXE7AXZ2C93K61WBPYEH',
    title: 'Production database experiencing high CPU',
    user_ids: ['01H0J1EXE7AXZ2C93K61WBPYEH', '01H0J1EXE7AXZ2C93K61WBPYEI']
  })
};

fetch('https://api.incident.io/v2/escalations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.incident.io/v2/escalations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'description' => 'Database CPU has been above 90% for 5 minutes',
    'escalation_path_id' => '01H0J1EXE7AXZ2C93K61WBPYEH',
    'idempotency_key' => '2024-01-15-abc123',
    'incident_id' => '01H0J1EXE7AXZ2C93K61WBPYEH',
    'title' => 'Production database experiencing high CPU',
    'user_ids' => [
        '01H0J1EXE7AXZ2C93K61WBPYEH',
        '01H0J1EXE7AXZ2C93K61WBPYEI'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.incident.io/v2/escalations"

	payload := strings.NewReader("{\n  \"description\": \"Database CPU has been above 90% for 5 minutes\",\n  \"escalation_path_id\": \"01H0J1EXE7AXZ2C93K61WBPYEH\",\n  \"idempotency_key\": \"2024-01-15-abc123\",\n  \"incident_id\": \"01H0J1EXE7AXZ2C93K61WBPYEH\",\n  \"title\": \"Production database experiencing high CPU\",\n  \"user_ids\": [\n    \"01H0J1EXE7AXZ2C93K61WBPYEH\",\n    \"01H0J1EXE7AXZ2C93K61WBPYEI\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.incident.io/v2/escalations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"description\": \"Database CPU has been above 90% for 5 minutes\",\n  \"escalation_path_id\": \"01H0J1EXE7AXZ2C93K61WBPYEH\",\n  \"idempotency_key\": \"2024-01-15-abc123\",\n  \"incident_id\": \"01H0J1EXE7AXZ2C93K61WBPYEH\",\n  \"title\": \"Production database experiencing high CPU\",\n  \"user_ids\": [\n    \"01H0J1EXE7AXZ2C93K61WBPYEH\",\n    \"01H0J1EXE7AXZ2C93K61WBPYEI\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.incident.io/v2/escalations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"description\": \"Database CPU has been above 90% for 5 minutes\",\n  \"escalation_path_id\": \"01H0J1EXE7AXZ2C93K61WBPYEH\",\n  \"idempotency_key\": \"2024-01-15-abc123\",\n  \"incident_id\": \"01H0J1EXE7AXZ2C93K61WBPYEH\",\n  \"title\": \"Production database experiencing high CPU\",\n  \"user_ids\": [\n    \"01H0J1EXE7AXZ2C93K61WBPYEH\",\n    \"01H0J1EXE7AXZ2C93K61WBPYEI\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "escalation": {
    "created_at": "2021-08-17T13:28:57.801578Z",
    "creator": {
      "alert": {
        "id": "01GW2G3V0S59R238FAHPDS1R66",
        "title": "*errors.withMessage: PG::Error failed to connect"
      },
      "user": {
        "email": "lisa@incident.io",
        "id": "01FCNDV6P870EA6S7TK1DSYDG0",
        "name": "Lisa Karlin Curtis",
        "role": "owner",
        "slack_user_id": "U02AYNF2XJM"
      },
      "workflow": {
        "id": "01FCNDV6P870EA6S7TK1DSYDG0",
        "name": "My little workflow"
      }
    },
    "escalation_path_id": "01G0J1EXE7AXZ2C93K61WBPYEH",
    "events": [
      {
        "channels": [
          {
            "microsoft_teams_channel_id": "abc123",
            "microsoft_teams_team_id": "abc123",
            "slack_channel_id": "abc123",
            "slack_team_id": "abc123"
          }
        ],
        "event": "entered_grace_period",
        "id": "01G0J1EXE7AXZ2C93K61WBPYEH",
        "occurred_at": "2021-08-17T13:28:57.801578Z",
        "urgency": "high",
        "users": [
          {
            "email": "lisa@incident.io",
            "id": "01FCNDV6P870EA6S7TK1DSYDG0",
            "name": "Lisa Karlin Curtis",
            "role": "owner",
            "slack_user_id": "U02AYNF2XJM"
          }
        ]
      }
    ],
    "id": "01G0J1EXE7AXZ2C93K61WBPYEH",
    "priority": {
      "name": "P1"
    },
    "related_alerts": [
      {
        "alert_group_ids": [
          "01GW2G3V0S59R238FAHPDS1R66"
        ],
        "alert_source_id": "01GW2G3V0S59R238FAHPDS1R66",
        "created_at": "2021-08-17T13:28:57.801578Z",
        "deduplication_key": "4293868629",
        "description": "CPU on the payments service has exceeded 75 percent for 5 minutes",
        "id": "01GW2G3V0S59R238FAHPDS1R66",
        "resolved_at": "2021-08-17T14:28:57.801578Z",
        "source_url": "https://www.my-alerting-platform.com/alerts/my-alert-123",
        "status": "firing",
        "title": "*errors.withMessage: PG::Error failed to connect",
        "updated_at": "2021-08-17T13:28:57.801578Z"
      }
    ],
    "related_incidents": [
      {
        "external_id": 123,
        "id": "01FDAG4SAP5TYPT98WGR2N7W91",
        "name": "Our database is sad",
        "reference": "INC-123",
        "status_category": "triage",
        "summary": "Our database is really really sad, and we don't know why yet.",
        "visibility": "public"
      }
    ],
    "status": "pending",
    "title": "Database CPU is high",
    "updated_at": "2021-08-17T13:28:57.801578Z"
  }
}