--- canonical: https://grafana.com/docs/oncall/latest/oncall-api-reference/escalation/ title: Escalation HTTP API weight: 0 refs: users: - pattern: /docs/oncall/ destination: /docs/oncall//oncall-api-reference/users - pattern: /docs/grafana-cloud/ destination: /docs/grafana-cloud/alerting-and-irm/oncall/oncall-api-reference/users teams: - pattern: /docs/oncall/ destination: /docs/oncall//oncall-api-reference/teams - pattern: /docs/grafana-cloud/ destination: /docs/grafana-cloud/alerting-and-irm/oncall/oncall-api-reference/teams manual-paging: - pattern: /docs/oncall/ destination: /docs/oncall//configure/integrations/references/manual - pattern: /docs/grafana-cloud/ destination: /docs/grafana-cloud/configure/integrations/references/manual --- # Escalation HTTP API See [Manual paging integration](ref:manual-paging) 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](ref:users) public API documentation. ```shell 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: ```json { "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:///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](ref:teams) public API documentation. ```shell 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: ```json { "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:///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. ```shell 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: ```json { "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:///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](#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](#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/`