From 26c6c59797031a3800cd20af493c3236ccf09889 Mon Sep 17 00:00:00 2001
From: Grische <2787581+grische@users.noreply.github.com>
Date: Mon, 20 Apr 2026 13:01:48 +0200
Subject: [PATCH] Fixes #21935: Document MAX_PAGE_SIZE effect on GraphQL
 (#21940)

---
 docs/best-practices/performance-handbook.md | 4 +++-
 docs/configuration/miscellaneous.md         | 6 ++++--
 docs/integrations/graphql-api.md            | 8 +++++++-
 3 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/docs/best-practices/performance-handbook.md b/docs/best-practices/performance-handbook.md
index 5611fb14d..9703a08cd 100644
--- a/docs/best-practices/performance-handbook.md
+++ b/docs/best-practices/performance-handbook.md
@@ -34,7 +34,7 @@ NetBox ships with a reasonable default configuration for most environments, but
 
 #### Reduce the Maximum Page Size
 
-NetBox paginates large result sets to reduce the overall response size. The [`MAX_PAGE_SIZE`](../configuration/miscellaneous.md#max_page_size) parameter specifies the maximum number of results per page that a client can request. This is set to 1,000 by default. Consider lowering this number if you find that API clients are frequently requesting very large result sets.
+NetBox paginates large result sets to reduce the overall response size. The [`MAX_PAGE_SIZE`](../configuration/miscellaneous.md#max_page_size) parameter specifies the maximum number of results per page that a client can request. This is set to 1,000 by default. Consider lowering this number if you find that API clients are frequently requesting very large result sets. `MAX_PAGE_SIZE` applies to both the REST API (`?limit=`) and the GraphQL API (`pagination: {limit: …}`), so lowering it reduces the maximum size of responses from either API.
 
 #### Limit GraphQL Aliases
 
@@ -185,3 +185,5 @@ Like the REST API, the GraphQL API supports pagination. Queries which return a l
   }
 }
 ```
+
+The requested `limit` is capped by [`MAX_PAGE_SIZE`](../configuration/miscellaneous.md#max_page_size).
diff --git a/docs/configuration/miscellaneous.md b/docs/configuration/miscellaneous.md
index 2aa429aa5..382cc8620 100644
--- a/docs/configuration/miscellaneous.md
+++ b/docs/configuration/miscellaneous.md
@@ -45,7 +45,7 @@ Sets content for the top banner in the user interface.
 
 !!! tip
     If you'd like the top and bottom banners to match, set the following:
-    
+
     ```python
     BANNER_TOP = 'Your banner text'
     BANNER_BOTTOM = BANNER_TOP
@@ -171,7 +171,9 @@ This specifies the URL to use when presenting a map of a physical location by st
 
 Default: `1000`
 
-A web user or API consumer can request an arbitrary number of objects by appending the "limit" parameter to the URL (e.g. `?limit=1000`). This parameter defines the maximum acceptable limit. Setting this to `0` or `None` will allow a client to retrieve _all_ matching objects at once with no limit by specifying `?limit=0`.
+Defines the maximum number of objects that may be returned in a single page across the web UI, REST API, and GraphQL API. Setting `MAX_PAGE_SIZE` to `0` or `None` removes the limit.
+
+See the [REST API](../integrations/rest-api.md#pagination) and [GraphQL API](../integrations/graphql-api.md#pagination) pagination documentation for details.
 
 ---
 
diff --git a/docs/integrations/graphql-api.md b/docs/integrations/graphql-api.md
index a05fcbc53..7d3e0950a 100644
--- a/docs/integrations/graphql-api.md
+++ b/docs/integrations/graphql-api.md
@@ -141,7 +141,13 @@ To ensure consistent ordering, objects will always be ordered by their primary k
 
 !!! note "Cursor-based pagination was introduced in NetBox v4.5.2."
 
-Both pagination strategies support passing an optional `limit` parameter. In both approaches, this specifies the maximum number of objects to include in the response. If no limit is specified, a default value of 100 is used.
+Both pagination strategies support an optional `limit` parameter specifying the maximum number of objects to include in the response. The [`MAX_PAGE_SIZE`](../configuration/miscellaneous.md#max_page_size) configuration parameter (default `1000`) sets a hard ceiling on this value; if no limit is specified, up to `MAX_PAGE_SIZE` records are returned.
+
+When `MAX_PAGE_SIZE` is set to `0` or `None`:
+
+* Omitting the `pagination` argument entirely returns all matching records.
+* Supplying `pagination` without a `limit` returns up to Strawberry Django's default of 100 records.
+* Supplying `pagination: {limit: 0}` returns _zero_ records — the opposite of the REST API's `?limit=0` semantics.
 
 ### Offset Pagination