---
title: "Escalation policies HTTP API | Grafana Cloud documentation"
description: "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:"
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Escalation policies HTTP API

## Create an escalation policy

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

shell ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```shell
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 code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

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

Expand table

| Parameter                          | Required                                                 | Description                                                                                                                   |
|------------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
| `escalation_chain_id`              | Yes                                                      | Each escalation policy is assigned to a specific escalation chain.                                                            |
| `position`                         | Optional                                                 | Escalation policies execute one after another starting from `position=0`. `Position=-1` puts the policy at the end.           |
| `type`                             | Yes                                                      | See **Step types** below.                                                                                                     |
| `important`                        | Optional                                                 | Default `false`. Uses “important” notification rules. Applicable for user/schedule/group notification types.                  |
| `duration`                         | If type = `wait` or `wait_if_notified`                   | Duration in seconds (60-86400).                                                                                               |
| `action_to_trigger`                | If type = `trigger_webhook`                              | ID of a webhook.                                                                                                              |
| `group_to_notify`                  | If type = `notify_user_group`                            | ID of a User Group.                                                                                                           |
| `persons_to_notify`                | If type = `notify_persons`                               | List of user IDs.                                                                                                             |
| `persons_to_notify_next_each_time` | If type = `notify_person_next_each_time`                 | List of user IDs.                                                                                                             |
| `notify_on_call_from_schedule`     | If type = `notify_*_from_schedule`                       | ID of a Schedule. See **Schedule notification types** below.                                                                  |
| `notify_on_call_from_schedules`    | If type = `notify_on_call_from_schedules_next_each_time` | List of schedule IDs, at least one. See **Schedule notification types** below.                                                |
| `notify_if_time_from`              | If type = `notify_if_time_from_to`                       | UTC time for period start, e.g. `09:00:00Z`.                                                                                  |
| `notify_if_time_to`                | If type = `notify_if_time_from_to`                       | UTC time for period end, e.g. `18:00:00Z`.                                                                                    |
| `num_alerts_in_window`             | If type = `notify_if_num_alerts_in_window`               | Number of alerts required to continue escalation.                                                                             |
| `num_minutes_in_window`            | If type = `notify_if_num_alerts_in_window`               | Time window in minutes.                                                                                                       |
| `team_to_notify`                   | If type = `notify_team_members*`                         | ID of a team. Also required if type = `pause_until_team_hours`. Refer to **Team notification types** and **Team hours step**. |
| `severity`                         | If type = `declare_incident`                             | Severity of the incident.                                                                                                     |

**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_on_call_from_schedules_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_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 except `notify_on_call_from_schedules_next_each_time` 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](https://grafana.com/docs/grafana-cloud/observe-and-act/respond-to-incidents/reference/oncall-api/escalation_policies/#advance-round-robin-position) to move the pointer without running an escalation.

`notify_on_call_from_schedules_next_each_time` requires the `notify_on_call_from_schedules` parameter with a list of schedule IDs instead. It notifies everyone currently on-call in one of those schedules, moving to the next schedule each time the step runs (round-robin). Schedules are used in alphabetical order by name, and schedules with nobody on call are skipped. If nobody is on call in any of the schedules, the step is skipped and escalation continues.

**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](https://grafana.com/docs/grafana-cloud/observe-and-act/respond-to-incidents/reference/oncall-api/escalation_policies/#advance-round-robin-position) to move the pointer without running an escalation.

**Team hours step**

`pause_until_team_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](https://grafana.com/docs/grafana-cloud/observe-and-act/respond-to-incidents/reference/oncall-api/team_hours). For how the step behaves, refer to [Configure team hours](https://grafana.com/docs/grafana-cloud/observe-and-act/respond-to-incidents/escalation-and-routing/team-hours/#pause-an-escalation-until-team-hours).

For example, to add the step at the start of an escalation chain:

shell ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```shell
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_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`

shell ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```shell
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 code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "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 code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```shell
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 code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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-irm-app.escalation-chains:read`

shell ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```shell
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 code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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](https://grafana.com/docs/grafana-cloud/observe-and-act/respond-to-incidents/reference/oncall-api/#pagination). 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 (for `notify_on_call_from_schedules_next_each_time`, the next schedule, as described below). 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.
- `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 returns `400 Bad Request`.
- `notify_on_call_from_schedules_next_each_time`: the pointer moves to the next of the policy’s schedules, by name, that has someone on call at the moment of the request. Advancing when nobody is on call in any of the schedules returns `400 Bad Request`. The response describes the schedule instead of a single user:
  
  JSON ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy
  
  ```json
  {
    "schedule_id": "SBM7DV7BKFUYU",
    "schedule_name": "Team A primary",
    "users": [{ "user_id": "U4DNY931HHJS5", "username": "alice" }]
  }
  ```

shell ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```shell
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 code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "user_id": "U4DNY931HHJS5",
  "username": "alice"
}
```

Expand table

| Parameter  | Description                                               |
|------------|-----------------------------------------------------------|
| `user_id`  | Public ID of the user now at the head of the round-robin. |
| `username` | Username of the user.                                     |

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`

shell ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

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