Merge pull request #543 from plausible/apiv2-pagination

APIv2: Add documentation for pagination

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" />

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 }
+}

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}
+  }
+}

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",