Enterprise Open source Grafana Cloud

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 and metadata.generateName is 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 to api to 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 as 1m, that is a multiple of your instance’s base evaluation interval.
  • spec.expressions: Required. Map of query and expression nodes keyed by refId (for example, A, B, C). Exactly one expression must set "source": true to mark the alert condition. Omit datasourceUID on server-side expression nodes (__expr__).
  • spec.noDataState: Required. State when evaluation returns no data: NoData, Ok, Alerting, or KeepLast.
  • spec.execErrState: Required. State when evaluation fails with an error: Error, Ok, Alerting, or KeepLast.
  • spec.for: Optional. Pending duration before the rule transitions to firing, such as 5m.
  • spec.keepFiringFor: Optional. Duration to keep firing after the condition resolves, such as 2m.
  • spec.paused: Optional. Set to true to pause evaluation.
  • spec.labels and spec.annotations: Optional maps of key-value template strings attached to firing alert instances.
  • spec.panelRef: Optional link to a dashboard panel, with dashboardUID and panelID.
  • spec.notificationSettings: Optional routing configuration. When omitted, alerts use the default notification policy tree. When set, type is required in v1beta1:
    • SimplifiedRouting: Routes directly to a contact point (receiver), with optional groupBy, groupWait, groupInterval, repeatInterval, muteTimeIntervals, and activeTimeIntervals.
    • NamedRoutingTree: Routes to a named notification policy tree (routingTree).
  • status: Read-only runtime status reported by Grafana, including health (Unknown, OK, Paused, Error, NoData), state (Inactive, Healthy, Firing, Pending, Recovering), stateReason, lastEvaluationTime, evaluationDuration, lastError, and per-state instance counts in totals.

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.

MethodSummaryURI
GETList alert rules/apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/alertrules
GETGet an alert rule/apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/alertrules/{name}
POSTCreate an alert rule/apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/alertrules
PUTUpdate an alert rule/apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/alertrules/{name}
DELETEDelete an alert rule/apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/alertrules/{name}

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 from metadata.continue in 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 selectable spec fields (refer to Details).
Example request

The following example lists alert rules in a specific folder:

http
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}: The metadata.name (rule UID) of the alert rule.
Example request

The following example gets an alert rule:

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

http
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
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.name already exists)
  • 422: Schema validation error (for example, notificationSettings.type is 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}: The metadata.name of the alert rule.
Example request

The following example updates the alert rule’s title and pending duration:

http
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.resourceVersion doesn’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}: The metadata.name of the alert rule.
Example request

The following example deletes an alert rule:

http
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, fieldSelector supports spec.title, spec.paused, spec.panelRef.dashboardUID, spec.panelRef.panelID, spec.notificationSettings.type, spec.notificationSettings.receiver, and spec.notificationSettings.routingTree.
  • History and trash modes: Pass labelSelector=grafana.app/get-history=true together with fieldSelector=metadata.name=<RULE_UID> to list an alert rule’s version history, or pass labelSelector=grafana.app/get-trash=true to 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 as 1m.
  • spec.expressions: Required. Map of query and expression nodes keyed by refId, with "source": true marking the expression to record.
  • spec.paused: Optional. Set to true to pause evaluation.
  • spec.labels: Optional map of labels added to the recorded metric series.
  • status: Read-only runtime status reporting health (Unknown, Recording, Paused, Error, NoData), lastEvaluationTime, evaluationDuration, and lastError.

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.

MethodSummaryURI
GETList recording rules/apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/recordingrules
GETGet a recording rule/apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/recordingrules/{name}
POSTCreate a recording rule/apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/recordingrules
PUTUpdate a recording rule/apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/recordingrules/{name}
DELETEDelete a recording rule/apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/recordingrules/{name}

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:

http
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}: The metadata.name (rule UID) of the recording rule.
Example request

The following example gets a recording rule:

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

http
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.name already 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}: The metadata.name of the recording rule.
Example request

The following example updates the recording rule’s evaluation interval:

http
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.resourceVersion doesn’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}: The metadata.name of the recording rule.
Example request

The following example deletes a recording rule:

http
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, fieldSelector supports spec.title, spec.paused, spec.metric, and spec.targetDatasourceUID. labelSelector supports grafana.app/folder and grafana.com/group, as well as grafana.app/get-history=true (with fieldSelector=metadata.name=<RULE_UID>) and grafana.app/get-trash=true.
  • Sequence membership: Remove a recording rule from any RuleSequence before 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 to RecordingRule resources in the same folder.
  • spec.alertRules: Optional ordered array of { "name": "<RULE_UID>" } references to AlertRule resources in the same folder, evaluated after recordingRules (named spec.alertingRules in v0alpha1).

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.

MethodSummaryURI
GETList rule sequences/apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/rulesequences
GETGet a rule sequence/apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/rulesequences/{name}
POSTCreate a rule sequence/apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/rulesequences
PUTUpdate a rule sequence/apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/rulesequences/{name}
DELETEDelete a rule sequence/apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/rulesequences/{name}

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:

http
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}: The metadata.name of the rule sequence.
Example request

The following example gets a rule sequence:

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

http
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.name already 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}: The metadata.name of the rule sequence.
Example request

The following example updates the shared evaluation interval of a rule sequence:

http
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.resourceVersion doesn’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}: The metadata.name of the rule sequence.
Example request

The following example deletes a rule sequence:

http
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, and spec.trigger.interval must 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:

Legacy endpointNew endpoint
GET /api/v1/provisioning/alert-rulesGET /apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/alertrules and GET /apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/recordingrules
GET /api/v1/provisioning/alert-rules/:uidGET /apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/alertrules/{name} or .../recordingrules/{name}
POST /api/v1/provisioning/alert-rulesPOST /apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/alertrules or .../recordingrules
PUT /api/v1/provisioning/alert-rules/:uidPUT /apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/alertrules/{name} or .../recordingrules/{name}
DELETE /api/v1/provisioning/alert-rules/:uidDELETE /apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/alertrules/{name} or .../recordingrules/{name}
GET /api/v1/provisioning/folder/:folderUid/rule-groups/:groupGET .../alertrules or .../recordingrules with labelSelector=grafana.app/folder=<FOLDER_UID>,grafana.com/group=<GROUP>
PUT /api/v1/provisioning/folder/:folderUid/rule-groups/:groupManage individual AlertRule and RecordingRule resources; use RuleSequence for ordered evaluation
DELETE /api/v1/provisioning/folder/:folderUid/rule-groups/:groupDelete individual AlertRule and RecordingRule resources
GET /api/v1/provisioning/alert-rules*/export and .../rule-groups/:group/exportNo equivalent in this API; file-provisioning export remains on the legacy API

When you migrate, consider the following differences:

  • Separate resource kinds: The legacy API uses one ProvisionedAlertRule payload for both alert rules and recording rules (distinguished by whether record is set). The new API separates them into AlertRule (alertrules) and RecordingRule (recordingrules), each with its own validated schema.
  • One resource per rule: You no longer need to PUT an entire rule group to change evaluation intervals or rule membership. Each rule sets its own spec.trigger.interval, and ordered evaluation across rules uses RuleSequence.
  • Metadata placement: uid moves to metadata.name, folderUID moves to metadata.annotations["grafana.app/folder"], and optimistic concurrency uses metadata.resourceVersion.
  • Expressions map: The legacy data array and top-level condition string become spec.expressions, a map keyed by refId where the alert condition or recorded query sets "source": true and relativeTimeRange uses duration strings (such as "from": "5m", "to": "0s") instead of integer seconds.
  • Provenance: Instead of sending the X-Disable-Provenance request header, set metadata.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.

Use the following resources to keep working with Grafana Alerting APIs: