---
title: "Billing Usage Breakdown"
method: GET
path: "/api/billing/usage/breakdown"
tags: ["billing", "team"]
---

# Billing Usage Breakdown

`GET /api/billing/usage/breakdown`

## Request

- Base URL: `https://www.oxfordledge.com` (the document declares no server; this is the origin it was published from)
- URL: `https://www.oxfordledge.com/api/billing/usage/breakdown`
- Auth: none declared

Return per-AI-action usage rollup for the user's last 30 days.

Items list is sorted by total_quantity DESC (highest-cost AI
actions first) so the FE can render the user's AI activity summary
at a glance. Empty list for new users with no AI usage events.
Currently scoped to the 12 AI surfaces that call report_usage()
— see BILL-01 comment above the route for the design intent.

## Response `200`

Successful Response

- UsageBreakdownResponse: Wire shape for GET /api/billing/usage/breakdown. Returns up to 30 actions ordered by total_quantity DESC over the last `window_days` days (default 30).
  - `items` UsageBreakdownItem[], required: Per-action rollup, newest-cost-first. Empty list when the user has no usage events yet (new account).
    - `action` string, required: Endpoint or feature key (e.g., '/api/screener', '/api/ai/chat'). Comes from usage_events.action.
    - `count` integer, required: Number of times the action was logged.
    - `total_quantity` integer, required: Sum of usage_events.quantity for this action over the window. This is the credits-cost equivalent (quantity carries the per-call weight from ENDPOINT_TOKEN_WEIGHTS).
  - `total_quantity` integer, required: Sum of total_quantity across all items — the user's total credits used in the window. UI uses to compute per-action percentages.
  - `window_days` integer, required: Number of days the rollup covers (always 30 for now; field exists for future per-billing-cycle alignment).

---

[API](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api.md) · [All operations](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api/llms.txt) · [OpenAPI document](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api/revisions/e832a1260f0b?raw)