Escalation chains HTTP API
Create an escalation chain
Required permission: grafana-irm-app.escalation-chains:write
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:
{
"id": "FWDL7M6N6I9HE",
"name": "example-chain",
"team_id": null
}HTTP request
POST {{API_URL}}/api/v1/escalation_chains/
Get an escalation chain
Required permission: grafana-irm-app.escalation-chains:read
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:
{
"id": "F5JU6KJET33FE",
"name": "default",
"team_id": null
}HTTP request
GET {{API_URL}}/api/v1/escalation_chains/<ESCALATION_CHAIN_ID>/
List escalation chains
Required permission: grafana-irm-app.escalation-chains:read
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:
{
"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. 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).
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:
{
"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"]
}
]
}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 to explicitly advance the round-robin position.
HTTP request
GET {{API_URL}}/api/v1/escalation_chains/<ESCALATION_CHAIN_ID>/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.
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.
HTTP request
GET {{API_URL}}/api/v1/escalation_chains/<ESCALATION_CHAIN_ID>/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.
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.
HTTP request
GET {{API_URL}}/api/v1/escalation_chains/<ESCALATION_CHAIN_ID>/next_oncall/
Delete an escalation chain
Required permission: grafana-irm-app.escalation-chains:write
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/<ESCALATION_CHAIN_ID>/
