Get Request Usage
/v1/billing/{request_id}Returns a billing and metering summary for one inference call, keyed by the X-Trace-ID you receive in response headers on that call. If X-Trace-ID and X-Request-ID differ, this endpoint uses X-Trace-ID.
Authentication
Authorization Bearer
Use an API key in the Authorization header (sk-…).
Path Parameters
request_idstringrequiredBilling correlation id: X-Trace-ID from the HTTP response for that inference call. If X-Trace-ID and X-Request-ID differ, use X-Trace-ID.
Query Parameters
typeenum<string>Optional. Omit entirely to search across all modalities (same as all). Use llm | image | audio | video only when resolving by request id alone could collide and you must narrow the row.
Response
The body uses the standard R<T> envelope (code, msg, data, trace_id; service_code when present). On success, code is 200 and data is a billing reconciliation summary object (shape below). On failure, data is null.
codeintegerResponse status code.
msgstringResponse message.
dataobject | nulldata.idstringRow ID.
data.request_idstringBilling correlation id (typically matches the path when resolved).
data.typestringe.g. llm, image, audio, video.
data.modelstringDisplay model name.
data.model_namestring | nullModel name when available.
data.statusstringTask or request status when present.
data.create_timeinteger | string | nullCreated time, epoch seconds (UTC); JSON may be string or number depending on serializer.
data.update_timeinteger | string | nullLast update, epoch seconds (UTC); JSON may be string or number.
data.billedboolean | nullWhether usage has been charged (wallet / voucher / token path).
data.total_amountnumber | nullTotal charged amount when settled.
data.wallet_amountnumber | nullWallet-funded portion when applicable.
data.voucher_amountnumber | nullVoucher-funded portion when applicable.
data.bill_record_statusstring | nullBilling status when present.
data.status_codestring | nullRecorded HTTP / status code string on usage row when present.
data.pricenumber | nullList price snapshot on the usage row when present.
data.billing_atinteger | string | nullBilling timestamp as epoch seconds when present; JSON may be string or number.
data.amount_basenumber | nullAmount before discounts (rating pipeline), when present.
data.amount_finalnumber | nullFinal rated amount before wallet split, when present.
data.currencystring | nullCurrency for rated amounts, when present.
data.usageobject | nullMerged metering for reconciliation: token counts, nested usage, duration tiers, etc. (no heavy explain / trace blobs).
data.durationnumber | nullGeneration duration in seconds when known.
trace_idstring | nullServer trace id when available.
service_codestring | nullStable service error code when applicable.
Error handling
- 401 / unauthenticated: missing or invalid
Authorization. - 404: unknown
request_id, or no access. Note a short-lived 404 may mean the ledger row is not written yet because charges can land slightly after the model response.
Request ID (billing correlation)
- Use
X-Trace-IDfrom the inference response asrequest_idfor this endpoint. - If
X-Trace-IDandX-Request-IDdiffer, useX-Trace-ID. - You may send
X-Request-IDorX-Trace-IDon the request to pin your own correlation id; otherwise the platform generates one. - Do not use the chat JSON
id(chatcmpl-…) or the video resourceid(video_…) as this key. For video, persist headers fromPOST /v1/videos— eachGETpoll is a new HTTP trace. - For video tasks,
GET /v1/videos/{video_id}(or equivalent polling) may include ausageobject after the task reaches a terminal status, useful for meter-only checks beside this billing endpoint.