Skip to main content

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.

Efficiently managing large datasets is crucial for maintaining API performance and scalability. Our APIs employ a robust pagination mechanism to deliver data in smaller, manageable portions. This improves response times and client-side processing, particularly for applications that load results incrementally.

​
Pagination in our APIs

Instead of returning the entire dataset in a single response, which can strain resources, clients can request specific subsets of data. This improves response times and enables smoother data handling, particularly for applications that load results incrementally. We support two query parameters for pagination:
  • page (integer): Specifies the page number to retrieve. The default value is 1.
    • Negative values are invalid and will result in 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: 
GET /v1/organizations?page=1&limit=10

​
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: 
{
    "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
}

​
Maximum page size

By default, API endpoints that support pagination accept a maximum of 100 items per page (limit=100). This restriction helps ensure optimal performance and 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).
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.
To update this configuration in Kubernetes: 
kubectl edit configmap midaz-transaction -n midaz

# Set the new value for MAX_PAGINATION_LIMIT

kubectl rollout restart deployments midaz-transaction -n midaz
Midaz and all its plugin services inherit this behavior.

​
Cursor-based pagination

Some endpoints use cursor-based pagination instead of page numbers. This approach is more efficient for large or frequently changing datasets and guarantees consistent results even when data is modified between requests. 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. The default value is 10.
  • sort_order (string): The direction used to sort results. Accepted values: asc (ascending, default) or desc (descending).
When paginating with a cursor from a previous response, you cannot change sort_order mid-pagination. Sorting parameters must be set on the initial request and remain consistent throughout the pagination sequence.
For example, to retrieve balances using cursor pagination: 
GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/balances?limit=10

​
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: 
GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/balances?cursor=eyJpZCI6IjAxOTNiN...&limit=10
Below is an example response for a cursor-paginated request: 
{
    "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
}

​
Which endpoints use cursor pagination?

The following endpoints use cursor-based pagination:
  • List Transactions — GET /v1/organizations/{id}/ledgers/{id}/transactions
  • List Balances — GET /v1/organizations/{id}/ledgers/{id}/balances
  • List Operations by Account — GET /v1/organizations/{id}/ledgers/{id}/accounts/{id}/operations
  • List Account Types — GET /v1/organizations/{id}/ledgers/{id}/account-types
  • List Operation Routes — GET /v1/organizations/{id}/ledgers/{id}/operation-routes
  • List Transaction Routes — GET /v1/organizations/{id}/ledgers/{id}/transaction-routes
All other list endpoints use the standard page-based pagination described above.