# 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:

```bash
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`](/api/smartsheet/openapi/workspaces/list-workspaces) operation.
Response:

```javascript
{
    "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:

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

```javascript
{
    "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](/api/smartsheet/guides/basics/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](/api/smartsheet/guides/basics/pagination-sdk-examples) that demonstrate paging through items using various langauges, including Python, Java, JavaScript/Node.js, and C#.