From 2d5713e3309224b5574f68427bd9fc2b92213afc Mon Sep 17 00:00:00 2001
From: Stephanie Hingtgen <stephanie.hingtgen@grafana.com>
Date: Wed, 29 Oct 2025 03:26:42 -0600
Subject: [PATCH] Docs: Add information on continue tokens (#113144)

---
 docs/sources/developers/http_api/dashboard.md | 58 ++++++++++++++++++-
 docs/sources/developers/http_api/folder.md    | 52 ++++++++++++++++-
 2 files changed, 108 insertions(+), 2 deletions(-)

diff --git a/docs/sources/developers/http_api/dashboard.md b/docs/sources/developers/http_api/dashboard.md
index f5456a22e77..0c886a83b48 100644
--- a/docs/sources/developers/http_api/dashboard.md
+++ b/docs/sources/developers/http_api/dashboard.md
@@ -634,6 +634,11 @@ Lists all dashboards in the given organization. You can control the maximum numb
 
 - namespace: to read more about the namespace to use, see the [API overview](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/developers/http_api/apis/).
 
+**Query parameters**:
+
+- **`limit`** (optional): Maximum number of dashboards to return
+- **`continue`** (optional): Continue token from a previous response to fetch the next page
+
 **Required permissions**
 
 See note in the [introduction]({{< ref "#dashboard-api" >}}) for an explanation.
@@ -666,7 +671,7 @@ Content-Length: 644
   "apiVersion": "dashboard.grafana.app/v1alpha1",
   "metadata": {
     "resourceVersion": "1741315830000",
-    "continue": "org:1/start:1158/folder:"
+    "continue": "eyJvIjoxNTIsInYiOjE3NjE3MDQyMjQyMDcxODksInMiOmZhbHNlfQ=="
   },
   "items": [
     {
@@ -697,6 +702,57 @@ Content-Length: 644
 }
 ```
 
+The `metadata.continue` field contains a token to fetch the next page.
+
+**Example subsequent request using continue token**:
+
+```http
+GET /apis/dashboard.grafana.app/v1beta1/namespaces/default/dashboards?limit=1&continue=eyJvIjoxNTIsInYiOjE3NjE3MDQyMjQyMDcxODksInMiOmZhbHNlfQ== HTTP/1.1
+Accept: application/json
+Content-Type: application/json
+Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+```
+
+**Example subsequent response**:
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json; charset=UTF-8
+
+{
+  "kind": "DashboardList",
+  "apiVersion": "dashboard.grafana.app/v1alpha1",
+  "items": [
+    {
+      "kind": "Dashboard",
+      "apiVersion": "dashboard.grafana.app/v1alpha1",
+      "metadata": {
+        "name": "hpqcmg",
+        "namespace": "default",
+        "uid": "WQyL7pNTpfGPNlPM6HRJSePrBg5dXmxr4iPQL7txLtwY",
+        "resourceVersion": "1",
+        "generation": 1,
+        "creationTimestamp": "2025-03-06T19:51:31Z",
+        "annotations": {
+          "grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
+          "grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
+          "grafana.app/updatedTimestamp": "2025-03-06T19:51:31Z"
+        }
+      },
+      "spec": {
+        "schemaVersion": 41,
+        "title": "Another dashboard",
+        "uid": "hpqcmg",
+        "version": 1,
+        ...
+      }
+    }
+  ]
+}
+```
+
+Continue making requests with the updated `continue` token until you receive a response without a `continue` field in the metadata, indicating you've reached the last page.
+
 Status Codes:
 
 - **200** – OK
diff --git a/docs/sources/developers/http_api/folder.md b/docs/sources/developers/http_api/folder.md
index cd66653e0e6..bc3b6605db0 100644
--- a/docs/sources/developers/http_api/folder.md
+++ b/docs/sources/developers/http_api/folder.md
@@ -41,6 +41,11 @@ Returns all folders that the authenticated user has permission to view within th
 
 - namespace: to read more about the namespace to use, see the [API overview](ref:apis).
 
+**Query parameters**:
+
+- **`limit`** (optional): Maximum number of folders to return
+- **`continue`** (optional): Continue token from a previous response to fetch the next page
+
 **Required permissions**
 
 See note in the [introduction]({{< ref "#folder-api" >}}) for an explanation.
@@ -67,7 +72,7 @@ Content-Type: application/json
   "kind": "FolderList",
   "apiVersion": "folder.grafana.app/v1beta1",
   "metadata": {
-    "continue": "org:1/start:1158/folder:"
+    "continue": "eyJvIjoxNTIsInYiOjE3NjE3MDQyMjQyMDcxODksInMiOmZhbHNlfQ=="
   },
   "items": [
     {
@@ -93,6 +98,51 @@ Content-Type: application/json
 }
 ```
 
+The `metadata.continue` field contains a token to fetch the next page.
+
+**Example subsequent request using continue token**:
+
+```http
+GET /apis/folder.grafana.app/v1beta1/namespaces/default/folders?limit=1&continue=eyJvIjoxNTIsInYiOjE3NjE3MDQyMjQyMDcxODksInMiOmZhbHNlfQ== HTTP/1.1
+Accept: application/json
+Content-Type: application/json
+Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+```
+
+**Example subsequent response**:
+
+```http
+HTTP/1.1 200
+Content-Type: application/json
+{
+  "kind": "FolderList",
+  "apiVersion": "folder.grafana.app/v1beta1",
+  "items": [
+    {
+      "kind": "Folder",
+      "apiVersion": "folder.grafana.app/v1beta1",
+      "metadata": {
+        "name": "bef30vrzxs3y8e",
+        "namespace": "default",
+        "uid": "YCtv1FXDsJmTYQoTgcPnfuwZhDZge3uMpXOefaOHjb5Y",
+        "resourceVersion": "1741343687000",
+        "creationTimestamp": "2025-03-07T10:35:47Z",
+        "annotations": {
+          "grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
+          "grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
+          "grafana.app/updatedTimestamp": "2025-03-07T10:35:47Z"
+        }
+      },
+      "spec": {
+        "title": "another folder"
+      }
+    }
+  ]
+}
+```
+
+Continue making requests with the updated `continue` token until you receive a response without a `continue` field in the metadata, indicating you've reached the last page.
+
 Status Codes:
 
 - **200** – OK