Escalations V2

Create and manage escalation paths, and create, list and filter escalations.

With incident.io On-call you can create escalation paths that describe how a page should be escalated to people and schedules.

CreatePath Escalations V2

Create an escalation path.

An escalation path is a series of steps that describe how a page should be escalated, represented as graph, supporting conditional branches based on alert priority and working intervals.

We recommend you create escalation paths in the incident.io dashboard where our path builder makes it easy to use conditions and visualise the path.

Request
Request Body schema: application/json
required
name
required
string

The name of this escalation path, for the user's reference.

required
Array of objects (EscalationPathNodePayloadV2)

The nodes that form the levels and branches of this escalation path.

team_ids
Array of strings

IDs of the teams that own this escalation path. This will automatically sync escalation paths with the right teams in Catalog. If you have an escalation paths attribute on your Teams, this attribute is required.

Array of objects (WeekdayIntervalConfigV2)

The working hours for this escalation path.

Responses
201

Created response.

post/v2/escalation_paths
Request samples
application/json
{
  • "name": "Urgent Support",
  • "path": [
    ],
  • "team_ids": [
    ],
  • "working_hours": [
    ]
}
Response samples
application/json
{
  • "escalation_path": {
    }
}

DestroyPath Escalations V2

Archives an escalation path.

We recommend you create escalation paths in the incident.io dashboard where our path builder makes it easy to use conditions and visualise the path.

Request
path Parameters
id
required
string

Unique identifier for this escalation path.

Example: 01FCNDV6P870EA6S7TK1DSYDG0
Responses
204

No Content response.

delete/v2/escalation_paths/{id}
Request samples 
ShowPath Escalations V2
Show an escalation path.


We recommend you create escalation paths in the incident.io dashboard where our path
builder makes it easy to use conditions and visualise the path.


Request 
path Parameters
id
required
string
Unique identifier for this escalation path.


 
 Example:  01FCNDV6P870EA6S7TK1DSYDG0
Responses 
200
OK response.


get/v2/escalation_paths/{id}
Request samples 
Response samples 
application/json
{
  • "escalation_path": {
    }
}
UpdatePath Escalations V2
Updates an escalation path.


We recommend you create escalation paths in the incident.io dashboard where our path
builder makes it easy to use conditions and visualise the path.


Request 
path Parameters
id
required
string
Unique identifier for this escalation path.


 
 Example:  01FCNDV6P870EA6S7TK1DSYDG0
Request Body schema: application/json
required
name
required
string
The name of this escalation path, for the user's reference.


 
required
Array of objects (EscalationPathNodePayloadV2) 
The nodes that form the levels and branches of this escalation path.


 
team_ids
Array of strings
IDs of the teams that own this escalation path. This will automatically sync escalation paths with the right teams in Catalog. If you have an escalation paths attribute on your Teams, this attribute is required.


 
Array of objects (WeekdayIntervalConfigV2) 
The working hours for this escalation path.


 
Responses 
200
OK response.


put/v2/escalation_paths/{id}
Request samples 
application/json
{
  • "name": "Urgent Support",
  • "path": [
    ],
  • "team_ids": [
    ],
  • "working_hours": [
    ]
}
Response samples 
application/json
{
  • "escalation_path": {
    }
}
List Escalations V2
List all escalations for your account.


This endpoint supports a number of filters, which can help find escalations matching certain
criteria.


Note that:


    

  • Filters may be used together, and the result will be escalations that match all filters.
    • 

  • All query parameters must be URI encoded.
    • 



To use this API, you will need an API key with the "View data" or "Create and manage on-call resources" permission.


By escalation_path


Find all escalations that escalated to escalation path with id=ABC:


    curl --get 'https://api.incident.io/v2/escalations' \
        --data 'escalation_path[one_of]=ABC'



By status


Find all escalations with a current status of "triggered":


    curl --get 'https://api.incident.io/v2/escalations' \
        --data 'status[one_of]=triggered'



Possible values are "pending", "triggered", "acked", "resolved", "expired" and "cancelled".
Escalations are in "pending" when they are in a grace period when the related alert has
been grouped in an incident.


By alert


Find all escalations that were created by alert with id=ABC:


    curl --get 'https://api.incident.io/v2/escalations' \
        --data 'alert[one_of]=ABC'



By created_at and updated_at


Find all escalations that follow specified date parameters for created_at and updated_at fields.
Possible values are "gte" (greater than or equal to), "lte" (less than or equal to), and
"date_range" (between two dates).
For example, to find all escalations updated after 2025-01-01:


    curl --get 'https://api.incident.io/v2/escalations' \
        --data 'updated_at[gte]=2025-01-01'



To find all escalations created between 2025-01-01 and 2025-01-31:


    curl --get 'https://api.incident.io/v2/escalations' \
        --data 'created_at[date_range]=2025-01-01~2025-01-31'



Request 
query Parameters
page_size
integer <int64>   [ 1 .. 50 ] 
 Default:  25
Number of escalations to return per page


 
 Example:  page_size=25
after
string
An escalation's ID. This endpoint will return a list of escalations after this ID in relation to the API response order.


 
 Example:  after=01FDAG4SAP5TYPT98WGR2N7W91
object
Filter on the escalation path for which the escalation was triggered. Accepted operators are 'one_of' and 'not_in'.


 
 Example:  one_of=01J479052SSQAA4531ASFPR3BF
object
Filter on the status of the escalation. Accepted operators are 'one_of' and 'not_in'.


 
 Example:  one_of=triggered
object
Filter on the alert that created an escalation. Accepted operators are 'one_of' and 'not_in'.


 
 Example:  one_of=01J479052SSQAA4531ASFPR3BF
object
Filter on the created_at timestamp of the escalation. Accepted operators are 'gte', 'lte' and 'date_range'.


 
 Example:  gte=2021-08-17
object
Filter on the updated_at timestamp of the escalation. Accepted operators are 'gte', 'lte' and 'date_range'.


 
 Example:  gte=2021-08-17
Responses 
200
OK response.


get/v2/escalations
Request samples 
Response samples 
application/json
{
  • "escalations": [
    ],
  • "pagination_meta": {
    }
}
Create Escalations V2
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.


Request 
Request Body schema: application/json
required
description
string
Additional details about the escalation


 
escalation_path_id
string
ID of the escalation path to follow


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


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


 
user_ids
Array of strings
IDs of users to escalate directly to


 
Responses 
201
Created response.


post/v2/escalations
Request samples 
application/json
{
  • "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": [
    ]
}
Response samples 
application/json
{
  • "escalation": {
    }
}
Show Escalations V2
Show a specific escalation.


Request 
path Parameters
id
required
string
Unique ID of the escalation


 
 Example:  01G0J1EXE7AXZ2C93K61WBPYEH
Responses 
200
OK response.


get/v2/escalations/{id}
Request samples 
Response samples 
application/json
{
  • "escalation": {
    }
}
➔ Next to Follow-ups V2