---
title: "Get Ledger Breakdown"
method: GET
path: "/billing/ledger/breakdown"
tags: ["billing"]
---

# Get Ledger Breakdown

`GET /billing/ledger/breakdown`

Return the active team's usage spend, grouped as requested.

Reads ``billing_ledger`` alone, so grouping never joins to ``requests`` and
agent spend can carry no prompt content (ENG-4722). Usage entries only:
top-ups, grants and adjustments are wallet movements rather than work, and
are what ``/balance`` accounts for.

Args:
    start: Inclusive lower bound on entry time.
    end: Exclusive upper bound on entry time.
    auth: Authenticated caller; the active billing team is read from scope.
    dimension: Grouping dimensions; at least one, or supply a grain.
    grain: Optional UTC day/month bucketing.
    project_id: Optional project filter.
    experiment_id: Optional experiment filter.

Returns:
    One row per group, largest spend first.

Raises:
    HTTPException: 422 when the window is invalid or no grouping is given.

## Query parameters

- `start` string, date-time, required — Inclusive lower bound on entry time (ISO, tz-aware)
- `end` string, date-time, required — Exclusive upper bound on entry time (ISO, tz-aware)
- `dimension` string[], nullable — Repeatable: category, model, provider, project, experiment
- `grain` 'day' | 'month', nullable — Bucket by UTC day or month
- `project_id` string, nullable — Restrict to one project
- `experiment_id` string, nullable — Restrict to one experiment

## Response `200`

Successful Response

- LedgerBreakdownResponse — Spend grouped over the ledger. Attributes: rows: One row per group, largest spend first.
  - `rows` LedgerBreakdownRow[], required
    - `category` string, nullable
    - `model` string, nullable
    - `provider` string, nullable
    - `project_id` string, nullable
    - `experiment_id` string, nullable
    - `period_start` string, date-time, nullable
    - `spend` string, required
    - `entries` integer, required

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-24** `1cffaad2a921` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/pioneer/apis/brain-api/changes/billing/ledger/breakdown/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/1cffaad2a921?raw)