Using pagination in the GraphQL API

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 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:

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 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:

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:

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 the octokit/plugin-paginate-graphql plugin to support pagination in your scripts. For more information, see plugin-paginate-graphql.js.