---
title: "Get Ledger Balance"
method: GET
path: "/v1/billing/ledger/balance"
tags: ["billing"]
---

# Get Ledger Balance

`GET /v1/billing/ledger/balance`

## Request

- Base URL: `https://api.pioneer.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.pioneer.ai/v1/billing/ledger/balance`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/pioneer/apis/brain-api/docs/v1/billing/ledger/balance/get.ts> (a function with typed inputs; its response is checked against the schema)

Return the active team's exact balance and wallet composition.

The total is exact — the latest monthly snapshot plus every entry since.
The composition comes from the aggregator's cache, so it can be staler;
``composition_drift`` is the gap, and a non-zero value means a client must
not present the split as authoritative.

Args:
    auth: Authenticated caller; the active billing team is read from scope.

Returns:
    Exact balance, its provenance, and the grant/purchased split.

## Response `200`

Successful Response

- LedgerBalanceResponse: A team's exact balance plus the provenance a dispute needs. Attributes: total: Exact balance in dollars, derived from the ledger. Negative is a real overdraft, never clamped. snapshot_month: Month of the snapshot the total was anchored on, or null when the whole log was summed because no snapshot existed. entries_since: How many entries were added to that anchor. composition: Grant/purchased split, from the aggregator's cache and so possibly staler than ``total``. composition_drift: ``total`` minus the composition. Non-zero means the aggregator is behind, and a client must not present the composition as authoritative.
  - `total` string, required
  - `snapshot_month` string, date, nullable, required
  - `entries_since` integer, required
  - `composition` WalletCompositionResponse, required: Grant-versus-purchased split of a wallet. Attributes: granted_remaining: Unspent grant dollars. Drained before purchased. purchased_remaining: Unspent paid dollars. May be negative.
    - `granted_remaining` string, required
    - `purchased_remaining` string, required
  - `composition_drift` string, required

## Changes

- **2026-09-24** `0e5e86e2bae5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/pioneer/apis/brain-api/changes/v1/billing/ledger/balance/get.md)

---

[API](https://skmtc.dev/pioneer/apis/brain-api.md) - [All operations](https://skmtc.dev/pioneer/apis/brain-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pioneer/apis/brain-api/revisions/0e5e86e2bae5?raw)