--- title: "Escalation chains HTTP API | Grafana Cloud documentation" description: "Escalation chains HTTP API Create an escalation chain Required permission: grafana-irm-app.escalation-chains:write shell Copy curl \"{{API_URL}}/api/v1/escalation_chains/\" \\ --request POST \\ --header \"Authorization: Bearer meowmeowmeow\" \\ --header \"Content-Type: application/json\" \\ --header \"X-Grafana-URL: https://your-stack.grafana.net\" \\ --data '{ \"name\": \"example-chain\" }' 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 chains HTTP API ## Create an escalation chain **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_chains/" \ --request POST \ --header "Authorization: Bearer meowmeowmeow" \ --header "Content-Type: application/json" \ --header "X-Grafana-URL: https://your-stack.grafana.net" \ --data '{ "name": "example-chain" }' ``` 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": "FWDL7M6N6I9HE", "name": "example-chain", "team_id": null } ``` Expand table | Parameter | Required | Description | |-----------|----------|------------------------------| | name | yes | Name of the escalation chain | | team\_id | no | ID of the team | **HTTP request** `POST {{API_URL}}/api/v1/escalation_chains/` ## Get an escalation chain **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_chains/F5JU6KJET33FE/" \ --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": "F5JU6KJET33FE", "name": "default", "team_id": null } ``` **HTTP request** `GET {{API_URL}}/api/v1/escalation_chains//` ## List escalation chains **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_chains/" \ --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": "F5JU6KJET33FE", "name": "default", "team_id": null } ], "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. **HTTP request** `GET {{API_URL}}/api/v1/escalation_chains/` ## Get current on-call users for an escalation chain **Required permission**: `grafana-irm-app.escalation-chains:read` Returns the users who would be notified by a given escalation chain based on its current policies. This walks all user-resolving escalation policy steps (schedule notifications, explicit user lists, team member notifications, Slack user group notifications, and round-robin queues) and returns the resolved users with their phone number, phone number status, and shift timing (when schedule-based). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/escalation_chains/F5JU6KJET33FE/current_oncall/" \ --request GET \ --header "Authorization: Bearer meowmeowmeow" \ --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, "users": [ { "id": "U4DNY931HHJS5", "grafana_id": 456, "email": "alice@example.com", "slack": { "user_id": "UALICESLACKID", "team_id": "TSLACKTEAMID" }, "username": "alice", "role": "admin", "is_phone_number_verified": true, "phone_number": "+12345678901", "phone_number_status": "available", "timezone": "America/New_York", "teams": ["TAAM1K1NNEHAG"] }, { "id": "U7S8H84ARFTGN", "grafana_id": 789, "email": "bob@example.com", "slack": null, "username": "bob", "role": "editor", "is_phone_number_verified": false, "phone_number": null, "phone_number_status": "not_configured", "timezone": "UTC", "teams": [] } ], "shifts": [ { "schedule_id": "SBM7DV7BKFUYU", "schedule_name": "Primary Rotation", "team_id": "TAAM1K1NNEHAG", "shift_start": "2026-03-24T09:00:00+00:00", "shift_end": "2026-03-25T09:00:00+00:00", "users": ["U4DNY931HHJS5", "U7S8H84ARFTGN"] } ] } ``` Expand table | Parameter | Description | |-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `slack` | A Slack user identity (`user_id`, `team_id`), or `null` if not connected. | | `timezone` | The user’s timezone (e.g. `America/New_York`), or `null`. | | `teams` | List of team IDs the user belongs to. | | `phone_number` | The user’s verified phone number, or `null` if not configured or private. | | `phone_number_status` | One of: `available` (number returned), `private` (user has hidden their number), `not_configured` (user has no verified number). | | `shifts` | List of shift entries with schedule reference (`schedule_id`, `schedule_name`, `team_id`) and timing (`shift_start`, `shift_end`). Empty when the resolving steps are not schedule-based. | > Note > > This endpoint resolves users from all escalation policy steps before the first “Wait” step, mirroring how the escalation engine fires all consecutive non-wait steps together. For round-robin steps, this is a read-only operation, which returns who would be notified next without advancing the pointer. Use the [advance round-robin endpoint](/docs/grafana-cloud/alerting-and-irm/irm/reference/oncall-api/escalation_policies/) to explicitly advance the round-robin position. **HTTP request** `GET {{API_URL}}/api/v1/escalation_chains//current_oncall/` ## Get previous on-call users for an escalation chain **Required permission**: `grafana-irm-app.escalation-chains:read` Returns the users who were on-call during the most recently completed shift for the first schedule-referencing policy step in the escalation chain. Only schedule-based steps have temporal meaning; chains with only non-schedule steps return an empty result. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/escalation_chains/F5JU6KJET33FE/previous_oncall/" \ --request GET \ --header "Authorization: Bearer meowmeowmeow" \ --header "X-Grafana-URL: https://your-stack.grafana.net" ``` The response format is identical to `current_oncall`. Expand table | Query Parameter | Required | Default | Description | |-----------------|----------|---------|-----------------------------------------------------------------| | `days` | No | `7` | Number of days to look back for past shifts. Maximum value: 30. | **HTTP request** `GET {{API_URL}}/api/v1/escalation_chains//previous_oncall/` ## Get next on-call users for an escalation chain **Required permission**: `grafana-irm-app.escalation-chains:read` Returns the users who will be on-call during the next upcoming shift for the first schedule-referencing policy step in the escalation chain. Shifts that overlap with the current time are skipped. Chains with only non-schedule steps return an empty result. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/escalation_chains/F5JU6KJET33FE/next_oncall/" \ --request GET \ --header "Authorization: Bearer meowmeowmeow" \ --header "X-Grafana-URL: https://your-stack.grafana.net" ``` The response format is identical to `current_oncall`. Expand table | Query Parameter | Required | Default | Description | |-----------------|----------|---------|--------------------------------------------------------------------| | `days` | No | `7` | Number of days to look ahead for future shifts. Maximum value: 30. | **HTTP request** `GET {{API_URL}}/api/v1/escalation_chains//next_oncall/` ## Delete an escalation chain **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_chains/F5JU6KJET33FE/" \ --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_chains//`