# API Reference Pagination v3

**URL:** <https://community.bluescape.com/t/api-reference-pagination-v3/626>\
**Category:** Developer\
**Tags:** api\
**Created:** [September 30, 2022, 6:22pm UTC](https://community.bluescape.com/t/api-reference-pagination-v3/626 "2022-09-30T18:22:12Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![Tom\_Garrett](https://avatars.discourse-cdn.com/v4/letter/t/258eb7/32.png) [@Tom\_Garrett](https://community.bluescape.com/u/Tom_Garrett)\
**Post date:** [September 30, 2022, 6:22pm UTC](https://community.bluescape.com/t/api-reference-pagination-v3/626/1 "2022-09-30T18:22:12Z")

</div>

# API Reference Pagination

**NOTICE: In the current `/v3/` GA version, the pagination mechanism has changed. The new cursor-based pagination uses different URL query parameters depending on whether it is the initial request for a collection or a subsequent request. For pagination information related to `/v2/` endpoints, please see [here](https://community.bluescape.com/t/api-reference-v2/638).**

API endpoints that can return large numbers of objects return their results using a cursor-based paging mechanism to improve performance. Applications can specify `limit` in the initial request to control what subset of the results are returned to them. The initial request’s result includes cursors for navigating backward and forward in increments of the provided limit. Subsequent requests should only provide these cursors to continue pagination.

- The `limit` parameter sets a maximum number of results to return per call. (defaults to a value of 25).
- The `cursor` parameter sets the cursor string to navigate next and previous requests. (defaults to a base64 encoded string).

### A sample initial request

For an application displaying a user’s workspaces 1 record at a time based on the specified query parameters, the API endpoint would look like this:

`/v3/users/me/workspaces?limit=1&filterBy=(name eq bob)&orderBy=name desc`

The results retrieved from an endpoint that returns paginated results should have a `prev` and `next` cursor, as well as additional related information to paging:

- the set of results
- the prev string can be used to request the previous page of results
- the next string can be used to request the next page of results
- the totalItems integer reflects the total number of items that match the query

> **A sample initial response**
>
> ```auto
> {
> "workspaces":[ //the results array
> {
> "id": "zYecVV0l2hppIhMSpdkL",
> "name": "workspace 1"
> }
> ],
> "prev": null, // previous cursor is null in the initial request
> "next": "ZFJOWjtLtjBSOdP5XXdvkQzK2hRQ81WuoYKvQbnqSDK", // next cursor navigates to subsequent requests
> "totalItems": 1 // the total number of items that match the query
> }
> A sample subsequent request
> After the initial request, the specified query parameters cannot be changed as they are included in the cursor which is opaque to the user:
> 
> /v3/users/me/workspaces?cursor=ZFJOWjtLtjBSOdP5XXdvkQzK2hRQ81WuoYKvQbnqSDK
> 
> ```

### A sample subsequent request

After the initial request, the specified query parameters cannot be changed as they are included in the cursor which is opaque to the user:

/v3/users/me/workspaces?cursor=ZFJOWjtLtjBSOdP5XXdvkQzK2hRQ81WuoYKvQbnqSDK

> **A sample subsequent response**
>
> ```auto
> {
> "workspaces":[ //the results array
> {
> "id": "4MbstEfKhPixXKRnSY7Z",
> "name": "workspace 2"
> }
> ],
> "prev": "WOsxk6rPfmJ82bLCnweOF1iZz4fJcU0RURgyGjgsPJ5b7RUgg", // previous cursor points to the last request
> "next": "wFkZLNx+jnly3wRUMfUjzGv2gEMEpKWXDyHjCGtwRQ7IG", // next cursor navigates to subsequent requests
> "totalItems": 1 // the total number of items that match the query
> }
> 
> ```

# Where to Next?

> - [API Reference Permissions v3](https://community.bluescape.com/t/api-reference-permissions-v3/627)
> - [Bluescape API Guides Landing Page](https://community.bluescape.com/t/wip-bluescape-api-guides-landing-page/2020)
> - [Bluescape API Overview](https://community.bluescape.com/t/wip-bluescape-api-overview/2021/2)

**Not what you were looking for? Reply below or [Search](https://community.bluescape.com/search) the community and discover more Bluescape.**