---
title: "Aggregate volumes"
method: GET
path: "/v3/{ledgerName}/volumes"
tags: ["Volumes"]
---

# Aggregate volumes

`GET /v3/{ledgerName}/volumes`

## Request

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

Returns aggregated volumes (input/output/balance per asset) across all accounts in the ledger.
Supports filtering accounts with the generic `filter` parameter, grouping by account prefixes,
and max-precision merging.
Requires `ledger:ReadAccount` scope.

## Path parameters

- `ledgerName` string, required

## Query parameters

- `filter` string
- `useMaxPrecision` boolean
- `groupByPrefixes` string
- `collapseColors` boolean

## Headers

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

## Response `200`

Aggregated volumes retrieved successfully

- AggregateVolumesResponse
  - `data` AggregateVolumesData, required
    - `volumes` AggregatedVolume[], required: Flat aggregated volumes per asset
      - `asset` string, required: Asset identifier (e.g. "USD/2")
      - `color` string, required: Color of the aggregated bucket. By default the response contains one AggregatedVolume per (asset, color) tuple. With `collapseColors=true`, every colored bucket of the same (asset, precision) is summed and the resulting entry carries color = "".
      - `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
    - `groups` GroupedAggregateResult[]: Per-prefix aggregated volumes (present when groupByPrefixes is set)
      - `prefix` string, required: Account prefix this group matches
      - `volumes` AggregatedVolume[], required: Aggregated volumes for accounts matching this prefix
        - `asset` string, required: Asset identifier (e.g. "USD/2")
        - `color` string, required: Color of the aggregated bucket. By default the response contains one AggregatedVolume per (asset, color) tuple. With `collapseColors=true`, every colored bucket of the same (asset, precision) is summed and the resulting entry carries color = "".
        - `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 `aggregateVolumes` removed and replaced with `v3AggregateVolumes`
- **2026-10-09** `0ed18e459f51`: 6 breaking, 7 info
  - response property `data/groups/items/volumes/items/balance` list-of-types was widened by adding types `integer` to media type `application/json` of response `200`
  - response property `data/groups/items/volumes/items/input` list-of-types was widened by adding types `integer` to media type `application/json` of response `200`
  - response property `data/groups/items/volumes/items/output` list-of-types was widened by adding types `integer` to media type `application/json` of response `200`
  - response property `data/volumes/items/balance` list-of-types was widened by adding types `integer` to media type `application/json` of response `200`
  - …9 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`
- …earlier changes not shown

[Operation history](https://skmtc.dev/formancehq/apis/ledger-api/changes/v3/:ledgerName/volumes/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)