Pagination

Pagination is a mechanism for dividing a large set of data into smaller, manageable chunks called pages. With large data sets, it's often impractical or inefficient to return them all in a single response. Pagination addresses this by letting you request data in smaller increments. This improves performance, reduces network latency, and conserves resources for you and for Smartsheet. Without pagination, requests for large datasets can cause slow response times, excessive memory consumption, and potential timeouts.

The Smartsheet endpoints use one of the following pagination strategies:

• Token-based pagination
• Offset-based pagination

We'll explore both here.

Token-based pagination

The Smartsheet API supports token-based pagination for some endpoints. With token-based pagination, an endpoint retrieves the number of items specified in your request. If more remain, it returns a token that marks its place in the data set. To retrieve the next page of items, you simply pass in the token in a subsequent request.

NOTE: The token value is opaque and arbitrary, carrying no inherent meaning or significance.

To retrieve a page of results, you specify these parameters:

• maxItems: The maximum amount of items to retrieve in a single request. While the number of items returned won't exceed this value, it's not guaranteed to return exactly maxItems. It's possible that fewer items, or even no items, are returned. If more items exist beyond the current response, the response includes a lastKey property that contains a token.
• lastKey: If your previous call to the endpoint indicated more items remained (that is, the response included a lastKey property with a token value), set this parameter to that token to retrieve the next page of results. If you omit lastKey, the endpoint returns the first page of results.

For example, here's how to retrieve 100 items per page:

1. Make your initial call with maxItems=100 and without including lastKey. The response includes up to 100 items (if they exist) and a lastKey property (if more items are available).
2. To get the next page, call the endpoint again, setting maxItems=100 and passing the lastKey value from the previous response. The endoint returns up to 100 more items (if they exist) and a new lastKey if more items are still available.

Offset-based pagination

Offset-based pagination, sometimes called limit-offset pagination, is a common method where you retrieve a specific page of results by specifying a starting point and the number of items to return.

To retrieve a page of results, you specify these parameters:

• pageSize: The maximum number of items to return in a single response.
• page: The number of the page you want to retrieve.

For example, if you want to retrieve the second page of results with 100 items per page, you would set pageSize=100 and page=2. The first page would be pageSize=100 and page=1.