Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow Alerts and IRMbreadcrumb arrow IRMbreadcrumb arrow Referencebreadcrumb arrow OnCall APIbreadcrumb arrow Alert groups API
Grafana Cloud

Alert groups HTTP API

List alert groups

Required permission: grafana-irm-app.alert-groups:read

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 
{
  "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. 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 
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/<ALERT_GROUP_ID>

Acknowledge an alert group

Required permission: grafana-irm-app.alert-groups:write

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/<ALERT_GROUP_ID>/acknowledge

Unacknowledge an alert group

Required permission: grafana-irm-app.alert-groups:write

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/<ALERT_GROUP_ID>/unacknowledge

Resolve an alert group

Required permission: grafana-irm-app.alert-groups:write

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/<ALERT_GROUP_ID>/resolve

Unresolve an alert group

Required permission: grafana-irm-app.alert-groups:write

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/<ALERT_GROUP_ID>/unresolve

Silence an alert group

Required permission: grafana-irm-app.alert-groups:write

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/<ALERT_GROUP_ID>/silence

ParameterRequiredDescription
delayYesThe duration of silence in seconds, -1 for silencing the alert forever

Unsilence an alert group

Required permission: grafana-irm-app.alert-groups:write

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/<ALERT_GROUP_ID>/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 
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/<ALERT_GROUP_ID>/attach

ParameterRequiredDescription
root_alert_group_idYesThe 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 
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/<ALERT_GROUP_ID>/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 
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/<ALERT_GROUP_ID>/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 
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"
  }'
ParameterRequiredDescription
modeNoThe 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/<ALERT_GROUP_ID>

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 
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 
{
  "key": {
    "id": "severity",
    "name": "severity"
  },
  "value": {
    "id": "critical",
    "name": "critical"
  }
}

HTTP request

POST {{API_URL}}/api/v1/alert_groups/<ALERT_GROUP_ID>/labels

ParameterRequiredDescription
keyYesThe label key object
key.nameYesThe name of the label key
valueYesThe label value object
value.nameYesThe 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 
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/<ALERT_GROUP_ID>/labels/remove

ParameterRequiredDescription
keyYesThe label key object
key.nameYesThe name of the label key
valueYesThe label value object
value.nameYesThe 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