Pagination

Overview

StackOne's Unified API allows paginating the API requests. Pagination is a modern way to fetch the data in bulk. Iterating through thousands of data pages can be done using the advanced optional next parameter.
It is often called cursor pagination.

Mechanism

The legacy approach of StackOne API was to pass page parameter to identify which page of data has to be returned in response. Now, when making the first API request and if the response contains over 25 records, you will get next value of a string type. This property can be passed as a query string parameter for subsequent requests until the next value becomes NULL.

Sample scenario

For example, you want to list all employees for the BambooHR integration. You have around 525 employees configured. In such a case, StackOne returns the next parameter string value on the first request. Then, you can iteratively get the new value of next parameter to get all the remaining employee records.

Sample response

In the response payload, you can find the next cursor.

"next":"eyJyIjphAsHHere",
"data":[
   0: [...],
   1: [...],
   ...
   24: [...],
]

Once the cursor reaches the end of the data list, both values become NULL.

Page Size

By default, the page_size parameter is set to 25 results per page. You can increase page size to up to 100. If fewer records remain in the underlying connected provider than a given page_size, you will not receive a next cursor value on the next request.

For example, if you have 17 records in total, all of them will be shown on one page with next parameter being empty. Then you specify the page_size = 10, you'll get the nextvalue. If you use this next value, you will get a stripped array of the last 7 records.

📘

Important:

To optimize the number of requests made to the underlying providers, if a specific request takes longer than expected, we may return fewer results than the requested page size. This does not imply that additional results are unavailable; rather, we prioritize returning the results already retrieved to prevent the entire request from timing out. If the value of the next cursor is not null, it indicates that more results are available for retrieval.