oncall-engine/docs/sources/oncall-api-reference/escalation.md

canonical	title	weight	refs
https://grafana.com/docs/oncall/latest/oncall-api-reference/escalation/	Escalation HTTP API	0	users teams manual-paging pattern destination /docs/oncall/ /docs/oncall/<ONCALL_VERSION>/oncall-api-reference/users pattern destination /docs/grafana-cloud/ /docs/grafana-cloud/alerting-and-irm/oncall/oncall-api-reference/users pattern destination /docs/oncall/ /docs/oncall/<ONCALL_VERSION>/oncall-api-reference/teams pattern destination /docs/grafana-cloud/ /docs/grafana-cloud/alerting-and-irm/oncall/oncall-api-reference/teams pattern destination /docs/oncall/ /docs/oncall/<ONCALL_VERSION>/configure/integrations/references/manual pattern destination /docs/grafana-cloud/ /docs/grafana-cloud/configure/integrations/references/manual

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 and users 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 Group
• alert_group_id is mutually exclusive with title, message, and source_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 the title, message, or source_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/