---
title: "Api Usage Breakdowns List Retrieve"
method: GET
path: "/api/usage-breakdowns/list/"
tags: ["platformApi"]
---

# Api Usage Breakdowns List Retrieve

`GET /api/usage-breakdowns/list/`

GET /api/usage-breakdowns/list/

Usage cost and request breakdown by dimension. The breakdown_by param
selects the grouping dimension (provider_id, model, deployment_name,
or feature). Defaults to current billing period.

When breakdown_by=feature, returns logging vs proxy cost split.
All other values query ClickHouse aggregations.

Query params: breakdown_by, sort_by, start_time, end_time, org (superadmin).
Response: { breakdown_by, breakdown_items, summary, billing_periods, start_time, end_time }

## Query parameters

- `breakdown_by` 'provider_id' | 'model' | 'deployment_name' | 'feature'
- `end_time` string, date-time
- `sort_by` 'number_of_requests' | 'total_cost'
- `start_time` string, date-time

## Headers

- `Authorization` string, required

## Response `200`

- UsageBreakdownResponse — Response for GET /payment/usage-breakdown/ Uses a fixed 'breakdown_items' key instead of a dynamic key. The 'breakdown_by' field tells the client which dimension was used.
  - `breakdown_by` string, required
  - `breakdown_items` UsageBreakdownItem[], required
    - `name` string, required — Breakdown dimension value
    - `total_cost` number, double, required
    - `number_of_requests` integer, required
    - `cost` number, double, required — Alias of total_cost for FE compat
  - `summary` UsageBreakdownSummary, required — Totals across all breakdown rows.
    - `cost` number, double, required
    - `name` string, required
    - `number_of_requests` integer, required
  - `billing_periods` BillingPeriod[], required
    - `start` string, required
    - `end` string, required
  - `start_time` string, required
  - `end_time` string, required

---

[API](https://skmtc.net/keywordsai/apis/api-reference.md) · [All operations](https://skmtc.net/keywordsai/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/keywordsai/api-reference/versions/c26d550029f8/schema)