Skip to main content
GET
Get usage aggregation
This endpoint requires an Admin Key with the billing:read scope.Window caps depend on granularity: 1m up to 24 hours, 1h up to 31 days, 1d up to 93 days. uid[] is a filter dimension (only rows of keys owned by these users are returned); rows are grouped by bucket × model × project × key.

Granularity, alignment, and empty buckets

Data retention follows the platform retention policy (no fixed number of days is guaranteed); rows are grouped by bucket × model × project × key.

Authorizations

Authorization
string
header
required

Send the Admin API secret as a Bearer token in the Authorization header (Bearer sk-admin-***). Create Admin Keys under Console → Organization → Admin API Keys.

Path Parameters

usage_type
enum<string>
required

Usage type. Only completions is supported currently.

Available options:
completions

Query Parameters

start
integer<int64>
required

Start time in milliseconds, inclusive, e.g. 1790784000000 (2026-10-01 00:00 CST).

Required range: x >= 0
end
integer<int64>
required

End time in milliseconds, exclusive, e.g. 1792598400000 (2026-10-22 00:00 CST).

Required range: x >= 0
project_id
string[]

Project IDs. Every project must belong to the authenticated organization.

key
string[]

Business API key IDs. Every key must belong to the authenticated organization.

uid
string[]

User ID filters. Rows are restricted to these users within the organization.

granularity
enum<string>
default:1d

Time bucket granularity. Window caps differ by granularity: 1m allows up to 24 hours, 1h up to 31 days, 1d up to 93 days; 1d buckets are cut on Asia/Shanghai natural days.

Available options:
1m,
1h,
1d
limit
integer
default:100

Page size. Defaults to 100, maximum 1000.

Required range: 1 <= x <= 1000
cursor
string

Cursor from the previous response next field. The cursor carries only the page position; all query parameters must be restated on every page. Keep them unchanged while paginating (except limit) — the server does not check them for consistency.

Response

Usage aggregation rows, ascending by bucket time.

data
object[]
required

Usage aggregation rows (bucket × model × project × API key).

has_more
boolean
required

Whether there is a next page.

next
string | null
required

Cursor for the next page. Pass it back verbatim as the cursor query parameter.