GET
/accounts/{accountId}/balance-history Get account balance history
One layer's balance through a window of days in the ledger's timezone: brought forward from every posting effective before start_date, then each posting effective by the end of end_date with the balance after it. Only posted and reversed transactions count. The balance after a day's last posting is the balance GET /api/v1/accounts/{accountId}/balance reports as of that day.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
accountIdrequired | path | string uuid | Account UUID |
start_date | query | string date | First day of the window (Y-m-d, ledger timezone). Defaults to one month before end_date. |
end_date | query | string date | Last day of the window (Y-m-d, ledger timezone), included whole. Defaults to today in the ledger's timezone. |
layer | query | string enum: settled | pending | encumbrance · default: "settled" | The balance layer (case-insensitive) |
Responses
200Balance history retrieved successfully
{
"success": true,
"data": {
"account": {
"id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
"code": "string",
"name": "string"
},
"period": {
"start": "2026-01-15",
"end": "2026-01-15"
},
"layer": "settled",
"opening_balance": "107.00",
"history": [
{
"date": "2026-01-15",
"description": null,
"debit": "0",
"credit": "5.00",
"balance": "112.00"
}
],
"ending_balance": "132.00"
}
} 401Unauthenticated
{
"success": false,
"message": "Validation failed",
"code": "VALIDATION_ERROR"
} 403Forbidden
{
"success": false,
"message": "Validation failed",
"code": "VALIDATION_ERROR"
} 404Account not found
{
"success": false,
"message": "Validation failed",
"code": "VALIDATION_ERROR"
} 422Unknown layer, a malformed date, a start_date after end_date, a window of more than 366 days, or more postings than the configured cap (10000 by default)
{
"success": false,
"message": "Validation failed",
"code": "VALIDATION_ERROR"
} Examples
curl https://ledga.io/api/v1/accounts/{accountId}/balance-history \
-H "Authorization: Bearer sk_xxxxxxxx_your_secret" use Ledga\Api\LedgaClient;
$ledga = new LedgaClient('sk_xxxxxxxx_your_secret');
$history = $ledga->accounts->getBalanceHistory('01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a', [
'start_date' => '2026-01-01',
'end_date' => '2026-01-31',
]);