Escalation HTTP API
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"
}'
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
}
Parameter | Unique | Required | Description |
---|---|---|---|
title | No | No | Name of the Alert Group that will be created |
message | No | No | Content of the Alert Group that will be created |
source_url | No | No | Value that will be added in the Alert’s payload as oncall.permalink . This can be useful to have the source URL/button autopopulated with a URL of interest. |
team | No | Yes (see Things to Note) | Grafana OnCall team ID. If specified, will use the “Direct Paging” Integration associated with this Grafana OnCall team, to create the Alert Group. |
users | No | Yes (see Things to Note) | List of user(s) to escalate to. See above request example for object schema. id represents the Grafana OnCall user’s ID. important is a boolean representing whether to escalate the Alert Group using this user’s default or important personal notification policy. |
alert_group_id | No | No | If specified, will escalate the specified users for this Alert Group. |
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
HTTP request
POST {{API_URL}}/api/v1/escalation/