Add new doc demonstrating how to traverse using pagination with our GraphQL API (#46563)

Co-authored-by: skedwards88 <skedwards88@github.com>

content/graphql/guides/forming-calls-with-graphql.md

@@ -407,7 +407,7 @@ For more information on the difference between enums and strings, see the [offic
 
 There is a _lot_ more you can do when forming GraphQL calls. Here are some places to look next:
 
-- [Pagination](https://graphql.org/learn/pagination/)
+- [AUTOTITLE](/graphql/guides/using-pagination-in-the-graphql-api)
 - [Fragments](https://graphql.org/learn/queries/#fragments)
 - [Inline fragments](https://graphql.org/learn/queries/#inline-fragments)
 - [Directives](https://graphql.org/learn/queries/#directives)

content/graphql/guides/index.md

@@ -16,8 +16,8 @@ children:
   - /using-global-node-ids
   - /migrating-from-rest-to-graphql
   - /using-the-explorer
+  - /using-pagination-in-the-graphql-api
   - /managing-enterprise-accounts
   - /using-the-graphql-api-for-discussions
   - /migrating-graphql-global-node-ids
 ---
-

content/graphql/guides/introduction-to-graphql.md

@@ -71,7 +71,7 @@ It's helpful to picture a graph: dots connected by lines. The dots are nodes, th
 
 ## Edge
 
-Edges represent connections between nodes. When you query a connection, you traverse its edges to get to its nodes. Every `edges` field has a `node` field and a `cursor` field. Cursors are used for [pagination](https://graphql.github.io/learn/pagination/).
+Edges represent connections between nodes. When you query a connection, you traverse its edges to get to its nodes. Every `edges` field has a `node` field and a `cursor` field. Cursors are used for pagination. For more information, see "[AUTOTITLE](/graphql/guides/using-pagination-in-the-graphql-api)."
 
 ## Node
 

content/graphql/guides/using-pagination-in-the-graphql-api.md

@@ -0,0 +1,101 @@
+---
+title: Using pagination in the GraphQL API
+intro: Learn how to traverse data sets using cursor based pagination with the GraphQL API.
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghae: '*'
+  ghec: '*'
+topics:
+  - API
+shortTitle: Pagination
+---
+
+## About pagination
+
+{% data variables.product.company_short %}'s GraphQL API limits the number of items that you can fetch in a single request in order to protect against excessive or abusive requests to GitHub's servers. When you use the GraphQL API, you must supply a `first` or `last` argument on any connection. The value of these arguments must be between 1 and 100. The GraphQL API will return the number of connections specified by the `first` or `last` argument.
+
+If the data that you are accessing has more connections than the number of items specified by the `first` or `last` argument, the response is divided into smaller "pages" of the specified size. These pages can be fetched one at a time until the entire data set has been retrieved. Each page contains the number of items specified by the `first` or `last` argument, unless it is the last page, which may contain a lower number of items.
+
+This guide demonstrates how to request additional pages of results for paginated responses, how to change the number of results returned on each page, and how to write a script to fetch multiple pages of results.
+
+## Requesting a `cursor` in your query
+
+When using the GraphQL API, you use cursors to traverse through a paginated data set. The cursor represents a specific position in the data set. You can get the first and last cursor on a page by querying the `pageInfo` object. For example:
+
+```graphql
+query($owner: String!, $name: String!) {
+  repository(owner: $owner, name: $name) {
+    pullRequests(first: 100, after: null) {
+      nodes {
+        createdAt
+        number
+        title
+      }
+      pageInfo {
+        endCursor
+        startCursor
+        hasNextPage
+        hasPreviousPage
+      }
+    }
+  }
+}
+```
+
+In this example, `pageInfo.startCursor` gives the cursor for the first item on the page. `pageInfo.endCursor` gives the cursor for the last item on the page. `pageInfo.hasNextPage` and `pageInfo.hasPreviousPage` indicate whether there is a page before and after the page that was returned.
+
+## Changing the number of items per page
+
+The `first` and `last` arguments control how many items are returned. The maximum number of items you can fetch using the `first` or `last` argument is 100. You may need to request fewer than 100 items if your query touches a lot of data in order to avoid hitting a rate or node limit. For more information, see "[AUTOTITLE](/graphql/overview/rate-limits-and-node-limits-for-the-graphql-api)."
+
+## Traversing the data set using pagination
+
+Once you return a cursor from a query, you can use the cursor to request the next page of results. To do so, you will use the `after` or `before` argument and the cursor.
+
+For example, assuming the `pageInfo.endCursor` value from the previous example was `Y3Vyc29yOnYyOpHOUH8B7g==`, you can use this query to request the next page of results:
+
+```graphql
+query($owner: String!, $name: String!) {
+  repository(owner: $owner, name: $name) {
+    pullRequests(first: 1, after: "Y3Vyc29yOnYyOpHOUH8B7g==") {
+      nodes {
+        createdAt
+        number
+        title
+      }
+      pageInfo {
+        endCursor
+        hasNextPage
+        hasPreviousPage
+      }
+    }
+  }
+}
+```
+
+You can continue to send queries with the new `pageInfo.endCursor` value returned in the response until there are no pages left to traverse, indicated by `pageInfo.hasNextPage` returning `false`.
+
+If you specified the `last` instead of the `first` argument, the last page of results will be returned first. In this case, you will use the `pageInfo.startCursor` value and the `before` argument to get the previous page of results. Once `pageInfo.hasPreviousPage` returns `false`, you have reached the last page. For example:
+
+```graphql
+query($owner: String!, $name: String!) {
+  repository(owner: $owner, name: $name) {
+    pullRequests(last: 1, before: "R3Vyc29yOnYyOpHOHcfoOg==") {
+      nodes {
+        createdAt
+        number
+        title
+      }
+      pageInfo {
+        startCursor
+        hasPreviousPage
+      }
+    }
+  }
+}
+```
+
+## Next steps
+
+You can use {% data variables.product.company_short %}'s Octokit SDK and the `octokit/plugin-paginate-graphql` plugin to support pagination in your scripts. For more information, see "[plugin-paginate-graphql.js](https://github.com/octokit/plugin-paginate-graphql.js)."

content/graphql/index.md

@@ -13,7 +13,7 @@ featuredLinks:
     - /graphql/overview/explorer
     - /graphql/overview/public-schema
     - /graphql/overview/schema-previews
-    - /graphql/guides/using-the-graphql-api-for-discussions
+    - /graphql/guides/using-pagination-in-the-graphql-api
   guideCards:
     - /graphql/guides/migrating-from-rest-to-graphql
     - /graphql/guides/managing-enterprise-accounts
@@ -33,4 +33,3 @@ children:
   - /reference
   - /guides
 ---
-