---
updatedAt: 2026-10-01T07:18:16.000Z
agentTools:
  projectIndex: https://developer.spendesk.com/llms.txt
---

# Pagination

How list endpoints paginate — page-based, cursor or offset — the page-size limits, and what a page past the last one returns.

Endpoints which return a list of objects are paginated. Most use **page-based** pagination; a few newer endpoints use a **cursor**, and one uses an **offset**. Each endpoint's reference page lists the parameters it accepts.

# Page-based pagination

This is the common standard, used for example by [Get Settlements](https://developer.spendesk.com/reference/v1-get-settlements).

## Request

When making a `GET` request, you can specify the following query parameters to control the response:

* `page` - the page number to return, starting at 1 (default: 1);
* `pageSize` - the maximum number of objects to return per page (default and maximum: 30).

For example, the following request would return 30 results, skipping the first 30 on page 1:

`GET /v1/settlements?page=2&pageSize=30`

## Response

In the response there is a `meta` object which contains the following details:

* `page` - the page number returned
* `pageSize` - the maximum number of objects per page
* `total` - the total number of objects

The structure of the `meta` object is:

```json
"meta": {
  "pagination": {
    "page": 2,
    "pageSize": 30,
    "total": 250
  }
}
```

## Retrieving every page

Calculate the number of pages from `total` and `pageSize` — here, 250 objects at 30 per page is 9 pages — and request each page in turn.

> 🚧 A page past the last one returns 404
>
> Requesting a page other than the first that yields no results returns a **404** error rather than an empty list. Stop at the calculated last page, and treat a 404 on a later page as the end of the list. The first page always returns `200`, with an empty `data` array when there is nothing to list.

# Cursor-based pagination

A few endpoints return pages through an opaque **cursor**: [List invoices](https://developer.spendesk.com/reference/v2-list-invoices), [List intakes](https://developer.spendesk.com/reference/v2-list-company-intakes), [List Analytical Field Values](https://developer.spendesk.com/reference/v2-list-analytical-field-values) and [List Expense Categories](https://developer.spendesk.com/reference/v2-list-expense-categories).

## Request

* `limit` - the maximum number of objects to return per page. The default and maximum differ per endpoint (for example 20 and 100 for invoices, 30 and 1,000 for analytical field values) — see each endpoint's reference;
* `cursor` - omit it for the first page, then pass the `nextCursor` value from the previous response. Keep the same filters and sort for every page.

## Response

```json
"meta": {
  "pagination": {
    "limit": 50,
    "hasNextPage": true,
    "nextCursor": "eyJvZmZzZXQiOjUwfQ",
    "nextUrl": "https://public-api.spendesk.com/v2/companies/7j6mvn11rqf7j5/invoices?limit=50&cursor=eyJvZmZzZXQiOjUwfQ"
  }
}
```

* `hasNextPage` - whether more results exist after this page;
* `nextCursor` - the cursor to pass for the next page, or `null` when there are no more results;
* `nextUrl` - a ready-to-follow URL for the next page, with the same filters and the `cursor` already set, or `null`.

Keep requesting pages until `hasNextPage` is `false`. Unlike page-based pagination, a page may legitimately be empty — it is not an error.

## Searching payables

[Search payables](https://developer.spendesk.com/reference/v1-search-payables) takes `cursor` and `limit` in the **request body** rather than the query string, and returns the next cursor as a top-level `nextCursor` field: send it back in the next request's body, and stop when it is `null`.

# Offset-based pagination

[Get accounts](https://developer.spendesk.com/reference/v1-get-accounts) pages with `offset` (the number of accounts to skip, default 0) and `fetch` (the number of accounts to return); `limit` is deprecated in favour of `fetch`. The response reports `totalResults`, `currentOffset` and `currentFetch`.

# Payable snapshots

Snapshots of payables are paged inside their `result` object — see [Retrieving Spend Data](https://developer.spendesk.com/reference/retrieving-snapshots-of-payables).

*Last checked against the Spendesk demo environment on 29 September 2026.*