---
title: "Get an account"
method: GET
path: "/v3/{ledgerName}/accounts/{address}"
tags: ["Accounts"]
---

# Get an account

`GET /v3/{ledgerName}/accounts/{address}`

## Request

- Base URL: `http://localhost:9000`
- URL: `http://localhost:9000/v3/{ledgerName}/accounts/{address}`
- Auth: one of:
  - HTTP bearer
  - none

Retrieves account information including metadata for a specific account address. Requires `ledger:read` scope.

## Path parameters

- `ledgerName` string, required
- `address` string, required

## Query parameters

- `collapseColors` boolean

## Headers

- `X-Consistency` 'linearizable' | 'stale'
- `Formance-Bigint-As-String` string

## Response `200`

Account retrieved successfully

- GetAccountResponse
  - `data` Account, required
    - `address` string, required: Account address
    - `metadata` object: Account metadata (typed values)
    - `volumes` AccountVolume[]: Account volumes listed per (asset, color). Sorted by (asset, color) ascending for stable serialization. The empty color is the uncolored bucket; colored buckets are strictly isolated. Use the `collapseColors=true` query parameter on GET /accounts to sum every colored bucket of the same asset into a single uncolored entry.
      - `asset` string, required: Asset identifier (e.g. "USD/2")
      - `color` string, required: Color of the bucket. Empty string is the uncolored bucket.
      - `volumes` VolumesWithBalance, required
        - `input` union, required: Arbitrary-precision unsigned BigUint value encoded as a JSON number by default, or a canonical decimal string when Formance-Bigint-As-String is enabled. The same rule applies to every response BigUint value, including nested fields, regardless of business meaning. JavaScript consumers should enable the header to avoid number rounding.
          - integer
          - string
        - `output` union, required: Arbitrary-precision unsigned BigUint value encoded as a JSON number by default, or a canonical decimal string when Formance-Bigint-As-String is enabled. The same rule applies to every response BigUint value, including nested fields, regardless of business meaning. JavaScript consumers should enable the header to avoid number rounding.
          - integer
          - string
        - `balance` union, required: Arbitrary-precision SignedBigInt value encoded as a JSON number by default, or a canonical decimal string when Formance-Bigint-As-String is enabled. The same rule applies to every response SignedBigInt value, including nested fields, regardless of business meaning.
          - integer
          - string

## Other responses

- `400`: Bad request
- `401`: Authentication required (missing or invalid JWT token)
- `403`: Insufficient permissions (missing required scope)
- `404`: Not found
- `405`: Method not allowed
- `500`: Internal server error
- `503`: Service unavailable — the server cannot serve the request right now but an immediate retry can succeed. The `errorCode` field discriminates the cause: `NO_LEADER` (no elected Raft leader), `CACHE_HORIZON_EXCEEDED` (admission snapshot too old, retry against a fresh one), `UNAVAILABLE` (an internal forwarded stream was torn down mid-transfer), or the reason of any domain error of the unavailable kind (e.g. `INDEX_BUILDING`).

## Changes

- **2026-11-03** `f5e817eca038`: 1 info
  - api operation id `getAccount` removed and replaced with `v3GetAccount`
- **2026-10-09** `0ed18e459f51`: 3 breaking, 4 info
  - response property `data/volumes/items/volumes/balance` list-of-types was widened by adding types `integer` to media type `application/json` of response `200`
  - response property `data/volumes/items/volumes/input` list-of-types was widened by adding types `integer` to media type `application/json` of response `200`
  - response property `data/volumes/items/volumes/output` list-of-types was widened by adding types `integer` to media type `application/json` of response `200`
  - added the new optional `header` request parameter `Formance-Bigint-As-String`
  - …3 more
- **2026-10-08** `3da23d327316`: 2 info
  - added the media type `text/plain` for the response with the status `401`
  - added the media type `text/plain` for the response with the status `403`
- **2026-10-08** `b3ee1959d86a`: 1 info
  - added the new optional `header` request parameter `X-Consistency`
- **2026-10-07** `8de1b9405d3e`: 3 info
  - the `data/volumes/items/volumes/balance` response's property pattern `^(0|-?[1-9][0-9]*)$` was added for the status `200`
  - the `data/volumes/items/volumes/input` response's property pattern `^(0|[1-9][0-9]*)$` was added for the status `200`
  - the `data/volumes/items/volumes/output` response's property pattern `^(0|[1-9][0-9]*)$` was added for the status `200`

[Operation history](https://skmtc.dev/formancehq/apis/ledger-api/changes/v3/:ledgerName/accounts/:address/get.md)

---

[API](https://skmtc.dev/formancehq/apis/ledger-api.md) - [All operations](https://skmtc.dev/formancehq/apis/ledger-api/llms.txt) - [OpenAPI document](https://skmtc.dev/formancehq/apis/ledger-api/revisions/f5e817eca038?raw)