From 333c3703e4e0eab41fff4ae5fcfcabc99ac267a0 Mon Sep 17 00:00:00 2001
From: Karl-Aksel Puulmann <oxymaccy@gmail.com>
Date: Mon, 16 Sep 2024 09:06:38 +0300
Subject: [PATCH] APIv2: Add documentation for pagination

---
 docs/stats-api-v2.md                          | 19 +++++++++++++++++++
 src/js/apiv2-examples/pagination-query.json   |  8 ++++++++
 .../apiv2-examples/pagination-response.json   | 18 ++++++++++++++++++
 src/js/examples.tsx                           |  6 ++++++
 4 files changed, 51 insertions(+)
 create mode 100644 src/js/apiv2-examples/pagination-query.json
 create mode 100644 src/js/apiv2-examples/pagination-response.json

diff --git a/docs/stats-api-v2.md b/docs/stats-api-v2.md
index 708d3844..8ba57c7b 100644
--- a/docs/stats-api-v2.md
+++ b/docs/stats-api-v2.md
@@ -281,6 +281,21 @@ time labels valid for `date_range`.
 
 [See example](#example-time-labels)
 
+#### include.total_rows {#include.total_rows}
+
+Default: `false`
+
+Should be used for [pagination](#pagination). If true, sets `meta.total_rows` in response containing the total number of
+rows for this query.
+
+[See example](#example-pagination)
+
+### pagination <Optional />
+
+Default: `{ "limit": 10000, "offset: 0 }`
+
+[See example](#example-pagination)
+
 ## Response structure
 
 Example response:
@@ -342,6 +357,10 @@ The query that was executed, after manipulations performed on the backend.
 
 <ApiV2Example id="example-custom-properties" />
 
+### Pagination {#example-pagination}
+
+<ApiV2Example id="example-pagination" />
+
 ### Including imported data {#example-imports}
 
 <ApiV2Example id="example-imports" />
diff --git a/src/js/apiv2-examples/pagination-query.json b/src/js/apiv2-examples/pagination-query.json
new file mode 100644
index 00000000..04668b4c
--- /dev/null
+++ b/src/js/apiv2-examples/pagination-query.json
@@ -0,0 +1,8 @@
+{
+  "site_id": "dummy.site",
+  "metrics": ["visitors", "events", "pageviews"],
+  "date_range": "7d",
+  "dimensions": ["visit:utm_medium", "visit:utm_source"],
+  "include": { "total_rows": true },
+  "pagination": { "limit": 3, "offset": 1 }
+}
diff --git a/src/js/apiv2-examples/pagination-response.json b/src/js/apiv2-examples/pagination-response.json
new file mode 100644
index 00000000..91035d8d
--- /dev/null
+++ b/src/js/apiv2-examples/pagination-response.json
@@ -0,0 +1,18 @@
+{
+  "results": [
+    {"metrics": [325, 397, 317], "dimensions": ["(not set)", "duckduckgo"]},
+    {"metrics": [311, 369, 295], "dimensions": ["(not set)", "google"]},
+    {"metrics": [296, 357, 292], "dimensions": ["social", "twitter"]}
+  ],
+  "meta": {"total_rows": 6},
+  "query": {
+    "site_id": "dummy.site",
+    "metrics": ["visitors", "events", "pageviews"],
+    "date_range": ["2024-09-10T00:00:00+00:00", "2024-09-16T23:59:59+00:00"],
+    "filters": [],
+    "dimensions": ["visit:utm_medium", "visit:utm_source"],
+    "order_by": [["visitors", "desc"]],
+    "include": {"total_rows": true},
+    "pagination": {"offset": 1, "limit": 3}
+  }
+}
diff --git a/src/js/examples.tsx b/src/js/examples.tsx
index a16524a8..6231c0d1 100644
--- a/src/js/examples.tsx
+++ b/src/js/examples.tsx
@@ -51,6 +51,12 @@ const EXAMPLES = [
     query: read("apiv2-examples/custom-properties-query.json"),
     exampleResponse: read("apiv2-examples/custom-properties-response.json"),
   },
+  {
+    id: "example-pagination",
+    title: "Pagination for UTM sources",
+    query: read("apiv2-examples/pagination-query.json"),
+    exampleResponse: read("apiv2-examples/pagination-response.json")
+  },
   {
     id: "example-imports",
     title: "Including imported data",