Skip to main content
GET
/
v1
/
organizations
/
{organization_id}
/
ledgers
/
{ledger_id}
/
balances
/
{balance_id}
/
history
Retrieve Balance History
curl --request GET \
  --url https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/balances/{balance_id}/history
import requests

url = "https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/balances/{balance_id}/history"

response = requests.get(url)

print(response.text)
const options = {method: 'GET'};

fetch('https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/balances/{balance_id}/history', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/balances/{balance_id}/history",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/balances/{balance_id}/history"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/balances/{balance_id}/history")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://ledger.sandbox.lerian.net/v1/organizations/{organization_id}/ledgers/{ledger_id}/balances/{balance_id}/history")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
{
  "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"
}

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.

​
balance_id
string<uuid>
required

The unique identifier of the balance that you want to retrieve.

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

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

The state of a balance at a specific point in time. Does not include allowSending and allowReceiving fields.

​
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.

​
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.

​
createdAt
string<date-time>

Timestamp of balance creation (UTC).

​
updatedAt
string<date-time>

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