--- title: "Escalation HTTP API | Grafana Cloud documentation" description: "Escalation HTTP API Required permission: grafana-irm-app.alert-groups:direct-paging Refer to Manual paging integration for more background on how escalating to a team or users 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." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Escalation HTTP API **Required permission**: `grafana-irm-app.alert-groups:direct-paging` Refer to [Manual paging integration](/docs/grafana-cloud/observe-and-act/respond-to-incidents/irm/integrations/alert-sources/manual) for more background on how escalating to a team or users works. ## Escalate to a set of users For more details about how to fetch a user’s Grafana OnCall ID, refer to the [Users](/docs/grafana-cloud/observe-and-act/respond-to-incidents/irm/reference/oncall-api/users) public API documentation. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/escalation/" \ --request POST \ --header "Authorization: Bearer meowmeowmeow" \ --header "Content-Type: application/json" \ --header "X-Grafana-URL: https://your-stack.grafana.net" \ --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 } ], "metadata": { "service": "payments_service", "zoom_meeting_link": "https://zoom.us/j/123456789?pwd=abc123xyz" } }' ``` ### Using usernames instead of IDs You can also reference users by their username instead of their Grafana OnCall ID: shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/escalation/" \ --request POST \ --header "Authorization: Bearer meowmeowmeow" \ --header "Content-Type: application/json" \ --header "X-Grafana-URL: https://your-stack.grafana.net" \ --data '{ "title": "We are seeing a network outage in the datacenter", "message": "I need help investigating, can you join the investigation?", "users": [ { "username": "alice", "important": false }, { "username": "bob", "important": true } ] }' ``` You can mix `id` and `username` in the same request, but each user entry must use only one identifier. The above command returns JSON structured in the following way: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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-irm-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](/docs/grafana-cloud/observe-and-act/respond-to-incidents/irm/reference/oncall-api/teams) public API documentation. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/escalation/" \ --request POST \ --header "Authorization: Bearer meowmeowmeow" \ --header "Content-Type: application/json" \ --header "X-Grafana-URL: https://your-stack.grafana.net" \ --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, "metadata": { "service": "payments_service", "zoom_meeting_link": "https://zoom.us/j/123456789?pwd=abc123xyz" } }' ``` ### Using team name instead of ID You can also reference a team by its name instead of its Grafana OnCall ID: shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/escalation/" \ --request POST \ --header "Authorization: Bearer meowmeowmeow" \ --header "Content-Type: application/json" \ --header "X-Grafana-URL: https://your-stack.grafana.net" \ --data '{ "title": "We are seeing a network outage in the datacenter", "message": "I need help investigating, can you join the investigation?", "team_name": "Platform Team", "important_team_escalation": true }' ``` The above command returns JSON structured in the following way: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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-irm-app/alert-groups/I5LAZ2MXGPUAH" }, "silenced_at": null } ``` ## Escalate with incident context When paging users or teams from within an incident, you can include an `incident_id` to link the escalation to the incident. This enables paged responders to appear in the incident’s “Paged Participants” section and timeline. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/escalation/" \ --request POST \ --header "Authorization: Bearer meowmeowmeow" \ --header "Content-Type: application/json" \ --header "X-Grafana-URL: https://your-stack.grafana.net" \ --data '{ "title": "Production Database Outage", "message": "You have been paged for an incident", "users": [ { "username": "alice", "important": true } ], "incident_id": "INC-123" }' ``` When `incident_id` is provided: 1. The alert group’s `grafana_incident_id` is set to the incident ID 2. An incident reference is added, populating the “Paged Participants” UI section 3. A timeline activity is created showing who was paged 4. An incident context entry is added to the “Links and context” tab > Note > > Incident API failures are logged but do not fail the escalation. The primary paging operation always succeeds first. ## 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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/escalation/" \ --request POST \ --header "Authorization: Bearer meowmeowmeow" \ --header "Content-Type: application/json" \ --header "X-Grafana-URL: https://your-stack.grafana.net" \ --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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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-irm-app/alert-groups/I5LAZ2MXGPUAH" }, "silenced_at": null } ``` ## Parameters Expand table | 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. | | `team_name` | No | Yes (see [Things to Note](#things-to-note)) | Team name (alternative to `team`). If specified, will look up the team by name. | | `users` | No | Yes (see [Things to Note](#things-to-note)) | List of user(s) to escalate to. Each user object requires either `id` (Grafana OnCall user ID) or `username`, plus an `important` boolean for notification policy selection. | | `users[].id` | No | Yes (or `username`) | Grafana OnCall user ID. | | `users[].username` | No | Yes (or `id`) | Username (alternative to `id`). If specified, will look up the user by username. | | `users[].important` | No | Yes | Boolean representing whether to escalate 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. | | `important_team_escalation` | No | No | Sets the value of `payload.oncall.important` to the value specified here (default is `False`; see [Things to Note](#things-to-note) for more details). | | `metadata` | No | No | Dictionary of structured data that gets included in the alert payload as `metadata`. Useful for including additional context, labels, and other structured information that can be used in alert templates. | | `incident_id` | No | No | Incident ID (e.g., “INC-123”). If provided, links the escalation to the specified incident. See [Escalate with incident context](#escalate-with-incident-context) for details. | ## Things to note - `team` and `team_name` are mutually exclusive. Use one or the other to identify the team. - `id` and `username` are mutually exclusive within each user object. Use one or the other to identify each user. - `team`/`team_name` 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 - If you specify `users` without a `team`/`team_name`, the request pages only those users. Your default (current) team is **not** implicitly added, so you no longer need to pass `"team": null` to page users when you have a default team set - `alert_group_id` is mutually exclusive with `title`, `message`, `source_url`, and `incident_id`. 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`, `source_url`, or link to an incident for 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 of `payload.oncall.important`. Refer to [Manual paging integration - important escalations](/docs/grafana-cloud/observe-and-act/respond-to-incidents/irm/integrations/alert-sources/manual) for more details. **HTTP request** `POST {{API_URL}}/api/v1/escalation/`