Escalation HTTP API
Required permission: grafana-oncall-app.alert-groups:direct-paging
(user authentication only)
See Manual paging integration for more background on how escalating to a team or user(s) works.
Escalate to a set of users
For more details about how to fetch a user’s Grafana OnCall ID, refer to the Users public API documentation.
curl "{{API_URL}}/api/v1/escalation/" \
--request POST \
--header "Authorization: meowmeowmeow" \
--header "Content-Type: application/json" \
--data '{
"title": "We are seeing a network outage in the datacenter",
"message": "I need help investigating, can you join the investigation?",
"source_url": "https://github.com/myorg/myrepo/issues/123",
"users": [
{
"id": "U281SN24AVVJX",
"important": false
},
{
"id": "U5AKCVNDEDUE7",
"important": true
}
]
}'
The above command returns JSON structured in the following way:
{
"id": "IZHCC4GTNPZ93",
"integration_id": "CC3GZYZNIIEH5",
"route_id": "RDN8LITALJXCJ",
"alerts_count": 1,
"state": "firing",
"created_at": "2024-08-15T18:05:36.801215Z",
"resolved_at": null,
"resolved_by": null,
"acknowledged_at": null,
"acknowledged_by": null,
"title": "We're seeing a network outage in the datacenter",
"permalinks": {
"slack": null,
"slack_app": null,
"telegram": null,
"web": "http://<my_grafana_url>/a/grafana-oncall-app/alert-groups/I5LAZ2MXGPUAH"
},
"silenced_at": null
}
Escalate to a team
For more details about how to fetch a team’s Grafana OnCall ID, refer to the Teams public API documentation.
curl "{{API_URL}}/api/v1/escalation/" \
--request POST \
--header "Authorization: meowmeowmeow" \
--header "Content-Type: application/json" \
--data '{
"title": "We are seeing a network outage in the datacenter",
"message": "I need help investigating, can you join the investigation?",
"source_url": "https://github.com/myorg/myrepo/issues/123",
"team": "TI73TDU19W48J",
"important_team_escalation": true
}'
The above command returns JSON structured in the following way:
{
"id": "IZHCC4GTNPZ93",
"integration_id": "CC3GZYZNIIEH5",
"route_id": "RDN8LITALJXCJ",
"alerts_count": 1,
"state": "firing",
"created_at": "2024-08-15T18:05:36.801215Z",
"resolved_at": null,
"resolved_by": null,
"acknowledged_at": null,
"acknowledged_by": null,
"title": "We're seeing a network outage in the datacenter",
"permalinks": {
"slack": null,
"slack_app": null,
"telegram": null,
"web": "http://<my_grafana_url>/a/grafana-oncall-app/alert-groups/I5LAZ2MXGPUAH"
},
"silenced_at": null
}
Escalate to a set of user(s) for an existing Alert Group
The following shows how you can escalate to a set of user(s) for an existing Alert Group.
curl "{{API_URL}}/api/v1/escalation/" \
--request POST \
--header "Authorization: meowmeowmeow" \
--header "Content-Type: application/json" \
--data '{
"alert_group_id": "IZMRNNY8RFS94",
"users": [
{
"id": "U281SN24AVVJX",
"important": false
},
{
"id": "U5AKCVNDEDUE7",
"important": true
}
]
}'
The above command returns JSON structured in the following way:
{
"id": "IZHCC4GTNPZ93",
"integration_id": "CC3GZYZNIIEH5",
"route_id": "RDN8LITALJXCJ",
"alerts_count": 1,
"state": "firing",
"created_at": "2024-08-15T18:05:36.801215Z",
"resolved_at": null,
"resolved_by": null,
"acknowledged_at": null,
"acknowledged_by": null,
"title": "We're seeing a network outage in the datacenter",
"permalinks": {
"slack": null,
"slack_app": null,
"telegram": null,
"web": "http://<my_grafana_url>/a/grafana-oncall-app/alert-groups/I5LAZ2MXGPUAH"
},
"silenced_at": null
}
Things to note
team
andusers
are mutually exclusive in the request payload. If you would like to escalate to a team AND user(s), first escalate to a team, then using the Alert Group ID returned in the response payload, add the required users to the existing Alert Groupalert_group_id
is mutually exclusive withtitle
,message
, andsource_url
. Practically speaking this means that if you are trying to escalate to a set of users on an existing Alert Group, you cannot update thetitle
,message
, orsource_url
of that Alert Group- If escalating to a set of users for an existing Alert Group, the Alert Group cannot be in a resolved state
- Regarding
important_team_escalation
; this can be useful to send an “important” escalation to the specified team. Teams can configure their Direct Paging Integration to route to different escalation chains based on the value ofpayload.oncall.important
. See Manual paging integration - important escalations for more details.
HTTP request
POST {{API_URL}}/api/v1/escalation/