> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomarketbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> Cursor-based pagination used on the API's large lists.

The MarketBox API's large lists use **cursor-based pagination**.
There are no page numbers — you ask for a page of results, and the
response tells you whether more exist.

A few small or windowed lists return everything in one response, with no
`cursor` and no `nextCursor`: locations and skills
([Locations and skills](https://docs.gomarketbox.com/resources/locations.md)), and the supplier plane's
lists — bookings in a window, schedules, blocked times, travel zones and
venues ([Supplier portal: bookings](https://docs.gomarketbox.com/guides/supplier-portal-bookings.md) and
[Supplier portal: availability](https://docs.gomarketbox.com/guides/supplier-portal-availability.md)). Each
endpoint's reference says which kind it is.

The catalog lists — `GET .../services` and, under a service, its offerings,
packages and business models — also return everything in one response. They take no `limit` or `cursor`, but their body still
carries `nextCursor`, and it is always `null`. Code that follows the
loop below works unchanged on them.

## Query parameters

| Parameter | Type | Default | Notes |
| - | - | - | - |
| `limit` | integer | `50` | Max items per page, `1`–`200` on most lists. Out of range → 400. |
| `cursor` | string | — | Opaque token returned from the previous page. |

Both are optional. Omitting `cursor` returns the first page.

Two lists use smaller limits:

| List | `limit` range | Default |
| - | - | - |
| `GET .../suppliers/me/alerts` | `1`–`100` | `20` |
| `POST .../availability/suppliers` (`limit` and `cursor` go in the body) | `1`–`50` | `20` |

A page can hold fewer than `limit` items even when more remain. Never stop
on a short page — only `nextCursor: null` means the end.

## Response shape

```json theme={null}
{
  "data": [ /* up to `limit` items */ ],
  "nextCursor": "eyJwayI6IkJPT0tJTkcjcHJv..."
}
```

* `data` — the items on this page, in the endpoint's natural ordering.
* `nextCursor` — the token for the next page, or `null` if there are no
  more results.

## Iterating in code

```ts TypeScript theme={null}
async function* listAllBookings(projectId: string) {
  let cursor: string | undefined;
  do {
    const url = new URL(`/v1/projects/${projectId}/bookings`, process.env.MARKETBOX_API_URL);
    url.searchParams.set('limit', '200');
    if (cursor) url.searchParams.set('cursor', cursor);

    const res = await fetch(url, {
      headers: { 'x-api-key': process.env.MARKETBOX_API_KEY! },
    });
    const { data, nextCursor } = await res.json();
    for (const b of data) yield b;
    cursor = nextCursor ?? undefined;
  } while (cursor);
}
```

```bash bash theme={null}
cursor=""
while :; do
  resp=$(curl -s "$MARKETBOX_API_URL/v1/projects/$MARKETBOX_PROJECT_ID/bookings?limit=200${cursor:+&cursor=$cursor}" \
    -H "x-api-key: $MARKETBOX_API_KEY")
  echo "$resp" | jq '.data[]'
  cursor=$(echo "$resp" | jq -r '.nextCursor // empty')
  [ -z "$cursor" ] && break
done
```

## Rules

* **Opaque cursors.** A `cursor` is a base64-encoded blob with internal
  structure. Treat it as a magic token — never parse, decode, or
  construct one yourself. Its format may change without notice.
* **Cursors are tied to a filter set.** If you change the query params
  (`status`, `startDate`, etc.) between calls, the cursor's behavior is
  undefined. Either keep filters identical across the iteration, or
  start a fresh iteration with no cursor.
* **`nextCursor: null` means done.** Don't loop again when the response
  says there are no more pages.
* **No total counts.** The API does not return how many items remain.
  If you need a count, walk the full iteration.

## Errors

* `400 VALIDATION_ERROR` — `limit` is non-numeric, or outside the list's
  range. `message` names the field, for example `limit: …`.
* `400 BAD_REQUEST` with `message` `"Invalid cursor"` — `cursor` is
  malformed (not valid base64, not a cursor this API issued) or came from a
  different list. Start again without it.
* `400 INVALID_CURSOR` — the same failure on `GET .../suppliers/me/alerts`,
  which has its own code. See
  [Supplier portal: insights and alerts](https://docs.gomarketbox.com/guides/supplier-portal-insights-and-alerts.md#alerts).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.