From c2d19119cb8c8b4d07f9859d465771b1eba4fcea Mon Sep 17 00:00:00 2001
From: Arthur <worldnomad@gmail.com>
Date: Tue, 14 Oct 2025 13:54:58 -0700
Subject: [PATCH] 19724 update documentation

---
 docs/integrations/graphql-api.md | 84 +++++++++++++++++++++++---------
 1 file changed, 62 insertions(+), 22 deletions(-)

diff --git a/docs/integrations/graphql-api.md b/docs/integrations/graphql-api.md
index 39309671c..7a093e3c5 100644
--- a/docs/integrations/graphql-api.md
+++ b/docs/integrations/graphql-api.md
@@ -11,7 +11,7 @@ curl -H "Authorization: Token $TOKEN" \
 -H "Content-Type: application/json" \
 -H "Accept: application/json" \
 http://netbox/graphql/ \
---data '{"query": "query {circuit_list(filters:{status: STATUS_ACTIVE}) {cid provider {name}}}"}'
+--data '{"query": "query {circuit_list(filters:{status: STATUS_ACTIVE}) {results {cid provider {name}}}}"}'
 ```
 
 The response will include the requested data formatted as JSON:
@@ -19,20 +19,22 @@ The response will include the requested data formatted as JSON:
 ```json
 {
   "data": {
-    "circuits": [
-      {
-        "cid": "1002840283",
-        "provider": {
-          "name": "CenturyLink"
+    "circuit_list": {
+      "results": [
+        {
+          "cid": "1002840283",
+          "provider": {
+            "name": "CenturyLink"
+          }
+        },
+        {
+          "cid": "1002840457",
+          "provider": {
+            "name": "CenturyLink"
+          }
         }
-      },
-      {
-        "cid": "1002840457",
-        "provider": {
-          "name": "CenturyLink"
-        }
-      }
-    ]
+      ]
+    }
   }
 }
 ```
@@ -63,7 +65,9 @@ query {
       status: STATUS_ACTIVE
     }
   ) {
-    name
+    results {
+      name
+    }
   }
 }
 ```
@@ -84,7 +88,9 @@ query {
       }
     }
   ) {
-    name
+    results {
+      name
+    }
   }
 }
 ```
@@ -94,10 +100,12 @@ Filtering can also be applied to related objects. For example, the following que
 ```
 query {
   device_list {
-    id
-    name
-    interfaces(filters: {enabled: true}) {
+    results {
+      id
       name
+      interfaces(filters: {enabled: true}) {
+        name
+      }
     }
   }
 }
@@ -109,7 +117,8 @@ Certain queries can return multiple types of objects, for example cable terminat
 
 ```
 {
-    cable_list {
+  cable_list {
+    results {
       id
       a_terminations {
         ... on CircuitTerminationType {
@@ -126,6 +135,7 @@ Certain queries can return multiple types of objects, for example cable terminat
         }
       }
     }
+  }
 }
 ```
 
@@ -133,16 +143,46 @@ The field "class_type" is an easy way to distinguish what type of object it is w
 
 ## Pagination
 
-Queries can be paginated by specifying pagination in the query and supplying an offset and optionaly a limit in the query.  If no limit is given, a default of 100 is used.  Queries are not paginated unless requested in the query. An example paginated query is shown below:
+All list queries return paginated results using the `OffsetPaginated` type, which includes:
+
+- `results`: The list of objects matching the query
+- `total_count`: The total number of objects matching the filters (without pagination)
+- `page_info`: Pagination metadata including `offset` and `limit`
+
+By default, queries return up to 100 results. You can control pagination by specifying the `pagination` parameter with `offset` and `limit` values:
 
 ```
 query {
   device_list(pagination: { offset: 0, limit: 20 }) {
-    id
+    total_count
+    page_info {
+      offset
+      limit
+    }
+    results {
+      id
+      name
+    }
   }
 }
 ```
 
+If you don't need pagination metadata, you can simply query the `results`:
+
+```
+query {
+  device_list {
+    results {
+      id
+      name
+    }
+  }
+}
+```
+
+!!! note
+    When not specifying the `pagination` parameter, avoid querying `page_info.limit` as it may return an undefined value. Either provide explicit pagination parameters or only query the `results` and `total_count` fields.
+
 ## Authentication
 
 NetBox's GraphQL API uses the same API authentication tokens as its REST API. Authentication tokens are included with requests by attaching an `Authorization` HTTP header in the following form: