List cost records
const url = 'https://example.com/v1/cost/records?limit=25&includeDescendants=false&scopeKind=tenant&inherit=true&include=rawUsage';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://example.com/v1/cost/records?limit=25&includeDescendants=false&scopeKind=tenant&inherit=true&include=rawUsage' \ --header 'Authorization: Bearer <token>'Cursor-paginated. Filters (all AND): runId (with includeDescendants, its whole subtree), rootRunId, flowId, agentId, conversationId, category, providerId, model, servedModel, from, to. Sort order is fixed: occurredAt desc, id desc. Records represent one accounted resource event each — a model call (category llm.inference: one record per call, with its model, usage and what the vendor said about it), tool invocation, storage write, sandbox execution, etc. include=rawUsage adds each model call’s usage as the vendor reported it.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”1..100. Default 25.
Where the previous page ended: its nextCursor, as it came. A runtime that seals cursors takes one only for the same list, filters and caller, within a day; otherwise 400 bad-input, and the list starts again without it. Absent → first page.
Filter records to this run id (exact match).
Filter records to this agent id (exact match).
Filter records to this conversation id (exact match).
Filter to a specific category (llm.inference, tool.invocation, storage.write, sandbox.exec, …). Exact match.
Filter records to this provider id (exact match).
Filter model calls to this model, the one actually called (exact match).
Filter model calls to the exact model version the vendor reported (exact match).
Every record of the run tree whose root is this run: a flow run and the agent turns and sub-flows it started.
Every record of the run trees whose root is a run of this flow (the record’s flowId, exact match): the flow’s spend across its runs, any version.
With runId: the run’s records and those of every run it started, at any depth. true or false (default).
ISO 8601 timestamp; records with occurredAt >= from. Required on /v1/cost/aggregate (or both endpoints omitted for default last-30-days window).
ISO 8601 timestamp; records with occurredAt < to (exclusive). Required on /v1/cost/aggregate (or both endpoints omitted for default last-30-days window).
Discriminator for the ?scopeKind + ?scopeId + ?inherit triplet. Tenant carries no id (implicit from session); org/project require scopeId.
Optional scope discriminator. If absent, no scope filter is applied.
Required IF scopeKind is org or project. MUST be absent if scopeKind=tenant (tenant is implicit from the session). Malformed combinations return 400 scope-invalid.
Default true. false = literal-at-this-scope only (admin/audit view). Load-bearing for policy/config-scoped resources (mcp-endpoints); documented no-op for content-scoped resources (agents/flows/tools/…).
Extra fields, comma-separated. rawUsage: each model call’s usage object exactly as the vendor reported it.
Responses
Section titled “Responses”Page of cost records.
object
object
Free-form resource category (llm.inference, tool.invocation, storage.write, sandbox.exec, …). Maps to resourceKind in the runtime.
Metered unit (tokens, seconds, bytes, …).
Kind-specific counters (e.g. { promptTokens, completionTokens }).
object
Free-form filter/display tags — never counters.
object
A model call’s id (category llm.inference); its provenance model-call node carries it too.
The root of the record’s run tree (a flow run, for its agent turns).
The flow of the run tree’s root.
The step that made the call.
The turn’s step number.
What the call was for, beyond the turn’s own model step: guardrail-judge:<guardrail id>.
The model actually called.
The exact model version the vendor reported (vendors alias).
The router picked a fallback provider for the turn.
ok: the provider answered. failed: the call threw.
The call’s tokens. promptTokens / completionTokens are the totals; cacheReadTokens / cacheWriteTokens are parts of promptTokens, reasoningTokens of completionTokens, present when the provider reports them.
object
The vendor’s id for the request.
HTTP attempts the call took, the client’s retries included.
Why a model call failed (status: failed).
object
The vendor’s own usage object, exactly as it reported it. Only with include=rawUsage.
object
object
Example
{ "data": [ { "status": "ok" } ]}Malformed query parameter.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Missing / malformed / expired / revoked bearer token.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}