> ## 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 Balances by Account > Use this endpoint to retrieve all balances from a specific account. ## OpenAPI ````yaml /en/openapi/v3-current/ledger.yaml get /v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/balances 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: get: tags: - Balances API summary: Retrieve Balances by Account description: Use this endpoint to retrieve all balances from a specific account. parameters: - $ref: '#/components/parameters/OrganizationId' - $ref: '#/components/parameters/LedgerId' - $ref: '#/components/parameters/ContentType' - $ref: '#/components/parameters/XRequestId' - $ref: '#/components/parameters/AccountId' responses: '200': description: >- Indicates that the request was successful and the response contains the expected data. content: application/json: schema: $ref: '#/components/schemas/GetBalanceResponse' 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: customer-brl-1 key: default assetCode: BRL available: '1000' onHold: '0' version: 1 accountType: deposit allowSending: true allowReceiving: true direction: credit overdraftUsed: '0' settings: allowOverdraft: true overdraftLimitEnabled: true overdraftLimit: '5000.00' balanceScope: transactional position: available: '1000' onHold: '0' overdraftLimitAvailable: '5000.00' createdAt: '2026-02-25T21:06:37.197596Z' updatedAt: '2026-02-25T21:06:38.420934Z' deletedAt: null '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0065: $ref: '#/components/examples/Error0065' headers: {} '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: Error0007: $ref: '#/components/examples/Error0007' headers: {} '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0046: $ref: '#/components/examples/Error0046' security: - bearer: [] components: parameters: 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 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 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 schemas: GetBalanceResponse: type: object properties: id: type: string 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 used in the operation. key: type: string description: The unique identifier for the balance in the context of the account. assetCode: type: string description: The name of the asset used in the operation. available: type: string description: Previous available balance. onHold: type: string description: Amount on hold/reserved. version: type: integer description: Balance version, which is updated with each transaction. accountType: type: string description: The type of account. allowSending: type: boolean description: >- If true, indicates that the balance can be used to send transactions. allowReceiving: type: boolean description: >- If true, indicates that the balance can be used to receive transactions. direction: type: string enum: - credit - debit description: >- The accounting direction of the balance. `credit` balances grow on credit and shrink on debit (asset-like); `debit` balances grow on debit and shrink on credit (liability-like). Set at creation and immutable. overdraftUsed: type: string description: >- The amount of overdraft currently consumed by this balance, as a decimal string. Always non-negative; `"0"` when the balance has no overdraft active. settings: allOf: - $ref: '#/components/schemas/BalanceSettings' description: >- Optional per-balance configuration (overdraft, scope). `null` for legacy balances without custom settings. position: type: object readOnly: true description: >- Computed view of the balance state at response time. Always present; never persisted. Re-derived from `available`, `onHold`, `overdraftUsed`, and `settings` on every read. properties: available: type: string readOnly: true description: >- Net spendable amount as a decimal string. Equals `balance.available` minus `overdraftUsed`. Negative when overdraft is active. onHold: type: string readOnly: true description: Mirrors `balance.onHold`. Funds reserved by pending operations. overdraftLimitAvailable: type: string readOnly: true description: >- Remaining overdraft headroom as a decimal string. `"0"` when overdraft is disabled. Omitted entirely when overdraft is unlimited (`allowOverdraft: true` and `overdraftLimitEnabled: false`). Otherwise equals `overdraftLimit` minus `overdraftUsed`. createdAt: type: string format: date-time description: Timestamp of creation (UTC). updatedAt: type: string format: date-time description: Timestamp of last update (UTC). deletedAt: type: - string - 'null' format: date-time description: Timestamp of soft deletion, if applicable (UTC). metadata: $ref: '#/components/schemas/Metadata' 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. Metadata: type: object additionalProperties: type: string description: >- An object containing key-value pairs to add as metadata, where the field `name` is the key and the field `value` is the value. For example, to add a Cost Center, use 'costCenter': 'BR_11101997'. examples: Error0065: value: code: '0065' title: Invalid Path Parameter message: >- The provided path parameter {{parameter_name}} is not in the expected format. Please ensure the parameter adheres to the required format and try again. summary: Invalid Path Parameter 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. Error0007: value: code: '0007' title: Entity Not Found message: >- No entity was found for the given ID. Please make sure to use the correct ID for the entity you are trying to manage. summary: Entity Not Found 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 ````