Alert rules HTTP API
Note
Available in Grafana 13.3 and later.
This API complies with the new Grafana API structure. To learn more refer to documentation about the API structure in Grafana.
The legacy Alerting Provisioning HTTP API is still available. Together with the Alert notifications HTTP API, this API partially replaces it. Refer to Migrate from the legacy Alerting Provisioning API to learn how both APIs match.
This document may not contain the latest version of the API. For the most up-to-date list of available endpoints, refer to rules.alerting.grafana.app/v1beta1 in Swagger.
This API is in
beta, so it might change in future releases.
Use this API to manage Grafana-managed alert rules, recording rules, and rule sequences as standalone resources. Each rule has its own versioned, schema-validated resource, so you can create, read, update, and delete a single rule without rewriting an entire rule group.
All paths use the rules.alerting.grafana.app group and the v1beta1 version. Replace {namespace} with your namespace. To learn more about which namespace to use, refer to the
API overview.
Grafana also serves the earlier v0alpha1 version for backward compatibility, including an experimental configs resource and rule search routes in v0alpha1. Use v1beta1 for new integrations. In v1beta1, alert rule notificationSettings must include type (SimplifiedRouting or NamedRoutingTree), and RuleSequence uses spec.alertRules instead of spec.alertingRules.
Before you begin
Before you begin, ensure you have the following:
- Grafana Alerting enabled: Grafana Alerting must be enabled on your instance.
- A target folder: Alert rules, recording rules, and rule sequences must belong to a folder. Pass the folder UID in
metadata.annotations["grafana.app/folder"]. Root-level placement isn’t supported. - API authentication: Authenticate with a service account token or basic authentication (OSS and Enterprise). Refer to HTTP API authentication.
Requirements
By default, users with the Viewer basic role can read alert rules, recording rules, and rule sequences in folders they have access to, and users with the Editor or Admin basic role can also create, update, and delete them.
If you’re running Grafana Enterprise or Grafana Cloud and want to configure granular role-based access control (RBAC) permissions, including folder scopes, data source query permissions, and provenance permissions for grafana.com/provenance, refer to
Configure RBAC for Grafana Alerting.
Alert rules
An AlertRule resource (alertrules) defines a Grafana-managed alert rule: its queries and expressions, evaluation interval, pending and keep-firing durations, no-data and execution-error handling, labels, annotations, and notification routing.
Schema
An AlertRule resource contains the following fields in metadata, spec, and status:
metadata.name: Required on legacy storage; optional if unified storage is enabled andmetadata.generateNameis set. Identifies the rule UID in request paths.metadata.annotations["grafana.app/folder"]: Required. UID of the folder that contains the rule.metadata.annotations["grafana.com/provenance"]: Optional. Set toapito mark the rule as provisioned so it can’t be edited in the Grafana UI, or omit it to allow UI edits.spec.title: Required. Display title of the alert rule (up to 190 characters).spec.trigger.interval: Required. Evaluation interval as a Prometheus duration string, such as1m, that is a multiple of your instance’s base evaluation interval.spec.expressions: Required. Map of query and expression nodes keyed byrefId(for example,A,B,C). Exactly one expression must set"source": trueto mark the alert condition. OmitdatasourceUIDon server-side expression nodes (__expr__).spec.noDataState: Required. State when evaluation returns no data:NoData,Ok,Alerting, orKeepLast.spec.execErrState: Required. State when evaluation fails with an error:Error,Ok,Alerting, orKeepLast.spec.for: Optional. Pending duration before the rule transitions to firing, such as5m.spec.keepFiringFor: Optional. Duration to keep firing after the condition resolves, such as2m.spec.paused: Optional. Set totrueto pause evaluation.spec.labelsandspec.annotations: Optional maps of key-value template strings attached to firing alert instances.spec.panelRef: Optional link to a dashboard panel, withdashboardUIDandpanelID.spec.notificationSettings: Optional routing configuration. When omitted, alerts use the default notification policy tree. When set,typeis required inv1beta1:SimplifiedRouting: Routes directly to a contact point (receiver), with optionalgroupBy,groupWait,groupInterval,repeatInterval,muteTimeIntervals, andactiveTimeIntervals.NamedRoutingTree: Routes to a named notification policy tree (routingTree).
status: Read-only runtime status reported by Grafana, includinghealth(Unknown,OK,Paused,Error,NoData),state(Inactive,Healthy,Firing,Pending,Recovering),stateReason,lastEvaluationTime,evaluationDuration,lastError, and per-state instance counts intotals.
Endpoints
The following table lists the main endpoints for AlertRule resources. For PATCH, collection DELETE, POST /alertrules/search, and /status sub-resource endpoints, refer to Swagger.
List alert rules
GET /apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/alertrules
Lists the AlertRule resources in the namespace.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Query parameters:
limit(optional): Maximum number of alert rules to return per page.continue(optional): Token frommetadata.continuein a previous response to fetch the next page.labelSelector(optional): Filter by folder (grafana.app/folder=<FOLDER_UID>) or rule group (grafana.com/group=<GROUP_NAME>).fieldSelector(optional): Filter by selectablespecfields (refer to Details).
Example request
The following example lists alert rules in a specific folder:
GET /apis/rules.alerting.grafana.app/v1beta1/namespaces/default/alertrules?labelSelector=grafana.app/folder=<FOLDER_UID> HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with an AlertRuleList object containing matching AlertRule items in items.
Status codes
- 200:
OK - 400: Bad request (invalid selector)
- 401: Unauthorized
- 403: Access denied
Get an alert rule
GET /apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/alertrules/{name}
Retrieves an AlertRule resource by metadata.name, including its runtime status.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: Themetadata.name(rule UID) of the alert rule.
Example request
The following example gets an alert rule:
GET /apis/rules.alerting.grafana.app/v1beta1/namespaces/default/alertrules/high-cpu-usage HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with the AlertRule object shown in Create an alert rule.
Status codes
- 200: Found
- 401: Unauthorized
- 403: Access denied
- 404: Alert rule not found
Create an alert rule
POST /apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/alertrules
Creates an AlertRule resource in the folder specified by metadata.annotations["grafana.app/folder"].
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Example request
The following example creates an alert rule that queries a Prometheus data source and routes notifications directly to a contact point:
POST /apis/rules.alerting.grafana.app/v1beta1/namespaces/default/alertrules HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"apiVersion": "rules.alerting.grafana.app/v1beta1",
"kind": "AlertRule",
"metadata": {
"name": "high-cpu-usage",
"annotations": {
"grafana.app/folder": "<FOLDER_UID>"
}
},
"spec": {
"title": "High CPU usage",
"trigger": {
"interval": "1m"
},
"for": "5m",
"noDataState": "NoData",
"execErrState": "Error",
"labels": {
"severity": "warning"
},
"annotations": {
"summary": "CPU usage is above 80%"
},
"notificationSettings": {
"type": "SimplifiedRouting",
"receiver": "oncall-slack"
},
"expressions": {
"A": {
"queryType": "",
"datasourceUID": "<DATASOURCE_UID>",
"relativeTimeRange": {
"from": "5m",
"to": "0s"
},
"model": {
"expr": "100 - (avg by (instance) (rate(node_cpu_seconds_total{mode=\"idle\"}[5m])) * 100)"
}
},
"B": {
"model": {
"type": "reduce",
"expression": "A",
"reducer": "last"
}
},
"C": {
"source": true,
"model": {
"type": "threshold",
"expression": "B",
"conditions": [
{
"evaluator": {
"type": "gt",
"params": [80]
}
}
]
}
}
}
}
}Replace <SERVICE_ACCOUNT_TOKEN>, <FOLDER_UID>, and <DATASOURCE_UID> with values from your Grafana instance.
Example response
The following example shows the response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"kind": "AlertRule",
"apiVersion": "rules.alerting.grafana.app/v1beta1",
"metadata": {
"name": "high-cpu-usage",
"namespace": "default",
"uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"resourceVersion": "1",
"labels": {
"grafana.app/folder": "<FOLDER_UID>"
},
"annotations": {
"grafana.app/folder": "<FOLDER_UID>",
"grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
"grafana.app/updatedTimestamp": "2026-11-12T09:00:00Z"
}
},
"spec": {
"title": "High CPU usage",
"trigger": {
"interval": "1m"
},
"for": "5m",
"noDataState": "NoData",
"execErrState": "Error",
"labels": {
"severity": "warning"
},
"annotations": {
"summary": "CPU usage is above 80%"
},
"notificationSettings": {
"type": "SimplifiedRouting",
"receiver": "oncall-slack"
},
"expressions": {
"A": {
"queryType": "",
"datasourceUID": "<DATASOURCE_UID>",
"relativeTimeRange": {
"from": "5m",
"to": "0s"
},
"model": {
"expr": "100 - (avg by (instance) (rate(node_cpu_seconds_total{mode=\"idle\"}[5m])) * 100)"
}
},
"B": {
"model": {
"type": "reduce",
"expression": "A",
"reducer": "last"
}
},
"C": {
"source": true,
"model": {
"type": "threshold",
"expression": "B",
"conditions": [
{
"evaluator": {
"type": "gt",
"params": [80]
}
}
]
}
}
}
},
"status": {}
}Status codes
- 201: Created
- 400: Bad request (invalid JSON, invalid duration or expression, or missing folder)
- 401: Unauthorized
- 403: Access denied (missing RBAC permission, missing provenance permission, or alert rule quota reached)
- 404: Target folder not found
- 409: Conflict (an alert rule with the same
metadata.namealready exists) - 422: Schema validation error (for example,
notificationSettings.typeis missing)
Update an alert rule
PUT /apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/alertrules/{name}
Replaces an existing AlertRule resource. Retrieve the current resource first and pass its metadata.resourceVersion in the PUT body so concurrent updates don’t overwrite each other. For partial updates, send a PATCH request to the same path instead.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: Themetadata.nameof the alert rule.
Example request
The following example updates the alert rule’s title and pending duration:
PUT /apis/rules.alerting.grafana.app/v1beta1/namespaces/default/alertrules/high-cpu-usage HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"apiVersion": "rules.alerting.grafana.app/v1beta1",
"kind": "AlertRule",
"metadata": {
"name": "high-cpu-usage",
"resourceVersion": "1",
"annotations": {
"grafana.app/folder": "<FOLDER_UID>"
}
},
"spec": {
"title": "High CPU usage (sustained)",
"trigger": {
"interval": "1m"
},
"for": "10m",
"noDataState": "NoData",
"execErrState": "Error",
"notificationSettings": {
"type": "SimplifiedRouting",
"receiver": "oncall-slack"
},
"expressions": {
"A": {
"queryType": "",
"datasourceUID": "<DATASOURCE_UID>",
"relativeTimeRange": {
"from": "5m",
"to": "0s"
},
"model": {
"expr": "100 - (avg by (instance) (rate(node_cpu_seconds_total{mode=\"idle\"}[5m])) * 100)"
}
},
"B": {
"model": {
"type": "reduce",
"expression": "A",
"reducer": "last"
}
},
"C": {
"source": true,
"model": {
"type": "threshold",
"expression": "B",
"conditions": [
{
"evaluator": {
"type": "gt",
"params": [80]
}
}
]
}
}
}
}
}Example response
The response returns 200 OK with the updated AlertRule resource and an incremented metadata.resourceVersion.
Status codes
- 200: Updated
- 400: Bad request (invalid JSON, invalid duration or expression, or missing folder)
- 401: Unauthorized
- 403: Access denied
- 404: Alert rule or target folder not found
- 409: Conflict (
metadata.resourceVersiondoesn’t match the stored version) - 422: Schema validation error
Delete an alert rule
DELETE /apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/alertrules/{name}
Deletes the AlertRule resource with the given metadata.name.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: Themetadata.nameof the alert rule.
Example request
The following example deletes an alert rule:
DELETE /apis/rules.alerting.grafana.app/v1beta1/namespaces/default/alertrules/high-cpu-usage HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with the deleted AlertRule object (or a Status object when served from unified storage).
Status codes
- 200: Deleted
- 401: Unauthorized
- 403: Access denied
- 404: Alert rule not found
- 409: Conflict (the alert rule is still referenced by a
RuleSequence)
Details
- Selectable fields: On
GET /alertrules,fieldSelectorsupportsspec.title,spec.paused,spec.panelRef.dashboardUID,spec.panelRef.panelID,spec.notificationSettings.type,spec.notificationSettings.receiver, andspec.notificationSettings.routingTree. - History and trash modes: Pass
labelSelector=grafana.app/get-history=truetogether withfieldSelector=metadata.name=<RULE_UID>to list an alert rule’s version history, or passlabelSelector=grafana.app/get-trash=trueto list deleted alert rules in the trash. - Sequence membership: If an alert rule belongs to a
RuleSequence, remove it from the sequence before deleting it or moving it to another folder.
Recording rules
A RecordingRule resource (recordingrules) evaluates a metric expression on a fixed interval and writes the resulting time series to a Prometheus-compatible target data source.
Schema
A RecordingRule resource uses the same folder and provenance annotations as AlertRule and contains the following fields in spec and status:
spec.title: Required. Display title of the recording rule.spec.metric: Required. Valid Prometheus metric name to write, matching^[a-zA-Z_:][a-zA-Z0-9_:]*$.spec.targetDatasourceUID: Required. UID of the Prometheus-compatible data source where Grafana writes the recorded samples.spec.trigger.interval: Required. Evaluation interval as a Prometheus duration string, such as1m.spec.expressions: Required. Map of query and expression nodes keyed byrefId, with"source": truemarking the expression to record.spec.paused: Optional. Set totrueto pause evaluation.spec.labels: Optional map of labels added to the recorded metric series.status: Read-only runtime status reportinghealth(Unknown,Recording,Paused,Error,NoData),lastEvaluationTime,evaluationDuration, andlastError.
Endpoints
The following table lists the main endpoints for RecordingRule resources. For PATCH, collection DELETE, POST /recordingrules/search, and /status sub-resource endpoints, refer to Swagger.
List recording rules
GET /apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/recordingrules
Lists the RecordingRule resources in the namespace. Supports limit, continue, labelSelector, and fieldSelector.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Example request
The following example lists recording rules in a folder:
GET /apis/rules.alerting.grafana.app/v1beta1/namespaces/default/recordingrules?labelSelector=grafana.app/folder=<FOLDER_UID> HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with a RecordingRuleList object containing matching RecordingRule items in items.
Status codes
- 200:
OK - 400: Bad request (invalid selector)
- 401: Unauthorized
- 403: Access denied
Get a recording rule
GET /apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/recordingrules/{name}
Retrieves a RecordingRule resource by metadata.name, including its runtime status.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: Themetadata.name(rule UID) of the recording rule.
Example request
The following example gets a recording rule:
GET /apis/rules.alerting.grafana.app/v1beta1/namespaces/default/recordingrules/service-request-rate HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with the RecordingRule resource.
Status codes
- 200: Found
- 401: Unauthorized
- 403: Access denied
- 404: Recording rule not found
Create a recording rule
POST /apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/recordingrules
Creates a RecordingRule resource in the folder specified by metadata.annotations["grafana.app/folder"].
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Example request
The following example creates a recording rule that records per-service request rates every minute:
POST /apis/rules.alerting.grafana.app/v1beta1/namespaces/default/recordingrules HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"apiVersion": "rules.alerting.grafana.app/v1beta1",
"kind": "RecordingRule",
"metadata": {
"name": "service-request-rate",
"annotations": {
"grafana.app/folder": "<FOLDER_UID>"
}
},
"spec": {
"title": "Service request rate",
"metric": "job:http_requests_total:rate5m",
"targetDatasourceUID": "<TARGET_DATASOURCE_UID>",
"trigger": {
"interval": "1m"
},
"labels": {
"env": "production"
},
"expressions": {
"A": {
"source": true,
"datasourceUID": "<SOURCE_DATASOURCE_UID>",
"relativeTimeRange": {
"from": "5m",
"to": "0s"
},
"model": {
"expr": "sum by (job) (rate(http_requests_total[5m]))"
}
}
}
}
}Replace <SERVICE_ACCOUNT_TOKEN>, <FOLDER_UID>, <SOURCE_DATASOURCE_UID>, and <TARGET_DATASOURCE_UID> with values from your Grafana instance.
Example response
On success, Grafana returns 201 Created with the created RecordingRule object.
Status codes
- 201: Created
- 400: Bad request (invalid JSON, invalid metric name or duration, or missing folder)
- 401: Unauthorized
- 403: Access denied (missing RBAC permission, missing provenance permission, or rule quota reached)
- 404: Target folder not found
- 409: Conflict (a recording rule with the same
metadata.namealready exists) - 422: Schema validation error
Update a recording rule
PUT /apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/recordingrules/{name}
Replaces an existing RecordingRule resource. Include metadata.resourceVersion from the latest version you read.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: Themetadata.nameof the recording rule.
Example request
The following example updates the recording rule’s evaluation interval:
PUT /apis/rules.alerting.grafana.app/v1beta1/namespaces/default/recordingrules/service-request-rate HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"apiVersion": "rules.alerting.grafana.app/v1beta1",
"kind": "RecordingRule",
"metadata": {
"name": "service-request-rate",
"resourceVersion": "1",
"annotations": {
"grafana.app/folder": "<FOLDER_UID>"
}
},
"spec": {
"title": "Service request rate",
"metric": "job:http_requests_total:rate5m",
"targetDatasourceUID": "<TARGET_DATASOURCE_UID>",
"trigger": {
"interval": "2m"
},
"expressions": {
"A": {
"source": true,
"datasourceUID": "<SOURCE_DATASOURCE_UID>",
"relativeTimeRange": {
"from": "5m",
"to": "0s"
},
"model": {
"expr": "sum by (job) (rate(http_requests_total[5m]))"
}
}
}
}
}Example response
The response returns 200 OK with the updated RecordingRule object and an incremented metadata.resourceVersion.
Status codes
- 200: Updated
- 400: Bad request (invalid JSON, invalid metric name or duration, or missing folder)
- 401: Unauthorized
- 403: Access denied
- 404: Recording rule or target folder not found
- 409: Conflict (
metadata.resourceVersiondoesn’t match the stored version) - 422: Schema validation error
Delete a recording rule
DELETE /apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/recordingrules/{name}
Deletes a RecordingRule resource by metadata.name.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: Themetadata.nameof the recording rule.
Example request
The following example deletes a recording rule:
DELETE /apis/rules.alerting.grafana.app/v1beta1/namespaces/default/recordingrules/service-request-rate HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with the deleted RecordingRule object (or a Status object when served from unified storage).
Status codes
- 200: Deleted
- 401: Unauthorized
- 403: Access denied
- 404: Recording rule not found
- 409: Conflict (the recording rule is still referenced by a
RuleSequence)
Details
- Selectable fields: On
GET /recordingrules,fieldSelectorsupportsspec.title,spec.paused,spec.metric, andspec.targetDatasourceUID.labelSelectorsupportsgrafana.app/folderandgrafana.com/group, as well asgrafana.app/get-history=true(withfieldSelector=metadata.name=<RULE_UID>) andgrafana.app/get-trash=true. - Sequence membership: Remove a recording rule from any
RuleSequencebefore deleting it or moving it to another folder.
Rule sequences
Note
Rule sequences are in public preview. For evaluation behavior and constraints, refer to Configure rule sequences.
A RuleSequence resource (rulesequences) evaluates existing Grafana-managed recording rules and optional alert rules in a defined order at a shared evaluation interval.
Schema
A RuleSequence resource requires metadata.annotations["grafana.app/folder"] and contains the following fields in spec:
spec.trigger.interval: Required. Shared evaluation interval for every rule in the sequence, overriding each rule’s individual interval while it belongs to the sequence.spec.recordingRules: Required non-empty ordered array of{ "name": "<RULE_UID>" }references toRecordingRuleresources in the same folder.spec.alertRules: Optional ordered array of{ "name": "<RULE_UID>" }references toAlertRuleresources in the same folder, evaluated afterrecordingRules(namedspec.alertingRulesinv0alpha1).
Endpoints
The following table lists the main endpoints for RuleSequence resources. For PATCH, collection DELETE, POST /rulesequences/search, and /status sub-resource endpoints, refer to Swagger.
List rule sequences
GET /apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/rulesequences
Lists the RuleSequence resources in the namespace.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Example request
The following example lists rule sequences in the namespace:
GET /apis/rules.alerting.grafana.app/v1beta1/namespaces/default/rulesequences HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with a RuleSequenceList object containing RuleSequence items in items.
Status codes
- 200:
OK - 401: Unauthorized
- 403: Access denied
Get a rule sequence
GET /apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/rulesequences/{name}
Retrieves a RuleSequence resource by metadata.name.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: Themetadata.nameof the rule sequence.
Example request
The following example gets a rule sequence:
GET /apis/rules.alerting.grafana.app/v1beta1/namespaces/default/rulesequences/request-error-sequence HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with the RuleSequence object.
Status codes
- 200: Found
- 401: Unauthorized
- 403: Access denied
- 404: Rule sequence not found
Create a rule sequence
POST /apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/rulesequences
Creates a RuleSequence resource in the folder specified by metadata.annotations["grafana.app/folder"].
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Example request
The following example creates a rule sequence in v1beta1 that evaluates two recording rules followed by an alert rule every minute:
POST /apis/rules.alerting.grafana.app/v1beta1/namespaces/default/rulesequences HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"apiVersion": "rules.alerting.grafana.app/v1beta1",
"kind": "RuleSequence",
"metadata": {
"name": "request-error-sequence",
"annotations": {
"grafana.app/folder": "<FOLDER_UID>"
}
},
"spec": {
"trigger": {
"interval": "1m"
},
"recordingRules": [
{ "name": "<REQUEST_RATE_RULE_UID>" },
{ "name": "<ERROR_RATIO_RULE_UID>" }
],
"alertRules": [
{ "name": "<ALERT_RULE_UID>" }
]
}
}Replace <FOLDER_UID> with the shared folder UID, and replace <REQUEST_RATE_RULE_UID>, <ERROR_RATIO_RULE_UID>, and <ALERT_RULE_UID> with the metadata.name of each rule.
Example response
On success, Grafana returns 201 Created with the created RuleSequence object.
Status codes
- 201: Created
- 400: Bad request (invalid JSON or missing folder)
- 401: Unauthorized
- 403: Access denied
- 404: Target folder not found
- 409: Conflict (a rule sequence with the same
metadata.namealready exists) - 422: Schema validation error (for example, a referenced rule is missing, in another folder, or already in another sequence)
Update a rule sequence
PUT /apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/rulesequences/{name}
Updates the evaluation order, rule membership, or interval of a RuleSequence resource. Include metadata.resourceVersion from the latest version you read.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: Themetadata.nameof the rule sequence.
Example request
The following example updates the shared evaluation interval of a rule sequence:
PUT /apis/rules.alerting.grafana.app/v1beta1/namespaces/default/rulesequences/request-error-sequence HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"apiVersion": "rules.alerting.grafana.app/v1beta1",
"kind": "RuleSequence",
"metadata": {
"name": "request-error-sequence",
"resourceVersion": "1",
"annotations": {
"grafana.app/folder": "<FOLDER_UID>"
}
},
"spec": {
"trigger": {
"interval": "2m"
},
"recordingRules": [
{ "name": "<REQUEST_RATE_RULE_UID>" },
{ "name": "<ERROR_RATIO_RULE_UID>" }
],
"alertRules": [
{ "name": "<ALERT_RULE_UID>" }
]
}
}Example response
The response returns 200 OK with the updated RuleSequence object and an incremented metadata.resourceVersion.
Status codes
- 200: Updated
- 400: Bad request (invalid JSON)
- 401: Unauthorized
- 403: Access denied
- 404: Rule sequence not found
- 409: Conflict (
metadata.resourceVersiondoesn’t match the stored version) - 422: Schema validation error
Delete a rule sequence
DELETE /apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/rulesequences/{name}
Deletes a RuleSequence resource without deleting the rules it references. Removed rules return to their own stored evaluation intervals.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: Themetadata.nameof the rule sequence.
Example request
The following example deletes a rule sequence:
DELETE /apis/rules.alerting.grafana.app/v1beta1/namespaces/default/rulesequences/request-error-sequence HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with a Status object confirming deletion.
Status codes
- 200: Deleted
- 401: Unauthorized
- 403: Access denied
- 404: Rule sequence not found
Details
- Same-folder requirement: All referenced recording rules and alert rules must already exist in the same folder as the
RuleSequence. - Single-sequence membership: Each rule can belong to at most one
RuleSequence, andspec.trigger.intervalmust be an integer multiple of your instance’s base evaluation interval.
Migrate from the legacy Alerting Provisioning API
Together with the
Alert notifications HTTP API, this API partially replaces the legacy
Alerting Provisioning HTTP API. Specifically, this API replaces the alert rule and rule group CRUD endpoints, while notification endpoints move to notifications.alerting.grafana.app/v1beta1.
The following table shows how the legacy alert rule endpoints map to rules.alerting.grafana.app/v1beta1:
When you migrate, consider the following differences:
- Separate resource kinds: The legacy API uses one
ProvisionedAlertRulepayload for both alert rules and recording rules (distinguished by whetherrecordis set). The new API separates them intoAlertRule(alertrules) andRecordingRule(recordingrules), each with its own validated schema. - One resource per rule: You no longer need to
PUTan entire rule group to change evaluation intervals or rule membership. Each rule sets its ownspec.trigger.interval, and ordered evaluation across rules usesRuleSequence. - Metadata placement:
uidmoves tometadata.name,folderUIDmoves tometadata.annotations["grafana.app/folder"], and optimistic concurrency usesmetadata.resourceVersion. - Expressions map: The legacy
dataarray and top-levelconditionstring becomespec.expressions, a map keyed byrefIdwhere the alert condition or recorded query sets"source": trueandrelativeTimeRangeuses duration strings (such as"from": "5m", "to": "0s") instead of integer seconds. - Provenance: Instead of sending the
X-Disable-Provenancerequest header, setmetadata.annotations["grafana.com/provenance"]to"api"to lock a rule from UI edits, or omit the annotation to allow UI edits. - Notification endpoints: Contact points, notification policies, templates, and mute timings are managed through the Alert notifications HTTP API.
Related resources
Use the following resources to keep working with Grafana Alerting APIs:
- Alert notifications HTTP API: Refer to Alert notifications HTTP API.
- Alert enrichment HTTP API: Refer to Alert enrichment HTTP API.
- Rule sequences: Refer to Configure rule sequences.
- API structure: Refer to API structure in Grafana.


