List Usage

GET/v1/usage

Overview

Requires usage.read. Results are ordered by accounting time with an opaque, filter-bound cursor. from is inclusive and to is exclusive. Pending paid requests are excluded; inspect logs for unresolved holds. Legacy event timestamps can be backfilled, so pagination is not a database snapshot.

Authorization

Authorizationstring · headerRequired

AudioLab API key sent as Bearer <token>. Authentication guide

Parameters

workspace_idquery · string

Select an authorized workspace for session callers. API keys are always scoped to their own workspace.

limitquery · integer

cursorquery · string

fromquery · string

toquery · string

Responses

200Usage page.

application/json

dataobject[]Required

Show nested fields

idstringRequired

request_idstringRequired

Durable request ID returned in the x-request-id response header.

workspace_idstringRequired

key_idstring | null

sourcestringRequired

Values: "audio""llm""legacy""images""moderation""secondary"

taskstring | null

Values: "transcription""speech""s2s""llm""embeddings""images""moderation""ocr""rerank"null

modelstring | null

resolved_modelstring | null

providerstring | null

statestring | null

Values: "queued""running""succeeded""failed""canceled""unknown"null

error_codestring | null

unitstringRequired

costnumberRequired

Posted customer wallet debit in USD, after fractional carry.

accrued_coststring | null

Exact per-request customer accrual before carry, with 16 decimal places. Historical rows may not have this value.

currencystringRequired

secondsnumber | null

billable_secondsnumber | null

input_charsinteger | null

input_tokensinteger | null

Input tokens of selected successful outputs, excluding internal and failed attempts.

cached_tokensinteger | null

Input tokens served from cache, when reported by the provider. Null for usage that does not report caching.

output_tokensinteger | null

reasoning_tokensinteger | null

imagesinteger | null

created_atstringRequired

Settlement time for funded LLM, embeddings and images; usage completion time for audio and moderation; recorded event time for legacy data.

next_cursorstring | null

401Authentication is missing or invalid.

application/json

errorobjectRequired

Show nested fields

codestringRequired

messagestringRequired

paramstring | null

request_idstring | null

metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

500Internal server error.

application/json

errorobjectRequired

Show nested fields

codestringRequired

messagestringRequired

paramstring | null

request_idstring | null

metadataobject