# Pagination

Canonical URL: https://api-docs.test-printeers.com/guides/pagination

Learn how to paginate through large result sets using cursors.

## Overview

Endpoints that return lists of resources use cursor-based pagination. Instead of page numbers, you receive an opaque cursor string that points to your position in the result set.

## How It Works

When a response contains more results, it includes a `nextCursor` field. The list itself is wrapped under a key named after the resource (`orders`, `claims`, `images`, ...):

```json
{
  "orders": [...],
  "nextCursor": "c1AAYa6zbXmgBhFNVccOVcnA"
}
```

To fetch the next page, pass this cursor as a query parameter:

```
GET /v2/orders?cursor=c1AAYa6zbXmgBhFNVccOVcnA
```

When there are no more results, `nextCursor` is `null`:

```json
{
  "orders": [...],
  "nextCursor": null
}
```

## Page Size

Each paginated endpoint specifies its own page size. Some endpoints use a fixed size, others accept a user-specified limit. See the documentation for each endpoint.

## When nextCursor Is Present

The response includes `nextCursor` whenever the number of returned items equals the page size. This means there may be more results.

When the number of items is less than the page size, `nextCursor` is `null` and you've reached the end.

Note that the final page may be empty. This happens when the total number of items is exactly a multiple of the page size. An empty page with `nextCursor: null` is a normal end-of-results signal.

## Cursor Rules

Cursors are opaque strings. Your integration should:

- **Treat cursors as arbitrary strings**: Do not parse, decode, or interpret the cursor value. The format may change without notice.
- **Do not store cursors**: Fetch all pages in a single session. Do not persist cursors for later use.
- **Do not reuse previous cursors**: Once you've moved to the next page, discard earlier cursors. To re-fetch a list, start from the beginning without a cursor.
- **Never construct cursors**: Only use cursor values returned by the API.

## Example: Fetching All Orders

```python
def fetch_all_orders():
    orders = []
    cursor = None

    while True:
        url = "/v2/orders"
        if cursor:
            url += f"?cursor={cursor}"

        response = api_request(url)
        orders.extend(response["orders"])

        cursor = response.get("nextCursor")
        if cursor is None:
            break

    return orders
```

## Empty Results

A response with zero items is normal in two cases:

- **No matches**: Your query filters excluded all resources.
- **Final page**: The total count was a multiple of the page size (see above).

## Ordering

Paginated endpoints return results in a fixed order (typically newest first by creation date). The ordering is not configurable.

## Where this is used

Cursor pagination applies to: `GET /orders`, `GET /claims`, `GET /products`, `GET /images`, and `GET /items`. See each endpoint in the [API Reference](https://api-docs.test-printeers.com/reference/v2) for endpoint-specific filters and the default sort field.