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: 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",
      "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. 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)
  • 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: 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

Note

This endpoint can only be used with an OnCall API key for now, as it requires specific user context.

shell 
curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/acknowledge" \
  --request POST \
  --header "Authorization: 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

Note

This endpoint can only be used with an OnCall API key for now, as it requires specific user context.

shell 
curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/unacknowledge" \
  --request POST \
  --header "Authorization: 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

Note

This endpoint can only be used with an OnCall API key for now, as it requires specific user context.

shell 
curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/resolve" \
  --request POST \
  --header "Authorization: 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

Note

This endpoint can only be used with an OnCall API key for now, as it requires specific user context.

shell 
curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/unresolve" \
  --request POST \
  --header "Authorization: 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

Note

This endpoint can only be used with an OnCall API key for now, as it requires specific user context.

shell 
curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/silence" \
  --request POST \
  --header "Authorization: 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

Note

This endpoint can only be used with an OnCall API key for now, as it requires specific user context.

shell 
curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/unsilence" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "X-Grafana-URL: https://your-stack.grafana.net"

HTTP request

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

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: 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: 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: 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