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

# Get Ledger Breakdown

`GET /v1/billing/ledger/breakdown`

## 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/breakdown`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/pioneer/apis/brain-api/docs/v1/billing/ledger/breakdown/get.ts> (a function with typed inputs; its response is checked against the schema)

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** `0e5e86e2bae5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/pioneer/apis/brain-api/changes/v1/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/0e5e86e2bae5?raw)