---
title: "Get ledger statistics"
method: GET
path: "/v3/{ledgerName}/stats"
tags: ["Ledgers"]
---

# Get ledger statistics

`GET /v3/{ledgerName}/stats`

## Request

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

Returns aggregate usage statistics (transaction, volume, reference, posting, log, revert and Numscript-execution counts, plus ephemeral-evicted and transient-used volume tallies) for a ledger. Requires `ledger:read` scope. On live reads, `transactionCount` and `logCount` are FSM-backed. The seven usage-derived counters (`postingCount`, `revertCount`, `numscriptExecutionCount`, `referenceCount`, `ephemeralEvictedCount`, `transientUsedCount`, `volumeCount`) are materialised asynchronously in the serving replica's usagestore and may lag committed state even after the request's ReadIndex barrier. Note: for checkpoint-scoped (historical) reads, only `transactionCount` and `logCount` are checkpoint-consistent; the usage-derived counters (`postingCount`, `revertCount`, `numscriptExecutionCount`, `referenceCount`, `ephemeralEvictedCount`, `transientUsedCount`, `volumeCount`) are sourced from the live usagestore projection, which is not checkpoint-aware, and are returned as `0` at a checkpoint rather than a live value — treat `0` on a checkpoint read as "not available at this checkpoint".

## Path parameters

- `ledgerName` string, required

## Headers

- `X-Consistency` 'linearizable' | 'stale'

## Response `200`

Ledger statistics retrieved successfully

- GetLedgerStatsResponse
  - `data` LedgerStats, required
    - `transactionCount` integer, required: Number of transactions in the ledger
    - `volumeCount` integer, required: Number of persisted (account, asset, color) volume rows
    - `referenceCount` integer, required: Number of transaction references registered in the ledger
    - `postingCount` integer, required: Total number of postings across all transactions
    - `logCount` integer, required: Number of log entries in the ledger
    - `ephemeralEvictedCount` integer, required: Number of ephemeral/draining volumes evicted from storage at commit
    - `transientUsedCount` integer, required: Number of transient volumes used across proposals
    - `revertCount` integer, required: Number of reverted transactions in the ledger
    - `numscriptExecutionCount` integer, required: Number of Numscript executions in the ledger

## Other responses

- `400`: Bad request
- `401`: Authentication required (missing or invalid JWT token)
- `403`: Insufficient permissions (missing required scope)
- `404`: Ledger not found (`LEDGER_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 `getLedgerStats` removed and replaced with `v3GetLedgerStats`
- **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-09-30** `b747efd5cd77`: 1 info
  - endpoint added
- **2026-09-29** `6ff73ac9a6bd`: 1 breaking
  - api path removed without deprecation

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