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

# Pagination

> Consistent page-based pagination used across all list endpoints.

## Overview

List endpoints use **page-based pagination** with two query parameters:

* `limit` — number of items per page (default **50**, min **1**, max **100**)
* `page` — 1-based page index (default **1**)

Results are wrapped in a standard envelope with a `data.items[]` array and a `data.meta` object that reports the pagination state.

## Request

Pass `limit` and `page` as query parameters on any list endpoint (e.g., chains, loans, withdrawals, corridors, utilizations).

```http theme={null}
GET /api/v2/liquidity/management/loans?limit=50&page=2
authorization: Bearer <token>
x-api-key: <key>
```

### Common query parameters

| Name  | In    | Type    | Default | Min | Max | Notes               |
| ----- | ----- | ------- | ------- | --- | --- | ------------------- |
| limit | query | integer | 50      | 1   | 100 | Items per page      |
| page  | query | integer | 1       | 1   | —   | 1-based page number |

> Some endpoints also accept additional filters (e.g., `status`, `chainId`, `loan_id`, `corridor_id`). Filters combine with pagination.

## Response Shape

All list responses follow the same structure:

```json theme={null}
{
  "items": [ /* array of resources */ ],
  "meta": {
    "limit": 50,
    "page": 2,
    "total": 1234
  }
}
```

### `meta` fields

* `limit` — the page size used for this response.
* `page` — the **current** 1-based page number.
* `total` — **total number of items** that match the query (across all pages).

You can compute **total pages** as:\
`totalPages = ceil(total / limit)`.

## Example

```http theme={null}
GET /api/v2/liquidity/corridors?status=ACTIVE&limit=25&page=3
```

```json theme={null}
{
  "items": [
    {
      "id": "corridor_ngn",
      "name": "Nigeria",
      "currency": "NGN",
      "status": "ACTIVE",
      "min_amount": 1000,
      "max_amount": 1000000,
      "created_at": "2025-08-02",
      "updated_at": "2025-08-02"
    }
    // ...
  ],
  "meta": {
    "limit": 25,
    "page": 3,
    "total": 240
  }
}
```

## Best Practices

* **Use stable sorting**: if the endpoint supports sorting, keep it consistent between requests to avoid duplicates or gaps when data changes.
* **Paginate deterministically**: when filtering by mutable fields (like `status`), expect `total` and page counts to change over time.
* **Handle bounds**: if `page` is beyond the last page (`page > ceil(total/limit)`), you may receive an empty `items` array.
* **Validate inputs**: invalid `limit`/`page` values return a validation error (`400` or `422`) with a structured error body.
* **Backoff & retry**: if you hit rate limits (`429`), retry with exponential backoff before continuing pagination.