Pagination

Responses from queries that return lists are paginated. We use the Relay style cursor-based pagination model with first/after and last/before pagination arguments. When querying for lists, it is required that you specify a first or last value, and that this value be no more than 100.

For example, to query for the first 10 issues in a workspace, you could do the following:

query workspaceIssuesFromStart($workspaceId: ID!, $endCursor: String) {
  workspace(id: $workspaceId) {
    issues(first: 10, after: $endCursor) {
      nodes {
        id
        repository {
          id
          name
        }
        number
        title
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

To query for the next 10 issues, you would pass the value of pageInfo.endCursor as the after parameter for the next query. You can do this as long as pageInfo.hasNextPage returns true, meaning there is at least one more page or results that can be fetched. Do this enough times and you'll eventually load all the issues for the given workspace.

Similarily, you may traverse the list from the bottom up rather than the top down. To do this, you would simply ask for the last 10 issues and change up the pageInfo part of the query to fetch the startCursor and hasPreviousPage value. These new pageInfo values act in much the same way as before, letting you know if there are more pages to be fetched and where to begin fetching from, it just happens in the opposite direction.

query workspaceIssuesFromEnd($workspaceId: ID!, $startCursor: String) {
  workspace(id: $workspaceId) {
    issues(last: 10, before: $startCursor) {
      nodes {
        id
        repository {
          id
          name
        }
        number
        title
      }
      pageInfo {
        hasPreviousPage
        startCursor
      }
    }
  }
}

Some queries may also provide the ability to specify a parameter which allows you to order the results. Using this ability, it's possible to fetch specific parts of the list, such as the 10 most recent epics that were created in a workspace:

query recentWorkspaceEpics($workspaceId: ID!) {
  workspace(id: $workspaceId) {
    epics(first: 10, orderBy: { field: CREATED_AT, direction: DESC }) {
      nodes {
        id
        issue {
          id
          repository {
            id
            name
          }
          number
          title
        }
      }
    }
  }
}

This may be combined with the page cursors talked about prior to fetch an ordered list.