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:

• paginationType: (Available for some endpoints) If the endpoint has this parameter, set it to token to use token-based pagination.
• 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.

cURL: Token-based pagination

Here's how to page through 100 workspaces at a time using cURL:

1. Make your initial call with the following query parameter settings:

   • maxItems=100
   • paginationType=token (if the endpoint supports this parameter)

   Request:

   curl https://api.smartsheet.com/2.0/workspaces?maxItems=100&paginationType=token \
   -H "Authorization: Bearer YOUR_API_TOKEN"

   Note: This example calls the GET /workspaces operation.

   Response:

   {
       "data": [
           {
               // workspace 1
           },
           // ... more workspaces
           {
               // workspace 100
           }
       ],
       "lastKey": "XYZ123ABC456"
   }

   The response includes 100 workspaces and a lastKey property, because there are more workspaces.

2. To get the next page, call the endpoint again with the same parameters plus lastKey, set to the lastKey value from the previous response.

   Note: You can continue to get more pages, using the lastKey from the previous response. If a response doens't include lastKey, you've paged through all the items.

   Request:

   curl https://api.smartsheet.com/2.0/workspaces?maxItems=100&paginationType=token&lastKey=XYZ123ABC456 \
   -H "Authorization: Bearer YOUR_API_TOKEN"

   Response:

   {
       "data": [
           {
               // workspace 101
           },
           // ... more workspaces
           {
               // workspace 121
           }
       ],
   }

   The response includes 21 more workspaces and no lastKey, because there arent' any more workspaces.

Note: Refer to Pagination - SDK examples for token-based pagination using various langauges, including Python, Java, JavaScript/Node.js, and C#.

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.

What's next

Explore Pagination - SDK examples that demonstrate paging through items using various langauges, including Python, Java, JavaScript/Node.js, and C#.