--- 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_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** Both 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. **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/alerting-and-irm/irm/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 escalation policies of type `notify_person_next_each_time` (round-robin), this endpoint advances the round-robin pointer to the next user in the queue and returns the user that is now current. 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. **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//`