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

# Pagination

> Page-based and cursor-based pagination on Midaz list endpoints: query parameters, response payloads, and the page-size limit.

Midaz list endpoints deliver data in smaller, manageable portions. This improves response times and client-side processing, particularly for applications that load results incrementally. Other Lerian APIs set their own pagination parameters, defaults, and limits. Check each API's reference.

## Page-based pagination

***

Instead of returning the entire dataset in a single response, which can strain resources, clients can request specific subsets of data.

Page-based endpoints accept two query parameters:

* `page` (integer): Specifies the page number to retrieve. The default value is `1`.
  * Values below `1` return an error.
* `limit` (integer): Defines the maximum number of items per page. The default value is `10`.

For example, to retrieve the first page of organizations with a maximum of 10 items per page:

<CodeGroup>
  ```http HTTP theme={null}
  GET /v1/organizations?page=1&limit=10
  ```
</CodeGroup>

### Pagination response

The pagination response includes the following structure:

* `items`: An array of entities retrieved for the current page. Each object contains detailed information about the resource requested, as shown in the example below.
* `page`: The current page number, starting from `1` (default).
* `limit`: The maximum number of items included in the response, as defined in the request or default configuration.

Below is an example response for a paginated request:

<CodeGroup>
  ```json JSON expandable theme={null}
  {
      "items": [
          {
              "id": "0193696f-8eff-7926-a77a-0b424cf7156b",
              "parentOrganizationId": null,
              "legalName": "Collins Inc",
              "doingBusinessAs": "The ledger.io",
              "legalDocument": "78425230000190",
              "address": {
                  "line1": "Avenida Paulista, 1234",
                  "line2": "CJ 203",
                  "zipCode": "01310916",
                  "city": "New Lyla",
                  "state": "CH",
                  "country": "FO"
              },
              "status": {
                  "code": "ACTIVE",
                  "description": "Ledger Test"
              },
              "createdAt": "2024-11-26T17:05:39.071587Z",
              "updatedAt": "2024-11-26T17:05:39.071587Z",
              "deletedAt": null,
              "metadata": {
                  "bitcoinn": "3QH2XV7JxMRKXDqh87JG7LWuf7AeGfy",
                  "boolean": true,
                  "chave": "metadata_chave",
                  "double": 10.5,
                  "int": 1
              }
          }
      ],
      "page": 1,
      "limit": 1
  }
  ```
</CodeGroup>

### Maximum page size

By default, Midaz accepts a maximum of **100 items per page** (`limit=100`). This restriction avoids excessive payload sizes.

If your use case requires retrieving a larger number of items per request, you can override this limit by setting the `MAX_PAGINATION_LIMIT` environment variable in your deployment configuration ( `.env` file). Billing package lists keep the 100 maximum.

<Warning>
  Increasing the pagination limit may result in slower response times depending on the volume of data and infrastructure conditions. Be sure to test thoroughly in staging environments before applying the change in production.
</Warning>

After you change it, restart the Ledger. To set it on a Midaz deployment, see the [Midaz chart README](https://github.com/LerianStudio/helm/tree/main/charts/midaz).

## Cursor-based pagination

***

Some endpoints use cursor-based pagination instead of page numbers. This approach is more efficient for large or frequently changing datasets.

Cursor-based endpoints accept the following query parameters:

* `cursor` (string): An encoded token from a previous response (`next_cursor` or `prev_cursor`) to navigate forward or backward. Omit this parameter to start from the beginning.
* `limit` (integer): The maximum number of items per page.
* `sort_order` (string): The direction used to sort results. Accepted values: `asc` (ascending) or `desc` (descending).

<Note>
  Set `sort_order` on the initial request and keep it unchanged while you follow the cursors.
</Note>

For example, to retrieve balances using cursor pagination:

<CodeGroup>
  ```http HTTP theme={null}
  GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/balances?limit=10
  ```
</CodeGroup>

### Cursor pagination response

The response includes the following structure:

* `items`: An array of entities for the current page.
* `next_cursor`: An encoded token to retrieve the next page. If absent or empty, there are no more results.
* `prev_cursor`: An encoded token to retrieve the previous page. If absent or empty, you are on the first page.
* `limit`: The maximum number of items included in the response.

To navigate to the next page, pass the `next_cursor` value as the `cursor` query parameter:

<CodeGroup>
  ```http HTTP theme={null}
  GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/balances?cursor=eyJpZCI6IjAxOTNiN...&limit=10
  ```
</CodeGroup>

Below is an example response for a cursor-paginated request:

<CodeGroup>
  ```json JSON theme={null}
  {
      "items": [
          {
              "id": "019c96a0-0c0d-7915-84b9-e497bfee9916",
              "organizationId": "019c96a0-0a98-7287-9a31-786e0809c769",
              "ledgerId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
              "accountId": "019c96a0-0c0c-7221-8cf3-13313fb60081",
              "alias": "customer-brl-1",
              "key": "default",
              "assetCode": "BRL",
              "available": "1000",
              "onHold": "0"
          }
      ],
      "next_cursor": "eyJpZCI6IjAxOTNiNTZmLWJhY2YtNzQ0MS05NDU4LTEyZTE5MjVlOGI4NCIsInBvaW50c19uZXh0Ijp0cnVlfQ==",
      "prev_cursor": "eyJpZCI6IjAxOTNiNTZmLWJhY2YtNzQ0MS05NDU4LTEyZTE5MjVlOGI4NCIsInBvaW50c19uZXh0IjpmYWxzZX0=",
      "limit": 10
  }
  ```
</CodeGroup>

### Which endpoints use cursor pagination?

Each endpoint's API reference shows whether it takes `page` or `cursor`.


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