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

# Billing Usage

`GET /api/billing/usage`

## 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`
- Auth: none declared

Return billing usage summary for current user.

Optional `?breakdown=1` query (METER-04): include the per-action
rollup that powers the Usage page's "where did my credits go?"
section. Identical shape to `/api/billing/usage/breakdown` items.

## Query parameters

- `breakdown` integer: If 1, include per-action 30-day breakdown in `breakdown` field. Saves a round-trip vs calling /api/billing/usage/breakdown. METER-04 (UX_audit_2026_05_10).

## Response `200`

Successful Response

- BillingUsageResponse: `GET /api/billing/usage` response. Required fields = intersection across all 3 branches: anon: {tier, tier_display, usage, limit, billing_period, authenticated} auth + summary OK: {tier, tier_display, usage, limit, overage, cap, spent, cap_reached, period_end, billing_period, billing_mode, credit_balance, [trial_end]} auth + summary fail: {tier, usage, limit, cap, spent, cap_reached, period_end, [trial_end]} Boundary contract: tier + usage + limit MUST always be present (consumed by the credit indicator + settings panel + topstrip).
  - `tier` string, required
  - `usage` integer, required
  - `limit` integer, required
  - `tier_display` string, nullable
  - `overage` integer, nullable
  - `cap` number, nullable
  - `spent` number, nullable
  - `cap_reached` boolean, nullable
  - `period_start` string, nullable
  - `period_end` string, nullable
  - `billing_period` string, nullable
  - `billing_mode` string, nullable
  - `credit_balance` number, nullable
  - `trial_end` string, nullable
  - `authenticated` boolean, nullable
  - `breakdown` object[], nullable
  - `dunning` object, nullable
  - `effective_tier` string, nullable
  - `consumer_tier` string, nullable
  - `agent_plan` string, nullable

## Other responses

- `422`: Validation Error

---

[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)