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 '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",
  "title": "Production database experiencing high CPU",
  "user_ids": [
    "01H0J1EXE7AXZ2C93K61WBPYEH",
    "01H0J1EXE7AXZ2C93K61WBPYEI"
  ]
}
'

{
  "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": "viewer",
        "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": "viewer",
            "slack_user_id": "U02AYNF2XJM"
          }
        ]
      }
    ],
    "id": "01G0J1EXE7AXZ2C93K61WBPYEH",
    "priority": {
      "name": "P1"
    },
    "related_alerts": [
      {
        "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"
  }
}

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"

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

Example:

{
  "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": "viewer",
      "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": "viewer",
          "slack_user_id": "U02AYNF2XJM"
        }
      ]
    }
  ],
  "id": "01G0J1EXE7AXZ2C93K61WBPYEH",
  "priority": { "name": "P1" },
  "related_alerts": [
    {
      "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"
}

List

Show

⌘I

Create

curl --request POST \
  --url https://api.incident.io/v2/escalations \
  --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",
  "title": "Production database experiencing high CPU",
  "user_ids": [
    "01H0J1EXE7AXZ2C93K61WBPYEH",
    "01H0J1EXE7AXZ2C93K61WBPYEI"
  ]
}
'

{
  "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": "viewer",
        "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": "viewer",
            "slack_user_id": "U02AYNF2XJM"
          }
        ]
      }
    ],
    "id": "01G0J1EXE7AXZ2C93K61WBPYEH",
    "priority": {
      "name": "P1"
    },
    "related_alerts": [
      {
        "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"
  }
}

Getting started

Endpoints

Create

Body

Response