> ## 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. # 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). ## OpenAPI ````yaml /en/openapi/v3-current/ledger.yaml get /v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/balances/history openapi: 3.1.0 info: title: Midaz Ledger API description: >- Complete API reference for Midaz Ledger services including organization management, ledger operations, assets, segments, portfolios, accounts, account types, transactions, operations, balances, operation routes, transaction routes, and metadata indexes. version: 3.7.1 servers: - url: https://ledger.sandbox.lerian.net security: [] tags: - name: Organizations API - name: Ledgers API - name: Assets API - name: Segments API - name: Portfolios API - name: Account Types API - name: Accounts API - name: Balances API - name: Transactions API - name: Operations API - name: Operation Routes API - name: Transaction Routes API - name: Metadata Indexes API paths: /v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/balances/history: get: tags: - Balances API summary: Retrieve Balance History by Account description: >- Use this endpoint to retrieve the state of all balances for a specific account at a given point in time (point-in-time query). parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/OrganizationId' - $ref: '#/components/parameters/LedgerId' - $ref: '#/components/parameters/AccountId' - name: date in: query description: >- The date and time to query the balance state. Format: yyyy-mm-dd hh:mm:ss (e.g., 2026-01-15 10:30:00). required: true example: '2026-01-15 10:30:00' schema: type: string pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$ - $ref: '#/components/parameters/ContentType' - $ref: '#/components/parameters/XRequestId' responses: '200': description: >- Indicates that the request was successful and the response contains all balance states at the specified point in time. content: application/json: schema: type: array items: $ref: '#/components/schemas/BalanceHistoryResponse' 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: {} '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0131: $ref: '#/components/examples/Error0131' Error0140: $ref: '#/components/examples/Error0140' Error0142: $ref: '#/components/examples/Error0142' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0041: $ref: '#/components/examples/Error0041' Error0042: $ref: '#/components/examples/Error0042' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0043: $ref: '#/components/examples/Error0043' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0141: $ref: '#/components/examples/Error0141' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0046: $ref: '#/components/examples/Error0046' security: - bearer: [] components: parameters: Authorization: name: Authorization in: header description: >- The authorization token. **This header is required if your environment has Access Manager enabled**. required: false schema: type: string OrganizationId: name: organization_id in: path description: The unique identifier of the Organization associated with the Ledger. required: true example: 019c96a0-0a98-7287-9a31-786e0809c769 schema: type: string LedgerId: name: ledger_id in: path description: The unique identifier of the associated Ledger. required: true example: 019c96a0-0ac0-7de9-9f53-9cf842a2ee5a schema: type: string AccountId: name: account_id in: path description: >- The unique identifier of the account of which you want to retrieve the balances. required: true example: 019c96a0-0c0c-7221-8cf3-13313fb60081 schema: type: string ContentType: name: Content-Type in: header description: >- The type of media of the resource. Recommended value is `application/json`. required: false example: application/json schema: type: string XRequestId: name: X-Request-Id in: header description: A unique identifier used to trace and track each request. required: false example: 019c96a0-0a98-7287-9a31-786e0809c769 schema: type: string format: uuid schemas: BalanceHistoryResponse: type: object description: >- The state of a balance at a specific point in time. Does not include allowSending and allowReceiving fields. properties: id: type: string format: uuid description: The unique identifier of the Balance. organizationId: type: string format: uuid description: The unique identifier of the Organization. ledgerId: type: string description: The unique identifier of the Ledger. format: uuid accountId: type: string description: The unique identifier of the Account. format: uuid alias: type: string description: The alias for the account (e.g., @conta_corrente). key: type: string description: >- The unique key for the balance in the context of the account (e.g., default, asset-freeze). assetCode: type: string description: The code of the asset (e.g., BRL, USD). available: type: string description: >- The available balance at the queried point in time. Represented as a decimal string with arbitrary precision (e.g., "1500.75"). onHold: type: string description: >- The on-hold (reserved) balance at the queried point in time. Represented as a decimal string with arbitrary precision (e.g., "250.00"). version: type: integer description: The balance version at the queried point in time. accountType: type: string description: The type of the account (e.g., deposit, creditCard). direction: type: string enum: - credit - debit description: >- The accounting direction of the balance at the queried point in time. overdraftUsed: type: string description: >- The amount of overdraft consumed at the queried point in time, as a decimal string. Always non-negative. settings: allOf: - $ref: '#/components/schemas/BalanceSettings' description: >- The per-balance configuration snapshot at the queried point in time. `null` for legacy balances without custom settings. position: type: object readOnly: true description: >- 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. properties: available: type: string readOnly: true description: >- Net spendable amount at the queried point in time. Equals `available` minus `overdraftUsed`. Negative when overdraft was active. onHold: type: string readOnly: true description: Mirrors `onHold` at the queried point in time. overdraftLimitAvailable: type: string readOnly: true description: >- Remaining overdraft headroom at the queried point in time. `"0"` when overdraft was disabled. Omitted entirely when overdraft was unlimited. createdAt: type: string format: date-time description: Timestamp of balance creation (UTC). updatedAt: type: string format: date-time description: Timestamp of last update at the queried point in time (UTC). ErrorFormat: type: object description: The response message error. required: - code - title - message properties: code: type: string description: A unique, stable identifier for the error. title: type: string description: A brief summary of the issue. message: type: string description: Detailed guidance for resolving the error. fields: type: object additionalProperties: true description: Additional information about the fields that caused the error. BalanceSettings: type: object description: >- Optional per-balance configuration controlling overdraft behavior and scope. properties: allowOverdraft: type: boolean description: >- When true, the balance may be debited beyond available funds. Defaults to false. overdraftLimitEnabled: type: boolean description: >- When true, an `overdraftLimit` must be supplied — the balance may overdraw up to that amount. When false with `allowOverdraft` true, the overdraft is unlimited. overdraftLimit: type: string description: >- Maximum overdraft amount as a decimal string (e.g., `"5000.00"`). Required when `overdraftLimitEnabled` is true and must be greater than zero. Omit when overdraft is unlimited. balanceScope: type: string enum: - transactional - internal description: >- System-managed scope. `transactional` is the default; `internal` marks system-managed companion balances (such as the overdraft companion) and blocks direct user operations on them. examples: Error0131: summary: Invalid Datetime Format value: code: '0131' title: Invalid Datetime Format message: >- The provided datetime format is invalid. Please use the format yyyy-mm-dd hh:mm:ss. Error0140: summary: Invalid Timestamp value: code: '0140' title: Invalid Timestamp message: >- The provided timestamp is invalid. Please ensure the date and time values are correct. Error0142: summary: Missing Required Query Parameter value: code: '0142' title: Missing Required Query Parameter message: >- A required query parameter is missing from the request. Please include all required parameters and try again. Error0041: summary: Token Missing value: code: '0041' title: Token Missing message: >- A valid token must be provided in the request header. Please include a token and try again. Error0042: summary: Invalid Token value: code: '0042' title: Invalid Token message: >- The provided token is expired, invalid or malformed. Please provide a valid token and try again. Error0043: summary: Insufficient Privileges value: code: '0043' title: Insufficient Privileges message: >- You do not have the necessary permissions to perform this action. Please contact your administrator if you believe this is an error. Error0141: summary: No Balance Data at Timestamp value: code: '0141' title: No Balance Data at Timestamp message: >- No balance data exists for the specified point in time. The balance may not have existed at that date, or no operations had been recorded yet. Error0046: summary: Internal Server Error value: code: '0046' title: Internal Server Error message: >- The server encountered an unexpected error. Please try again later or contact support. securitySchemes: bearer: type: http scheme: bearer ````