# Pagination and delta sync

List endpoints return one page at a time, always as an object – never a bare array:

```json
{ "items": [ … ], "nextCursor": "eyJ2IjoxLCJzIjoidXBkYXRlZCIsImsiOlsi…", "total": 342 }
```

| Field | Meaning |
|---|---|
| `items` | the entries of this page; `[]` when there are none |
| `nextCursor` | cursor of the next page; missing on the last page (cursor lists only) |
| `total` | number of entries for the filter, where the list counts; left out where counting would be expensive |

Two styles exist, and the reference of every list endpoint shows which one it uses and its limits:

- **Cursor (keyset) pagination** for collections that keep growing (tickets, items, events, documents,
  messages): stable while data changes, no skipped or repeated entries.
- **Offset pagination** for bounded lists (settings, groups, configuration).

`limit` and `offset` are checked, never adjusted silently: a value that is not a whole number or lies outside the
documented range is a `400 invalid` naming the parameter in `field` (`limit`, `offset`, `cursor`). The search API
pages its hits with `from` and `size` (see its reference) under the same rule; `from + size` is at most 500 (it was
10,000 until November 2026), so a search reaches its 500 best hits.

## Cursor pagination (desk, forge)

Desk and forge lists take `limit` and an opaque `cursor`:

```bash
curl "https://api.mbcom.cloud/api/desk/v1/items?space=SUP&limit=100" -H "Authorization: Bearer $ACCESS_TOKEN"
```

```json
{
  "items": [ { "id": "…", "number": 1234, "title": "…" } ],
  "nextCursor": "eyJ1IjoiMjAyNi0wMy0wMlQwOTozMDowMFoiLCJpIjoiLi4uIn0",
  "total": 342
}
```

Pass `nextCursor` as `cursor` to get the next page; keep every other parameter unchanged. When
`nextCursor` is missing you have reached the end. `limit` defaults to 100 in desk (at most 500) and 50 in forge
(at most 200). The entries and the history of a desk ticket page the same way (`limit` 1–500, default 200); short
lists such as a ticket's links, children or checklist, the configuration lists and the last executions of a desk or
forge automation (at most 50) answer every entry at once (`{ "items": [ … ] }` without `nextCursor`). Workflow's instance list (`GET /api/workflow/v1/instances`) pages the same way (`limit` 1–500,
default 100); its task list (`GET /api/workflow/v1/tasks`) takes `limit` and `offset` and returns `total`. The DMS
document list (`GET /api/dms/v1/documents`) pages by cursor too (`limit` 1–100, default 50) and returns the `total` of
the filter; keep `sort` and the filter unchanged while you follow `nextCursor`. The CRM lists (leads, opportunities,
activities, campaigns, CSAT feedback) and the master data addresses and articles page by cursor as well (`limit`
1–200, default 50, with `total`), whatever their `sort`.
Trade's growing lists page by cursor, newest first: the sales transactions and contracts, and – with the `total` of
the filter on every page – purchase orders, goods receipts, inbound invoices, inbound delivery notes, e-invoice checks
and the stock movements of an article.
Cursors are opaque and short-lived: do not store, build or change them. A cursor belongs to the list and
the sort it came from – used with another `sort`, or altered, it is a `400 invalid` with `field: "cursor"`.

## Offset pagination (HR, comms)

HR and comms lists take `limit` (default 50, at most 200) and `offset` and return `total`:

```bash
curl "https://api.mbcom.cloud/api/hr/v1/employees?status=active&limit=200&offset=200" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```json
{ "items": [ … ], "total": 431 }
```

Increase `offset` by `limit` until `offset >= total`. Offsets can skip or repeat entries when data
changes while you page; for exports sort by a stable key (e.g. `sort=createdAt`).

## Delta sync

To mirror desk items into another system, do not re-read everything. Remember the time of your
last sync and ask only for what changed since:

```bash
curl "https://api.mbcom.cloud/api/desk/v1/items?updatedSince=2026-03-02T09:30:00Z&sort=updated&order=asc&limit=500" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

1. Store the start time of a sync run *before* the first request.
2. Page through all results with `cursor`.
3. Use the stored start time as `updatedSince` of the next run; overlapping a few seconds is fine
   because the result is idempotent per item `id` and `version`.

For near-real-time updates combine delta sync with [webhooks](/guides/webhooks): the webhook tells
you *that* an item changed, the API gives you its current state.

## Filtering and sorting

List endpoints accept filters as query parameters; several values of one filter are
comma-separated (`status=open,waiting`). Desk filters on custom fields use `cf.<key>=<value>`.
Sorting uses `sort` and `order` (desk) or `sort` with a `-` prefix for descending (HR). Filter
values such as statuses, types and priorities are **tenant configuration**: read them from the
module's `bootstrap` endpoint instead of hard-coding them.
