About pagination

GitHub'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 afirst orlast 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 thefirst orlast argument.

If the data that you are accessing has more connections than the number of items specified by thefirst orlast 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 thefirst orlast 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 acursor 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 thepageInfo object. For example:

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 andpageInfo.hasPreviousPage indicate whether there is a page before and after the page that was returned.

Changing the number of items per page

Thefirst andlast arguments control how many items are returned. The maximum number of items you can fetch using thefirst orlast 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, seeRate 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 theafter orbefore argument and the cursor.

For example, assuming thepageInfo.endCursor value from the previous example wasY3Vyc29yOnYyOpHOUH8B7g==, you can use this query to request the next page of results:

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 newpageInfo.endCursor value returned in the response until there are no pages left to traverse, indicated bypageInfo.hasNextPage returningfalse.

If you specified thelast instead of thefirst argument, the last page of results will be returned first. In this case, you will use thepageInfo.startCursor value and thebefore argument to get the previous page of results. OncepageInfo.hasPreviousPage returnsfalse, you have reached the last page. For example:

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 GitHub's Octokit SDK and theoctokit/plugin-paginate-graphql plugin to support pagination in your scripts. For more information, seeplugin-paginate-graphql.js.