Documentation Grafana Cloud Observe and act Manage on-call and incidents Reference OnCall API Escalation policies API

Escalation policies HTTP API

Create an escalation policy

Required permission: grafana-irm-app.escalation-chains:write

shell Copy

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:

JSON Copy

{
  "id": "E3GA6SJETWWJS",
  "escalation_chain_id": "F5JU6KJET33FE",
  "position": 0,
  "type": "wait",
  "duration": 60
}

Step types

wait, 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, trigger_webhook, resolve, notify_whole_channel, notify_if_time_from_to, notify_if_num_alerts_in_window, repeat_escalation, declare_incident.

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.

HTTP request

POST {{API_URL}}/api/v1/escalation_policies/

Get an escalation policy

Required permission: grafana-irm-app.escalation-chains:read

shell Copy

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:

JSON Copy

{
  "id": "E3GA6SJETWWJS",
  "escalation_chain_id": "F5JU6KJET33FE",
  "position": 0,
  "type": "wait",
  "duration": 60
}

Update an escalation policy

Required permission: grafana-irm-app.escalation-chains:write

shell Copy

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:

JSON Copy

{
  "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

shell Copy

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:

JSON Copy

{
  "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’s persons_to_notify_next_each_time list.
• 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 returns 400 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.

shell Copy

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:

JSON Copy

{
  "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).

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

shell Copy

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>/