---
title: "Get Usage Breakdown"
method: GET
path: "/v1/organizations/billing/usage/breakdown"
tags: ["Organization Billing"]
---

# Get Usage Breakdown

`GET /v1/organizations/billing/usage/breakdown`

Get detailed usage breakdown.

Returns usage breakdown by operation type and extractor
for the specified billing period.

**Query Parameters:**
- `billing_month`: Month to query (YYYY-MM format, defaults to current)

**Requirements:**
- Read permission

**Example:**
```python
# Current month
response = await client.get("/v1/organizations/billing/usage/breakdown")

# Specific month
response = await client.get(
    "/v1/organizations/billing/usage/breakdown",
    params={"billing_month": "2025-11"}
)
```

## Query parameters

- `billing_month` string, nullable — Billing month in YYYY-MM format (defaults to current month)

## Response `200`

Successful Response

- UsageBreakdownResponse — Response with detailed usage breakdown.
  - `billing_month` string, required — Billing month (YYYY-MM)
  - `total_credits` integer, required — Total credits consumed
  - `total_cost_usd` number, required — Total cost in USD
  - `by_operation` object, required — Credits consumed by operation type
  - `by_extractor` object, required — Credits consumed by extractor
  - `by_namespace` object — Credits consumed by namespace (SP-242 — chargeback / cost-allocation for multi-namespace orgs). Keyed by namespace_id; excludes namespace-less consumption. Empty for older usage recorded before per-namespace attribution.
  - `by_retriever` object — Credits consumed by retriever (per-product query-cost attribution for chargeback). Keyed by retriever_id (resource_type='retriever' charges: queries, enrichment). Empty when no retriever-attributed usage.
  - `pending_credits` number — Unflushed sub-credit usage accrued but not yet committed to by_operation. Micro-priced per-op usage (e.g. MVS writes/queries at ~0.001 credit each) accumulates here and rolls into by_operation in whole credits as it crosses 1 — so real activity is visible immediately, before a whole credit accrues (BACKE-790).
  - `pending_by_operation` object — Unflushed fractional credits by operation type.
  - `period_start` string, date-time, required — Start of billing period
  - `period_end` string, date-time, required — End of billing period

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/5307993e44d3/schema)