If I call /rest/api/3/search?jql=project is not EMPTY, it’ll return every issue in the instance from a project that isn’t empty.  That’s potentially a lot of issues. 

However if we look at the results that are returned, there are some meta attributes in addition to the issues themselves.  In our example, the JSON that is returned starts with this:

{
"expand": "schema,names",
"startAt": 0,
"maxResults": 50,
"total": 35,

From this, we see that the number of results returned by default is 50, as we have not specified another value. Let’s try calling the same API endpoint, but we specify maxResults.   We do this by tacking maxResults onto the end: /rest/api/3/search?jql=project is not EMPTY&maxResults=200

Here are the results:

{
	"expand": "schema,names",
	"startAt": 0,
	"maxResults": 100,
	"total": 35,	

Okay so we’ve affected the maxResults value, but it’s only 100.   This tell us that the maximum number of results that the API will return to us on a single page is 100.   How do we get the rest?  We use pagination.

Pagination literally means that we’re going through the pages of results, rather than working with a single page of results that is returned. APIs do this to ensure that they don’t get overloaded while processing, and that your system doesn’t get overloaded by the results.  The meta-attributes we’ve been looking at give us all the information we need to paginate through the list of issues.  Let’s examine them one at a time.

If you imagine that the list of possible results is 1000 issues long, and that each issue is assigned a number in that list, startAt is the issue that leads the page of results.  In other words, if we specify startAt to be 50, the page of results that is returned will start at item #50 and run to #150.

We already know what maxResults is.

Total is, simply, the number of results that were returned on the given page.

With these, we have the pieces we need to paginate through the entire list. 

Here’s a basic script that performs pagination:

def maxResults = 100
def startAt = 0
def stillPaginating = true

//Define the global variables

while (stillPaginating == true){
   
    //We need to paginate through the results
    //We're iterating by 100 results at a time
   
    def getIssueKeys = get("/rest/api/3/search?jql=project%20is%20not%20EMPTY&maxResults=${maxResults}&startAt=${startAt}")
        .header('Content-Type', 'application/json')
        .asObject(Map)
    //We start by returning all of the issues in the instance with a JQL search
   
    getIssueKeys.body.issues.each{ issueKey ->
   
       //do something with the issues
   
            if(getIssueKeys.body.total < maxResults){
            stillPaginating = false;
        }
        //Finally, we check to see if we're still paginating
        //If the total number of results is less than the total number of maximum possible results,
        //We must be at the end of the line and can stop paginating by terminating the loop
       startAt += 100
}

The first thing we do is define our maxResults and the startAt values.  We also define a boolean object, stillPaginating, and set it to true by default.

Next we define a while loop. This loop runs as long as stillPaginating remains true.   

We make an HTTP  GET request to the API endpoint that we’ve been discussing. This request takes the two values that we already defined, maxResults and startAt.

Presumably you’d want to do something with the issue keys that are returned, so we have a loop that does that.   We also check to see if the number of results that were returned were less than the maximum possible results.  In other words, if 35 results were returned by maxResults was 100, we can assume that we’ve reached the end of the list of possible results.  If this is the case, we break the loop by setting the value of stillPaginating to false.

If we’re still receiving full pages of results, we increment startAt by 100 and continue looping.