--- 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", "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/alerting-and-irm/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` > Note > > This endpoint can only be used with an OnCall API key for now, as it requires specific user context. 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` > Note > > This endpoint can only be used with an OnCall API key for now, as it requires specific user context. 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` > Note > > This endpoint can only be used with an OnCall API key for now, as it requires specific user context. 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` > Note > > This endpoint can only be used with an OnCall API key for now, as it requires specific user context. 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` > Note > > This endpoint can only be used with an OnCall API key for now, as it requires specific user context. 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` > Note > > This endpoint can only be used with an OnCall API key for now, as it requires specific user context. 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` ## 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