--- title: "Alert groups HTTP API | Grafana Cloud documentation" description: "Alert groups HTTP API List alert groups Required permission: grafana-irm-app.alert-groups:read shell Copy curl \"{{API_URL}}/api/v1/alert_groups/\" \\ --request GET \\ --header \"Authorization: Bearer meowmeowmeow\" \\ --header \"Content-Type: application/json\" \\ --header \"X-Grafana-URL: https://your-stack.grafana.net\" The above command returns JSON structured in the following way:" --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Alert groups HTTP API ## List alert groups **Required permission**: `grafana-irm-app.alert-groups:read` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/alert_groups/" \ --request GET \ --header "Authorization: Bearer meowmeowmeow" \ --header "Content-Type: application/json" \ --header "X-Grafana-URL: https://your-stack.grafana.net" ``` 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 { "count": 1, "next": null, "previous": null, "results": [ { "id": "I68T24C13IFW1", "integration_id": "CFRPV98RPR1U8", "route_id": "RIYGUJXCPFHXY", "alerts_count": 3, "state": "resolved", "created_at": "2020-05-19T12:37:01.430444Z", "alert_group_number": 42, "resolved_at": "2020-05-19T13:37:01.429805Z", "acknowledged_at": null, "acknowledged_by": null, "resolved_by": "UCGEIXI1MR1NZ", "title": "Memory above 90% threshold", "permalinks": { "slack": "https://ghostbusters.slack.com/archives/C1H9RESGA/p135854651500008", "telegram": "https://t.me/c/5354/1234?thread=1234" }, "silenced_at": "2020-05-19T13:37:01.429805Z", "root_alert_group_id": null, "dependent_alert_group_ids": ["I7XKBQYJYFW3M", "I9LPV30QXJ5KM"], "last_alert": { "id": "AA74DN7T4JQB6", "alert_group_id": "I68T24C13IFW1", "created_at": "2020-05-11T20:08:43Z", "payload": { "state": "alerting", "title": "[Alerting] Test notification", "ruleId": 0, "message": "Someone is testing the alert notification within Grafana.", "ruleUrl": "{{API_URL}}/", "ruleName": "Test notification", "evalMatches": [ { "tags": null, "value": 100, "metric": "High value" }, { "tags": null, "value": 200, "metric": "Higher Value" } ] } } } ], "current_page_number": 1, "page_size": 50, "total_pages": 1 } ``` > **Note**: The response is [paginated](/docs/grafana-cloud/observe-and-act/respond-to-incidents/irm/reference/oncall-api/#pagination). You may need to make multiple requests to get all records. These available filter parameters should be provided as `GET` arguments: - `id` (Exact match, alert group ID) - `route_id` (Exact match, route ID) - `integration_id` (Exact match, integration ID) - `label` (Matching labels, can be passed multiple times; expected format: `key1:value1`) - `search` (Search by alert group title, alert group ID, or alert group number. When used, results are limited to the most recent 30 days within the requested time range.) - `team_id` (Exact match, team ID) - `started_at` (A “{start}\_{end}” ISO 8601 timestamp range; expected format: `%Y-%m-%dT%H:%M:%S_%Y-%m-%dT%H:%M:%S`) If a `started_at` date is not provided the last 30 days will be used. Timezone support is not available. All times must be in UTC; other time zones will cause an error. - `state` (Possible values: `new`, `acknowledged`, `resolved` or `silenced`) **HTTP request** `GET {{API_URL}}/api/v1/alert_groups/` ## Alert group details **Required permission**: `grafana-irm-app.alert-groups:read` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1" \ --request GET \ --header "Authorization: Bearer meowmeowmeow" \ --header "X-Grafana-URL: https://your-stack.grafana.net" ``` **HTTP request** `GET {{API_URL}}/api/v1/alert_groups/` ## Acknowledge an alert group **Required permission**: `grafana-irm-app.alert-groups:write` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/acknowledge" \ --request POST \ --header "Authorization: Bearer meowmeowmeow" \ --header "X-Grafana-URL: https://your-stack.grafana.net" ``` **HTTP request** `POST {{API_URL}}/api/v1/alert_groups//acknowledge` ## Unacknowledge an alert group **Required permission**: `grafana-irm-app.alert-groups:write` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/unacknowledge" \ --request POST \ --header "Authorization: Bearer meowmeowmeow" \ --header "X-Grafana-URL: https://your-stack.grafana.net" ``` **HTTP request** `POST {{API_URL}}/api/v1/alert_groups//unacknowledge` ## Resolve an alert group **Required permission**: `grafana-irm-app.alert-groups:write` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/resolve" \ --request POST \ --header "Authorization: Bearer meowmeowmeow" \ --header "X-Grafana-URL: https://your-stack.grafana.net" ``` **HTTP request** `POST {{API_URL}}/api/v1/alert_groups//resolve` ## Unresolve an alert group **Required permission**: `grafana-irm-app.alert-groups:write` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/unresolve" \ --request POST \ --header "Authorization: Bearer meowmeowmeow" \ --header "X-Grafana-URL: https://your-stack.grafana.net" ``` **HTTP request** `POST {{API_URL}}/api/v1/alert_groups//unresolve` ## Silence an alert group **Required permission**: `grafana-irm-app.alert-groups:write` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/silence" \ --request POST \ --header "Authorization: Bearer meowmeowmeow" \ --header "Content-Type: application/json" \ --header "X-Grafana-URL: https://your-stack.grafana.net" \ --data '{ "delay": 10800 }' ``` **HTTP request** `POST {{API_URL}}/api/v1/alert_groups//silence` Expand table | Parameter | Required | Description | |-----------|----------|--------------------------------------------------------------------------| | `delay` | Yes | The duration of silence in seconds, `-1` for silencing the alert forever | ## Unsilence an alert group **Required permission**: `grafana-irm-app.alert-groups:write` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/unsilence" \ --request POST \ --header "Authorization: Bearer meowmeowmeow" \ --header "X-Grafana-URL: https://your-stack.grafana.net" ``` **HTTP request** `POST {{API_URL}}/api/v1/alert_groups//unsilence` ## Attach an alert group to another alert group **Required permission**: `grafana-irm-app.alert-groups:write` Attaches an alert group as a dependent of another alert group. The attached alert group inherits the acknowledge/silence state of the root alert group and stops its own escalation. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/attach" \ --request POST \ --header "Authorization: Bearer meowmeowmeow" \ --header "Content-Type: application/json" \ --header "X-Grafana-URL: https://your-stack.grafana.net" \ --data '{ "root_alert_group_id": "I5GO9SINNFHSL" }' ``` **HTTP request** `POST {{API_URL}}/api/v1/alert_groups//attach` Expand table | Parameter | Required | Description | |-----------------------|----------|----------------------------------------------------------| | `root_alert_group_id` | Yes | The ID of the alert group to attach to (the root group). | The root alert group must not itself be attached or resolved. The alert group being attached must not be a maintenance alert group, must not already be attached, and must not have any other alert groups attached to it. ## Unattach an alert group **Required permission**: `grafana-irm-app.alert-groups:write` Detaches an alert group that has been attached to another alert group. Escalation resumes for the unattached alert group if it is not acknowledged or resolved. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/unattach" \ --request POST \ --header "Authorization: Bearer meowmeowmeow" \ --header "X-Grafana-URL: https://your-stack.grafana.net" ``` **HTTP request** `POST {{API_URL}}/api/v1/alert_groups//unattach` ## Advance escalation **Required permission**: `grafana-irm-app.alert-groups:write` Advances the escalation for an alert group. If the alert is currently acknowledged, resolved, or silenced, this action clears that state first, then resumes the escalation chain from where it left off. If the escalation is paused at a wait step, it skips past the wait (and any consecutive waits) to trigger the next notification batch immediately. Use this when the escalation is paused at a wait step, or when an acknowledged/resolved/silenced alert group should resume escalation. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/escalate_next/" \ --request POST \ --header "Authorization: meowmeowmeow" \ --header "X-Grafana-URL: https://your-stack.grafana.net" ``` On success, the endpoint returns `200 OK` with an empty body. > Warning > > Calling this on an acknowledged or resolved alert group will change its state back to active (firing) and continue the escalation chain from where it left off. This is different from unacknowledging, which starts the escalation chain over from the beginning. **HTTP request** `POST {{API_URL}}/api/v1/alert_groups//escalate_next/` **Response codes** - `200 OK` - Escalation successfully advanced - `400 Bad Request` - No actionable state (alert is active and not at a wait step, escalation is finished, or no remaining steps) - `403 Forbidden` - Insufficient permissions ## Delete an alert group **Required permission**: `grafana-irm-app.alert-groups:write` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/" \ --request DELETE \ --header "Authorization: Bearer meowmeowmeow" \ --header "Content-Type: application/json" \ --header "X-Grafana-URL: https://your-stack.grafana.net" \ --data '{ "mode": "wipe" }' ``` Expand table | Parameter | Required | Description | |-----------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `mode` | No | The default value for this parameter is `wipe`. Using `wipe` will delete the content of the alert group but keep the metadata, which is helpful if you’ve sent sensitive information to OnCall. On the other hand, passing `delete` will fully erase the alert group and its metadata, as well as delete related messages in Slack and other platforms. | > **NOTE:** `DELETE` can take a few moments to delete alert groups because Grafana OnCall interacts with 3rd party APIs such as Slack. Please check objects using `GET` to be sure the data is removed. **HTTP request** `DELETE {{API_URL}}/api/v1/alert_groups/` ## Add a label to an alert group **Required permission**: `grafana-irm-app.alert-groups:write` Adds a label to a specific alert group. The label key and value must exist. > Note > > **Prerequisites**: Before adding labels to alert groups, you must first create the label keys and values. > Warning > > **Label Limit**: Each alert group can have a maximum of **50 labels**. Attempting to add more labels will result in an error. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/labels/" \ --request POST \ --header "Authorization: Bearer meowmeowmeow" \ --header "Content-Type: application/json" \ --header "X-Grafana-URL: https://your-stack.grafana.net" \ --data '{ "key": { "name": "severity" }, "value": { "name": "critical" } }' ``` 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 { "key": { "id": "severity", "name": "severity" }, "value": { "id": "critical", "name": "critical" } } ``` **HTTP request** `POST {{API_URL}}/api/v1/alert_groups//labels` Expand table | Parameter | Required | Description | |--------------|----------|-----------------------------| | `key` | Yes | The label key object | | `key.name` | Yes | The name of the label key | | `value` | Yes | The label value object | | `value.name` | Yes | The name of the label value | **Response codes** - `201 Created` - Label successfully added to the alert group - `400 Bad Request` - Invalid request data or label validation failed - `403 Forbidden` - Insufficient permissions - `404 Not Found` - Alert group not found **Error responses** - `Label key 'key_name' does not exist` - The specified label key doesn’t exist in the label repository - `Label value 'value_name' does not exist for key 'key_name'` - The specified label value doesn’t exist for the given key - `Label already exists for this alert group` - The label is already associated with the alert group - `Alert group already has the maximum number of labels (50)` - The alert group has reached the maximum number of labels allowed ## Remove a label from an alert group **Required permission**: `grafana-irm-app.alert-groups:write` Removes a specific label from an alert group by key-value combination. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/labels/remove/" \ --request POST \ --header "Authorization: Bearer meowmeowmeow" \ --header "Content-Type: application/json" \ --header "X-Grafana-URL: https://your-stack.grafana.net" \ --data '{ "key": { "id": "severity", "name": "severity" }, "value": { "id": "critical", "name": "critical" } }' ``` **HTTP request** `POST {{API_URL}}/api/v1/alert_groups//labels/remove` Expand table | Parameter | Required | Description | |--------------|----------|-----------------------------| | `key` | Yes | The label key object | | `key.name` | Yes | The name of the label key | | `value` | Yes | The label value object | | `value.name` | Yes | The name of the label value | **Response codes** - `204 No Content` - Label successfully removed from the alert group - `400 Bad Request` - Invalid request data - `403 Forbidden` - Insufficient permissions - `404 Not Found` - Alert group not found or label not found **Error responses** - `Label not found` - The specified label is not associated with the alert group