This is documentation for the next version of Grafana documentation. For the latest stable release, go to the latest version.
Alert enrichment HTTP API
Note
Available in Grafana Cloud.
This API complies with the new Grafana API structure. To learn more refer to documentation about the API structure in Grafana.
This document may not contain the latest version of the API. For the most up-to-date list of available endpoints, refer to alertenrichment.grafana.app/v1beta1 in Swagger.
This API is in
beta, so it might change in future releases.
Use this API to manage alert enrichment in Grafana Cloud. An AlertEnrichment resource runs one or more enrichment steps when an alert fires and attaches additional context—such as data source query results, annotations, AI-generated explanations, or investigation links—before the alert notification is delivered.
All paths use the alertenrichment.grafana.app group and the v1beta1 version. Replace {namespace} with your stack namespace (stacks-<STACK_ID>). To learn more about namespaces in Grafana Cloud, refer to the
API overview.
Before you begin
Before you begin, ensure you have the following:
- Grafana Cloud stack: Alert enrichment is only available in Grafana Cloud.
- API authentication: Authenticate your requests with a Grafana Cloud service account token. Refer to HTTP API authentication.
Requirements
Managing global alert enrichment resources requires the Admin basic role. For per-rule alert enrichment (spec.alertRuleUids), users with the Viewer basic role can read configurations and users with the Editor or Admin basic role can create, update, and delete them.
For details on granular role-based access control (RBAC) permissions and roles, refer to Configure RBAC for Grafana Alerting and Alert enrichment.
Alert enrichment
An AlertEnrichment resource (alert-enrichments) defines an enrichment pipeline and the matching criteria that control which firing alerts run it.
Schema
An AlertEnrichment resource contains the following fields in metadata and spec:
metadata.name: Unique identifier of the enrichment within the stack namespace. Providemetadata.nameon create or setmetadata.generateNameso Grafana generates one.spec.title: Required. Display title of the enrichment.spec.description: Optional. Human-readable description of what the enrichment adds.spec.alertRuleUids: Optional list of alert rule UIDs this enrichment applies to. When empty, the enrichment applies globally across rules that satisfy the configured matchers.spec.labelMatchers: Optional list of label matchers (type,name,value, wheretypeis=,!=,=~, or!~) that an alert must match for the enrichment to run.spec.annotationMatchers: Optional list of annotation matchers (type,name,value) that an alert must match.spec.receivers: Optional list of receiver (contact point) names to restrict the enrichment to. When empty, the enrichment runs for all receivers.spec.steps: Required ordered list of pipeline steps. Each step sets:type:enricher(runs a single enrichment step) orconditional(evaluatesconditional.ifand branches tothenorelsesteps).timeout: Maximum execution duration for the step, such as"5s".enricher: Step configuration whentypeisenricher. Setenricher.typeto one of the following values along with its matching configuration field:assign(assign.annotations): Sets one or more annotations (nameand Go templatevalue) on the alert.dsquery(dataSource): Queries a Grafana data source (type: "logs"withlogs.dataSourceType,logs.dataSourceUid,logs.expr, and optionallogs.maxLines, ortype: "raw"withraw.requestand optionalraw.refId).external(external.url): Sends the alert payload to an external HTTP endpoint URL.explain(explain.annotation): Generates an AI/LLM explanation and stores it in the specified annotation key.asserts(asserts: {}): Adds a link to Root Cause Analysis (RCA) Workbench.sift(sift: {}): Starts a Sift investigation and adds a link to it. Sift is deprecated and reaches end of life soon; useassistantinstead for new configurations.assistant(assistant: {}): Starts a Grafana Assistant investigation and adds a link to it.loop(loop: {}) orquerySample(querySample: {}): Runs a Loop or rule query sample step.
Endpoints
The following table lists the main endpoints for AlertEnrichment resources. The Swagger specification also includes DELETE on the collection endpoint and watch query parameters.
List alert enrichment resources
GET /apis/alertenrichment.grafana.app/v1beta1/namespaces/{namespace}/alert-enrichments
Lists the AlertEnrichment resources in the stack namespace.
Path parameters:
{namespace}: Your Grafana Cloud stack namespace, in the formatstacks-<STACK_ID>.
Query parameters:
limit(optional): Maximum number ofAlertEnrichmentresources to return per page.continue(optional): Token frommetadata.continuein a previous response to fetch the next page.labelSelector(optional): FilterAlertEnrichmentresources bymetadata.labels.fieldSelector(optional): FilterAlertEnrichmentresources by selectable fields.
Example request
The following example lists AlertEnrichment resources in a stack:
GET /apis/alertenrichment.grafana.app/v1beta1/namespaces/stacks-123456/alert-enrichments HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Replace stacks-123456 with your stack namespace and <SERVICE_ACCOUNT_TOKEN> with your service account token.
Example response
The following example shows the response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "AlertEnrichmentList",
"apiVersion": "alertenrichment.grafana.app/v1beta1",
"metadata": {
"resourceVersion": "1762938000000000"
},
"items": [
{
"kind": "AlertEnrichment",
"apiVersion": "alertenrichment.grafana.app/v1beta1",
"metadata": {
"name": "attach-recent-logs",
"namespace": "stacks-123456",
"uid": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
"resourceVersion": "1762938000000000",
"creationTimestamp": "2026-11-12T09:00:00Z"
},
"spec": {
"title": "Attach recent error logs",
"description": "Adds recent Loki error logs to critical alerts",
"labelMatchers": [
{
"type": "=",
"name": "severity",
"value": "critical"
}
],
"steps": [
{
"type": "enricher",
"timeout": "5s",
"enricher": {
"type": "dsquery",
"dataSource": {
"type": "logs",
"logs": {
"dataSourceType": "loki",
"dataSourceUid": "<LOKI_DATASOURCE_UID>",
"expr": "{service_name=\"checkout\"} |= \"error\"",
"maxLines": 5
}
}
}
}
]
}
}
]
}Status codes
- 200:
OK - 401: Unauthorized
- 403: Access denied
Get an alert enrichment
GET /apis/alertenrichment.grafana.app/v1beta1/namespaces/{namespace}/alert-enrichments/{name}
Retrieves an AlertEnrichment resource by metadata.name.
Path parameters:
{namespace}: Your Grafana Cloud stack namespace (stacks-<STACK_ID>).{name}: Themetadata.nameof the alert enrichment.
Example request
The following example retrieves an alert enrichment:
GET /apis/alertenrichment.grafana.app/v1beta1/namespaces/stacks-123456/alert-enrichments/attach-recent-logs HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with the AlertEnrichment object shown in List alert enrichment resources.
Status codes
- 200: Found
- 401: Unauthorized
- 403: Access denied
- 404: Alert enrichment not found
Create an alert enrichment
POST /apis/alertenrichment.grafana.app/v1beta1/namespaces/{namespace}/alert-enrichments
Creates an AlertEnrichment resource. Provide metadata.name or set metadata.generateName so Grafana generates a unique name.
Path parameters:
{namespace}: Your Grafana Cloud stack namespace (stacks-<STACK_ID>).
Example request
The following example creates an enrichment that sets a formatted triage annotation on critical alerts:
POST /apis/alertenrichment.grafana.app/v1beta1/namespaces/stacks-123456/alert-enrichments HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"apiVersion": "alertenrichment.grafana.app/v1beta1",
"kind": "AlertEnrichment",
"metadata": {
"name": "add-runbook-note"
},
"spec": {
"title": "Add runbook note",
"description": "Adds a formatted triage note from alert labels",
"labelMatchers": [
{
"type": "=",
"name": "severity",
"value": "critical"
}
],
"steps": [
{
"type": "enricher",
"timeout": "5s",
"enricher": {
"type": "assign",
"assign": {
"annotations": [
{
"name": "triage_note",
"value": "Check service {{ $labels.service }} in {{ $labels.cluster }}"
}
]
}
}
}
]
}
}Example response
The following example shows the response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"kind": "AlertEnrichment",
"apiVersion": "alertenrichment.grafana.app/v1beta1",
"metadata": {
"name": "add-runbook-note",
"namespace": "stacks-123456",
"uid": "9a1b2c3d-4e5f-6789-abcd-0123456789ab",
"resourceVersion": "1762938060000000",
"generation": 1,
"creationTimestamp": "2026-11-12T09:01:00Z"
},
"spec": {
"title": "Add runbook note",
"description": "Adds a formatted triage note from alert labels",
"labelMatchers": [
{
"type": "=",
"name": "severity",
"value": "critical"
}
],
"steps": [
{
"type": "enricher",
"timeout": "5s",
"enricher": {
"type": "assign",
"assign": {
"annotations": [
{
"name": "triage_note",
"value": "Check service {{ $labels.service }} in {{ $labels.cluster }}"
}
]
}
}
}
]
}
}Status codes
- 201: Created
- 400: Bad request (invalid JSON or invalid matcher or duration syntax)
- 401: Unauthorized
- 403: Access denied
- 409: Conflict (an alert enrichment with the same
metadata.namealready exists) - 422: Schema validation error
Update an alert enrichment
PUT /apis/alertenrichment.grafana.app/v1beta1/namespaces/{namespace}/alert-enrichments/{name}
Replaces an existing AlertEnrichment resource. Include metadata.resourceVersion from the latest version you read to prevent concurrent overwrites.
Path parameters:
{namespace}: Your Grafana Cloud stack namespace (stacks-<STACK_ID>).{name}: Themetadata.nameof the alert enrichment.
Example request
The following example updates the enrichment created earlier:
PUT /apis/alertenrichment.grafana.app/v1beta1/namespaces/stacks-123456/alert-enrichments/add-runbook-note HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"apiVersion": "alertenrichment.grafana.app/v1beta1",
"kind": "AlertEnrichment",
"metadata": {
"name": "add-runbook-note",
"resourceVersion": "1762938060000000"
},
"spec": {
"title": "Add runbook note",
"description": "Adds a formatted triage note for critical and error alerts",
"labelMatchers": [
{
"type": "=~",
"name": "severity",
"value": "critical|error"
}
],
"steps": [
{
"type": "enricher",
"timeout": "5s",
"enricher": {
"type": "assign",
"assign": {
"annotations": [
{
"name": "triage_note",
"value": "Check service {{ $labels.service }} in {{ $labels.cluster }}"
}
]
}
}
}
]
}
}Example response
The response returns 200 OK with the updated AlertEnrichment resource and an incremented metadata.resourceVersion.
Status codes
- 200: Updated
- 400: Bad request (invalid JSON)
- 401: Unauthorized
- 403: Access denied
- 404: Alert enrichment not found
- 409: Conflict (
metadata.resourceVersiondoesn’t match the stored version) - 422: Schema validation error
Patch an alert enrichment
PATCH /apis/alertenrichment.grafana.app/v1beta1/namespaces/{namespace}/alert-enrichments/{name}
Applies a partial update to an AlertEnrichment resource using application/merge-patch+json, application/json-patch+json, or application/strategic-merge-patch+json.
Path parameters:
{namespace}: Your Grafana Cloud stack namespace (stacks-<STACK_ID>).{name}: Themetadata.nameof the alert enrichment.
Example request
The following example updates only spec.description:
PATCH /apis/alertenrichment.grafana.app/v1beta1/namespaces/stacks-123456/alert-enrichments/add-runbook-note HTTP/1.1
Accept: application/json
Content-Type: application/merge-patch+json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"spec": {
"description": "Updated description for runbook triage notes"
}
}Example response
The response returns 200 OK with the updated AlertEnrichment resource.
Status codes
- 200: Updated
- 400: Bad request (invalid JSON or patch)
- 401: Unauthorized
- 403: Access denied
- 404: Alert enrichment not found
- 409: Conflict (
metadata.resourceVersiondoesn’t match the stored version) - 422: Schema validation error
Delete an alert enrichment
DELETE /apis/alertenrichment.grafana.app/v1beta1/namespaces/{namespace}/alert-enrichments/{name}
Deletes an AlertEnrichment resource by metadata.name.
Path parameters:
{namespace}: Your Grafana Cloud stack namespace (stacks-<STACK_ID>).{name}: Themetadata.nameof the alert enrichment.
Example request
The following example deletes an alert enrichment:
DELETE /apis/alertenrichment.grafana.app/v1beta1/namespaces/stacks-123456/alert-enrichments/add-runbook-note HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The following example shows the response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "Status",
"apiVersion": "v1",
"metadata": {},
"status": "Success",
"code": 200
}Status codes
- 200: Deleted
- 401: Unauthorized
- 403: Access denied
- 404: Alert enrichment not found
Details
When spec.alertRuleUids is omitted or empty, the enrichment applies globally across alerts matching labelMatchers, annotationMatchers, and receivers. When spec.alertRuleUids lists one or more alert rule UIDs, the enrichment runs only for those rules. Refer to Requirements for how global and per-rule scoping affects access.
Related resources
Use the following resources to keep working with alert enrichment and Grafana Alerting APIs:
- Alert enrichment guide: Refer to Alert enrichment.
- Alert rules HTTP API: Refer to Alert rules HTTP API.
- Alert notifications HTTP API: Refer to Alert notifications HTTP API.
- API structure: Refer to API structure in Grafana.


