Retrieve Balance History by Account

Use this endpoint to retrieve the state of all balances for a specific account at a given point in time (point-in-time query).

GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/balances/history

Retrieve Balance History by Account

cURL

curl --request GET \
  --url https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/balances/history

200

Example

[
  {
    "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": "@conta_corrente",
    "key": "default",
    "assetCode": "BRL",
    "available": "150000",
    "onHold": "25000",
    "version": 42,
    "accountType": "deposit",
    "direction": "credit",
    "overdraftUsed": "0",
    "settings": null,
    "position": {
      "available": "150000",
      "onHold": "25000",
      "overdraftLimitAvailable": "0"
    },
    "createdAt": "2025-06-01T10:00:00Z",
    "updatedAt": "2026-01-15T10:30:00Z"
  },
  {
    "id": "019c96a0-1234-5678-9abc-def012345678",
    "organizationId": "019c96a0-0a98-7287-9a31-786e0809c769",
    "ledgerId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
    "accountId": "019c96a0-0c0c-7221-8cf3-13313fb60081",
    "alias": "@conta_corrente",
    "key": "asset-freeze",
    "assetCode": "USD",
    "available": "50000",
    "onHold": "0",
    "version": 12,
    "accountType": "deposit",
    "direction": "credit",
    "overdraftUsed": "0",
    "settings": null,
    "position": {
      "available": "50000",
      "onHold": "0",
      "overdraftLimitAvailable": "0"
    },
    "createdAt": "2025-08-10T14:00:00Z",
    "updatedAt": "2026-01-15T10:30:00Z"
  }
]

Headers

Content-Type · string

The type of media of the resource. Recommended value is application/json.

X-Request-Id · string<uuid>

A unique identifier used to trace and track each request.

Authorization · string

Bearer JWT token for authentication. Required when PLUGIN_AUTH_ENABLED=true (enforced in multi-tenant deployments). Optional in default OSS single-tenant mode. Format: Bearer <token>

Path Parameters

organization_id · string<uuid> · required

The unique identifier of the Organization associated with the Ledger.

ledger_id · string<uuid> · required

The unique identifier of the associated Ledger.

account_id · string<uuid> · required

The unique identifier of the account.

Query Parameters

date · string · required

The date and time to query the balance state. Format: yyyy-mm-dd hh:mm:ss (e.g., 2026-01-15 10:30:00).

Pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$

Response

200

application/json

Indicates that the request was successful and the response contains all balance states at the specified point in time.

id · string<uuid>

The unique identifier of the Balance.

organizationId · string<uuid>

The unique identifier of the Organization.

ledgerId · string<uuid>

The unique identifier of the Ledger.

accountId · string<uuid>

The unique identifier of the Account.

alias · string

The alias for the account (e.g., @conta_corrente).

key · string

The unique key for the balance in the context of the account (e.g., default, asset-freeze).

assetCode · string

The code of the asset (e.g., BRL, USD).

available · string

The available balance at the queried point in time. Represented as a decimal string with arbitrary precision (e.g., "1500.75").

onHold · string

The on-hold (reserved) balance at the queried point in time. Represented as a decimal string with arbitrary precision (e.g., "250.00").

version · integer

The balance version at the queried point in time.

accountType · string

The type of the account (e.g., deposit, creditCard).

direction · enum<string>

The accounting direction of the balance at the queried point in time.

Available options: credit, debit

overdraftUsed · string

The amount of overdraft consumed at the queried point in time, as a decimal string. Always non-negative.

settings · object

The per-balance configuration snapshot at the queried point in time. null for legacy balances without custom settings.

Show child attributes

position · object · read-only

Computed view of the balance state at the queried point in time. Always present; never persisted. Mirrors the live balance position shape so historical responses carry the same wire surface as live reads.

Show child attributes

createdAt · string<date-time>

Timestamp of balance creation (UTC).

updatedAt · string<date-time>

Timestamp of last update at the queried point in time (UTC).