--- 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](/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](/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` | 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_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. | | `severity` | If type = `declare_incident` | Severity of the incident. | **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](#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 code to clipboard](/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](/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](/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](/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//` **HTTP request** `GET {{API_URL}}/api/v1/escalation_policies//` ## List escalation policies **Required permission**: `grafana-irm-app.escalation-chains:read` shell ![Copy code to clipboard](/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](/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](/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. 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 code to clipboard](/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](/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). **HTTP request** `POST {{API_URL}}/api/v1/escalation_policies//advance_round_robin/` ## Delete an escalation policy **Required permission**: `grafana-irm-app.escalation-chains:write` shell ![Copy code to clipboard](/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//`