Pagination and sorting

Control the order and paging of collection results using the sort, page, limit, and pagination query parameters.

Prerequisites:

A valid API key (see How to authenticate)
A resolved tenant context (see Understanding multi-tenancy)

Steps

1. Sort by a single field

Pass the sort parameter with a field name. Results are sorted in ascending order by default.

curl -s \
  -H "Authorization: users API-Key a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-basker-tenant-slug: royal-opera-house" \
  "https://api.basker.app/partners/2026-02/royal-opera-house/events?sort=startDate"

Result: Events sorted by startDate from earliest to latest.

2. Sort in descending order

Prefix the field name with - to sort in descending order.

curl -s \
  -H "Authorization: users API-Key a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-basker-tenant-slug: royal-opera-house" \
  "https://api.basker.app/partners/2026-02/royal-opera-house/events?sort=-startDate"

Result: Events sorted by startDate from latest to earliest.

3. Sort by multiple fields

Separate multiple field names with commas. Each field can independently have a - prefix.

curl -s \
  -H "Authorization: users API-Key a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-basker-tenant-slug: royal-opera-house" \
  "https://api.basker.app/partners/2026-02/royal-opera-house/events?sort=-startDate,title"

Result: Events sorted by startDate descending first, then by title ascending for events with the same start date.

4. Set the page size

Use the limit parameter to control how many documents are returned per page.

curl -s \
  -H "Authorization: users API-Key a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-basker-tenant-slug: royal-opera-house" \
  "https://api.basker.app/partners/2026-02/royal-opera-house/events?limit=5"

Result: At most 5 events per page.

5. Navigate to a specific page

Use the page parameter to request a specific page. Pages are 1-indexed.

curl -s \
  -H "Authorization: users API-Key a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-basker-tenant-slug: royal-opera-house" \
  "https://api.basker.app/partners/2026-02/royal-opera-house/events?limit=5&page=3"

Result: The third page of results (events 11--15, assuming 5 per page).

6. Read pagination metadata

Every list response includes pagination fields:

{
  "docs": [],
  "totalDocs": 47,
  "limit": 5,
  "totalPages": 10,
  "page": 3,
  "pagingCounter": 11,
  "hasPrevPage": true,
  "hasNextPage": true,
  "prevPage": 2,
  "nextPage": 4
}

Field	Type	Description
`totalDocs`	number	Total documents matching the query
`limit`	number	Documents per page
`totalPages`	number	Total number of pages
`page`	number	Current page number
`pagingCounter`	number	Index of the first document on this page (1-indexed)
`hasPrevPage`	boolean	Whether a previous page exists
`hasNextPage`	boolean	Whether a next page exists
`prevPage`	number or null	Previous page number, or `null` if on the first page
`nextPage`	number or null	Next page number, or `null` if on the last page

7. Disable pagination

To retrieve all documents in a single response, set pagination=false. This removes page-based metadata from the response.

curl -s \
  -H "Authorization: users API-Key a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-basker-tenant-slug: royal-opera-house" \
  "https://api.basker.app/partners/2026-02/royal-opera-house/venues?pagination=false"

Result: All venues returned in a single docs array without page metadata.

Result

When complete, you will have:

Sorted results by one or more fields in ascending or descending order
Controlled page size and navigated between pages
Used pagination metadata to build page navigation

Verify: The page, totalPages, hasPrevPage, and hasNextPage fields in the response match your expectations.

Troubleshooting

Sort does not appear to work Check the field name is correct and sortable. Relationship fields cannot be sorted by their populated values; sort by the raw ID field instead.

Page number exceeds total pages If page is greater than totalPages, the docs array is empty. Check totalPages first and constrain your page number.

How to filter results -- narrowing results before sorting
How to select fields -- reducing response size
Query parameters reference -- all parameters with types and defaults

Pagination and sorting

On this page