Caution

As of 2026-03-24, the Grafana OnCall OSS project is archived. The grafana/oncall repository is read-only, and active development continues in Grafana Cloud IRM. For a fully supported and actively maintained alternative, Grafana Cloud IRM offers a modern approach to incident response and on-call management.

Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Documentationbreadcrumb arrow OnCallbreadcrumb arrow API referencebreadcrumb arrow Escalation policies HTTP API
Open source

Escalation policies HTTP API

Create an escalation policy

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

shell 
curl "{{API_URL}}/api/v1/escalation_policies/" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
      "escalation_chain_id": "F5JU6KJET33FE",
      "type": "wait",
      "duration": 60
  }'

The above command returns JSON structured in the following way:

JSON 
{
  "id": "E3GA6SJETWWJS",
  "escalation_chain_id": "F5JU6KJET33FE",
  "position": 0,
  "type": "wait",
  "duration": 60
}
ParameterRequiredDescription
escalation_chain_idYesEach escalation policy is assigned to a specific escalation chain.
positionOptionalEscalation policies execute one after another starting from position=0. Position=-1 will put the escalation policy to the end of the list. A new escalation policy created with a position of an existing escalation policy will move the old one (and all following) down in the list.
typeYesOne of: wait, notify_persons, notify_person_next_each_time, notify_on_call_from_schedule, notify_user_group, trigger_webhook, resolve, notify_whole_channel, notify_if_time_from_to, declare_incident.
importantOptionalDefault is false. Will assign “important” to personal notification rules if true. This can be used to distinguish alerts on which you want to be notified immediately by phone. Applicable for types notify_persons, notify_person_next_each_time, notify_team_members, notify_on_call_from_schedule, and notify_user_group.
durationIf type = waitThe duration, in seconds, when type wait is chosen. Valid values are any number of seconds in the inclusive range 60 to 86400.
action_to_triggerIf type = trigger_webhookID of a webhook.
group_to_notifyIf type = notify_user_groupID of a User Group.
persons_to_notifyIf type = notify_personsList of user IDs.
persons_to_notify_next_each_timeIf type = notify_person_next_each_timeList of user IDs.
notify_on_call _from_scheduleIf type = notify_on_call_from_scheduleID of a Schedule.
notify_if_time_fromIf type = notify_if_time_from_toUTC time represents the beginning of the time period, for example 09:00:00Z.
notify_if_time_toIf type = notify_if_time_from_toUTC time represents the end of the time period, for example 18:00:00Z.
team_to_notifyIf type = notify_team_membersID of a team.
severityIf type = declare_incidentSeverity of the incident.

HTTP request

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

Get an escalation policy

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

shell 
curl "{{API_URL}}/api/v1/escalation_policies/E3GA6SJETWWJS/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \

The above command returns JSON structured in the following way:

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

Update an escalation policy

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

shell 
curl "{{API_URL}}/api/v1/escalation_policies/E3GA6SJETWWJS/" \
  --request PUT \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "wait",
    "duration": 300,
  }'

The above command returns JSON structured in the following way:

JSON 
{
  "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-oncall-app.escalation-chains:read

shell 
curl "{{API_URL}}/api/v1/escalation_policies/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

The above command returns JSON structured in the following way:

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

Delete an escalation policy

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

shell 
curl "{{API_URL}}/api/v1/escalation_policies/E3GA6SJETWWJS/" \
  --request DELETE \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

HTTP request

DELETE {{API_URL}}/api/v1/escalation_policies/<ESCALATION_POLICY_ID>/