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

# Pagination

Paginated endpoints in the Sendcloud v3 API use **cursor-based pagination** with HTTP `Link` headers.

Unlike offset-based pagination, cursor-based pagination provides stable results even when data changes between requests.

## How it works

Pagination links (`next`, `prev`) are returned in the HTTP **`Link` response header**, not in the JSON response body. The response body only contains a `data` array.

### Query parameters

| Parameter   | Type    | Required | Description                                                                |
| ----------- | ------- | -------- | -------------------------------------------------------------------------- |
| `cursor`    | string  | No       | The pagination cursor value from a previous response's `Link` header.      |
| `page_size` | integer | No       | Number of results per page. Clamped between 0 and the endpoint's max size. |

### Link header format

When there are more pages available, the response includes a `Link` header with `next` and/or `prev` URLs:

```
Link: <https://panel.sendcloud.sc/v3/shipments?cursor=cD0xMjM=>; rel="next", <https://panel.sendcloud.sc/v3/shipments?cursor=cj0xJnA9NDU2>; rel="prev"
```

<Warning>
  The `cursor` values are **base64-encoded and opaque**. Do not parse or construct them manually — pass them back as-is
  from the `Link` header.
</Warning>

### Example response

**Response headers:**

```
HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://panel.sendcloud.sc/v3/shipments?cursor=cD0xMjM=>; rel="next"
```

**Response body:**

```json theme={null}
{
  "data": [
    { "id": 1, "...": "..." },
    { "id": 2, "...": "..." }
  ]
}
```

## Iterating through all pages

To retrieve all results, follow the `next` link from each response until no `next` link is returned:

1. Make an initial request to the list endpoint (optionally with `page_size`).
2. Parse the `Link` header from the response.
3. If a `rel="next"` URL is present, make a request to that URL.
4. Repeat until no `next` link is returned.