From 0b6c55f5033cf52f569b86c1ae363a0f2f6ac65a Mon Sep 17 00:00:00 2001
From: "Johnny K." <johnny.kartheiser@grafana.com>
Date: Mon, 12 Jan 2026 14:17:41 -0600
Subject: [PATCH] recording rule provisioning

---
 .../shared/alerts/alerting_provisioning.md    | 99 +++++++++++++++++++
 1 file changed, 99 insertions(+)

diff --git a/docs/sources/shared/alerts/alerting_provisioning.md b/docs/sources/shared/alerts/alerting_provisioning.md
index 05885168fdf..d23f8fb53af 100644
--- a/docs/sources/shared/alerts/alerting_provisioning.md
+++ b/docs/sources/shared/alerts/alerting_provisioning.md
@@ -23,6 +23,8 @@ The `export` endpoints allow you to export alerting resources in a JSON format s
 
 ### Alert rules
 
+The following endpoints can be used to manage both alert rules and recording rules. To create a recording rule, include a `record` block in your request instead of a `condition` field.
+
 | Method | URI                                                              | Name                                                                    | Summary                                                 |
 | ------ | ---------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------- |
 | DELETE | /api/v1/provisioning/alert-rules/:uid                            | [route delete alert rule](#route-delete-alert-rule)                     | Delete a specific alert rule by UID.                    |
@@ -215,6 +217,103 @@ Content-Type: application/json
 }
 ```
 
+**Example request for new recording rule:**
+
+Recording rules allow you to pre-compute frequently used or computationally expensive expressions and save the results as new time series data. To create a recording rule instead of an alert rule, include a `record` block in your request.
+
+The `record` block contains the following fields:
+
+- `metric`: The name of the new metric to create
+- `from`: The `refId` of the query whose value will be used for the recording
+- `target_datasource_uid`: The UID of the data source where the metric will be written
+
+```http
+POST /api/v1/provisioning/alert-rules
+Accept: application/json
+Content-Type: application/json
+Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+
+{
+  "folderUID": "IpGEy0u7k",
+  "ruleGroup": "Testing",
+  "title": "test-grafana-recording-rule-2",
+  "condition": "",
+  "data": [
+    {
+      "refId": "A",
+      "queryType": "",
+      "relativeTimeRange": {
+        "from": 600,
+        "to": 0
+      },
+      "datasourceUid": "grafanacloud-prom",
+      "model": {
+        "expr": "up{job=\"integrations/macos-node\",instance=\"Bojans-MacBook-Pro.local\"}",
+        "instant": true,
+        "intervalMs": 1000,
+        "legendFormat": "__auto",
+        "maxDataPoints": 43200,
+        "range": false,
+        "refId": "A"
+      }
+    },
+    {
+      "refId": "B",
+      "queryType": "",
+      "relativeTimeRange": {
+        "from": 0,
+        "to": 0
+      },
+      "datasourceUid": "__expr__",
+      "model": {
+        "conditions": [
+          {
+            "evaluator": {
+              "params": [],
+              "type": "gt"
+            },
+            "operator": {
+              "type": "and"
+            },
+            "query": {
+              "params": [
+                "B"
+              ]
+            },
+            "reducer": {
+              "params": [],
+              "type": "last"
+            },
+            "type": "query"
+          }
+        ],
+        "datasource": {
+          "type": "__expr__",
+          "uid": "__expr__"
+        },
+        "expression": "A",
+        "intervalMs": 1000,
+        "maxDataPoints": 43200,
+        "reducer": "last",
+        "refId": "B",
+        "type": "reduce"
+      }
+    }
+  ],
+  "noDataState": "",
+  "execErrState": "",
+  "for": "0s",
+  "keep_firing_for": "0s",
+  "isPaused": false,
+  "notification_settings": null,
+  "record": {
+    "metric": "grafana_recording_rule_test_2",
+    "from": "B",
+    "target_datasource_uid": "grafanacloud-prom"
+  }
+}
+```
+
 ### Contact points
 
 | Method | URI                                        | Name                                                              | Summary                                                |