v54

OpenAPI 3.1.0raw.githubusercontent.com2026-08-038690315.6 KB
usage

Ingest External Usage

Ingest a batch of externally-observed usage events (standalone).

Authenticated with either an API key or the master key. Usage binds to the authenticated principal: an API key attributes to its own user (and stamps its id on the rows); the master key may name any user via user_id. Records subscription-backed usage (e.g. Claude Code) as usage-log rows tagged with their source, priced at the effective API rate for each event's timestamp. Imported usage is real cost, but never counts toward budgets or mutates users.spend (it is retrospective, so it cannot be reserved). Idempotent by (source, source_event_id). The payload is content-free; any prompt/completion/tool field is rejected (422), not stored.

post/v1/usage/external-events

Request body

sourcestring required
user_idstring nullable

Response

Successful Response

acceptedinteger
duplicateinteger
rejectedinteger