# Pagination

Efficiently retrieving large sets of data from the API requires pagination. Our API uses HTTP headers to provide pagination information, supporting up to 50 items per page.

## How Pagination Works

When a response contains a list of results, pagination details are included in the response headers. This allows clients to navigate through large datasets efficiently without overloading the response body.

## Pagination Parameters

- **Maximum items per page:** 50.
- **Page size:** Controlled by the `limit` query parameter (see endpoint documentation for defaults and limits).
- **Page navigation:** Use the URLs provided in the `Link` header to move between pages.

## Pagination Headers

The following headers are included in paginated responses:

- `X-Pagination-Count`: Total number of available pages.
- `X-Pagination-Page`: The current page number.
- `X-Pagination-Limit`: The maximum number of items per page.
- `X-Result-Count`: The total number of results across all pages.
- `Link`: Contains navigation URLs for `next`, `prev`, `first`, and `last` pages, following the [RFC 5988](https://datatracker.ietf.org/doc/html/rfc5988) standard.

Example headers:

```
X-Pagination-Count: 12
X-Pagination-Page: 2
X-Pagination-Limit: 50
X-Result-Count: 600
Link: <https://merchant-zfds.api.myfinqu.com/3.0/orders?page=3>; rel="next", <https://merchant-zfds.api.myfinqu.com/3.0/orders?page=12>; rel="last", <https://merchant-zfds.api.myfinqu.com/3.0/orders?page=1>; rel="first", <https://merchant-zfds.api.myfinqu.com/3.0/orders?page=1>; rel="prev"
```

## Cursor-Based Pagination

Currently, the API uses page-based pagination. Cursor-based pagination is not supported.

## Page-Based Pagination

To request a specific page, use the `page` query parameter:

```
GET /orders?page=2&limit=50
```

Use the URLs in the `Link` header to navigate between pages.

## Best Practices

- Always check the `Link` header for navigation URLs.
- Do not assume the number of pages; use the `X-Pagination-Count` header.
- Limit the number of items per page to avoid large responses (maximum is 50).
- Stop paginating when there is no `next` link in the `Link` header.