Escalation policies HTTP API
Create an escalation policy
Required permission: grafana-irm-app.escalation-chains:write
curl "{{API_URL}}/api/v1/escalation_policies/" \
--request POST \
--header "Authorization: Bearer meowmeowmeow" \
--header "Content-Type: application/json" \
--header "X-Grafana-URL: https://your-stack.grafana.net" \
--data '{
"escalation_chain_id": "F5JU6KJET33FE",
"type": "wait",
"duration": 60
}'The above command returns JSON structured in the following way:
{
"id": "E3GA6SJETWWJS",
"escalation_chain_id": "F5JU6KJET33FE",
"position": 0,
"type": "wait",
"duration": 60
}Step types
wait, wait_if_notified, notify_persons, notify_person_next_each_time, notify_on_call_from_schedule, notify_next_on_call_from_schedule, notify_previous_on_call_from_schedule, notify_on_call_from_schedule_next_each_time, notify_user_group, notify_team_members, notify_team_members_next_each_time, trigger_webhook, resolve, notify_whole_channel, notify_if_time_from_to, notify_if_num_alerts_in_window, repeat_escalation, declare_incident,
pause_until_team_working_hours.
wait_if_notified waits for duration only if a previous step notified at least one user since the last wait step
(or since the start of the escalation). Otherwise escalation moves on to the next step immediately.
A notify_user_group step counts if the group has at least one member linked to a Grafana IRM user.
notify_whole_channel doesn’t count.
Schedule notification types
All schedule notification types require the notify_on_call_from_schedule parameter with a schedule ID:
notify_on_call_from_schedule: Notifies the user currently on-call from the specified schedule.notify_next_on_call_from_schedule: Notifies all users from the next upcoming on-call shift in the specified schedule. If there is no next shift within the lookahead window (14 days), the step is skipped and escalation continues.notify_previous_on_call_from_schedule: Notifies all users from the most recently ended on-call shift in the specified schedule. With overlapping or staggered rotations, that shift may have ended after the current shift started, and its users may still be on-call. If no shift has ended within the lookback window (14 days), the step is skipped and escalation continues.notify_on_call_from_schedule_next_each_time: Notifies one of the users currently on-call from the specified schedule, moving to the next of those users each time the step runs (round-robin). Users are notified in the order they appear in the schedule, starting with the rotation that began first. If nobody is on call, the step is skipped and escalation continues. Use Advance round-robin position to move the pointer without running an escalation.
Team notification types
All team notification types require the team_to_notify parameter with a team ID:
notify_team_members: Notifies every member of the specified team.notify_team_members_next_each_time: Notifies one member of the specified team, moving to the next member each time the step runs (round-robin). Members are sorted alphabetically by their username, and members without permission to receive notifications are left out. Team membership is read when the step runs, so members added to or removed from the team are picked up automatically. If the team has no members who can be notified, the step is skipped and escalation continues. Use Advance round-robin position to move the pointer without running an escalation.
Team hours step
pause_until_team_working_hours pauses the escalation until the team in team_to_notify is within its team hours, then
continues with the next step. If the team is already within its hours, or has no team hours, escalation continues
immediately. A request that sets this type without a team returns 400 Bad Request.
To set a team’s hours, use the Team hours HTTP API.
For how the step behaves, refer to Configure team hours.
For example, to add the step at the start of an escalation chain:
curl "{{API_URL}}/api/v1/escalation_policies/" \
--request POST \
--header "Authorization: Bearer meowmeowmeow" \
--header "Content-Type: application/json" \
--header "X-Grafana-URL: https://your-stack.grafana.net" \
--data '{
"escalation_chain_id": "F5JU6KJET33FE",
"position": 0,
"type": "pause_until_team_working_hours",
"team_to_notify": "TI73TDU19W48J"
}'HTTP request
POST {{API_URL}}/api/v1/escalation_policies/
Get an escalation policy
Required permission: grafana-irm-app.escalation-chains:read
curl "{{API_URL}}/api/v1/escalation_policies/E3GA6SJETWWJS/" \
--request GET \
--header "Authorization: Bearer meowmeowmeow" \
--header "Content-Type: application/json" \
--header "X-Grafana-URL: https://your-stack.grafana.net"The above command returns JSON structured in the following way:
{
"id": "E3GA6SJETWWJS",
"escalation_chain_id": "F5JU6KJET33FE",
"position": 0,
"type": "wait",
"duration": 60
}Update an escalation policy
Required permission: grafana-irm-app.escalation-chains:write
curl "{{API_URL}}/api/v1/escalation_policies/E3GA6SJETWWJS/" \
--request PUT \
--header "Authorization: Bearer meowmeowmeow" \
--header "Content-Type: application/json" \
--header "X-Grafana-URL: https://your-stack.grafana.net" \
--data '{
"type": "wait",
"duration": 300,
}'The above command returns JSON structured in the following way:
{
"id": "E3GA6SJETWWJS",
"escalation_chain_id": "F5JU6KJET33FE",
"position": 0,
"type": "wait",
"duration": 300
}HTTP request
PUT {{API_URL}}/api/v1/on_call_shifts/<ON_CALL_SHIFT_ID>/
HTTP request
GET {{API_URL}}/api/v1/escalation_policies/<ESCALATION_POLICY_ID>/
List escalation policies
Required permission: grafana-irm-app.escalation-chains:read
curl "{{API_URL}}/api/v1/escalation_policies/" \
--request GET \
--header "Authorization: Bearer meowmeowmeow" \
--header "Content-Type: application/json" \
--header "X-Grafana-URL: https://your-stack.grafana.net"The above command returns JSON structured in the following way:
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"id": "E3GA6SJETWWJS",
"escalation_chain_id": "F5JU6KJET33FE",
"position": 0,
"type": "wait",
"duration": 60
},
{
"id": "E5JJTU52M5YM4",
"escalation_chain_id": "F5JU6KJET33FE",
"position": 1,
"type": "notify_person_next_each_time",
"persons_to_notify_next_each_time": ["U4DNY931HHJS5"]
}
],
"current_page_number": 1,
"page_size": 50,
"total_pages": 1
}Note: The response is paginated. You may need to make multiple requests to get all records.
The following available filter parameter should be provided as a GET argument:
escalation_chain_id
HTTP request
GET {{API_URL}}/api/v1/escalation_policies/
Advance round-robin position
Required permission: grafana-irm-app.escalation-chains:write
For round-robin escalation policies, this endpoint advances the round-robin pointer to the next user in the queue and returns the user that is now current. Supported types:
notify_person_next_each_time: the queue is the policy’spersons_to_notify_next_each_timelist.notify_on_call_from_schedule_next_each_time: the queue is whoever is on call in the policy’s schedule at the moment of the request. Because the queue is time-dependent, advancing during an uncovered slot returns400 Bad Request, and the user the pointer lands on may have rotated off the schedule before the next alert group escalates. When that happens the step starts again from the first user on call.notify_team_members_next_each_time: the queue is the members of the policy’s team at the moment of the request, sorted by username. Members who can’t receive notifications are left out. Advancing when the team has no members who can be notified returns400 Bad Request.
curl "{{API_URL}}/api/v1/escalation_policies/E5JJTU52M5YM4/advance_round_robin/" \
--request POST \
--header "Authorization: Bearer meowmeowmeow" \
--header "Content-Type: application/json" \
--header "X-Grafana-URL: https://your-stack.grafana.net"The above command returns JSON structured in the following way:
{
"user_id": "U4DNY931HHJS5",
"username": "alice"
}Returns 400 Bad Request if the policy is not a round-robin step or if the round-robin queue has no users (for a
schedule step, this includes nobody being on call at the time of the request; for a team step, this includes the team
having no members who can be notified).
HTTP request
POST {{API_URL}}/api/v1/escalation_policies/<ESCALATION_POLICY_ID>/advance_round_robin/
Delete an escalation policy
Required permission: grafana-irm-app.escalation-chains:write
curl "{{API_URL}}/api/v1/escalation_policies/E3GA6SJETWWJS/" \
--request DELETE \
--header "Authorization: Bearer meowmeowmeow" \
--header "Content-Type: application/json" \
--header "X-Grafana-URL: https://your-stack.grafana.net"HTTP request
DELETE {{API_URL}}/api/v1/escalation_policies/<ESCALATION_POLICY_ID>/

