Skip to content
Kindgi

Fetch a cost record

View as Markdown
GET
/v1/cost/records/{recordId}
curl --request GET \
  --url 'https://example.com/v1/cost/records/example?include=rawUsage' \
  --header 'Authorization: Bearer <token>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
recordId
required
string

CostRecordId — opaque string identifier chosen by the binding.

Query Parameters

Section titled “Query Parameters”
include
string
Allowed values: rawUsage

Extra fields, comma-separated. rawUsage: each model call’s usage object exactly as the vendor reported it.

Responses

Section titled “Responses”

200

Section titled “200”

Cost record.

Media typeapplication/json
object
id
required
string
tenantId
required
string format: uuid
category
required

Free-form resource category (llm.inference, tool.invocation, storage.write, sandbox.exec, …). Maps to resourceKind in the runtime.

string
providerId
string
runId
string format: uuid
agentId
string
conversationId
string format: uuid
quantity
required
number
unit
required

Metered unit (tokens, seconds, bytes, …).

string
costUsd
number
occurredAt
required
string format: date-time
metrics

Kind-specific counters (e.g. { promptTokens, completionTokens }).

object
key
additional properties
any
attributes

Free-form filter/display tags — never counters.

object
key
additional properties
any
callId

A model call’s id (category llm.inference); its provenance model-call node carries it too.

string
projectId
string format: uuid
rootRunId

The root of the record’s run tree (a flow run, for its agent turns).

string format: uuid
parentRunId
string format: uuid
agentVersion
string
flowId

The flow of the run tree’s root.

string
nodeId

The step that made the call.

string
step

The turn’s step number.

integer
>= 1
purpose

What the call was for, beyond the turn’s own model step: guardrail-judge:<guardrail id>.

string
model

The model actually called.

string
servedModel

The exact model version the vendor reported (vendors alias).

string
fallback

The router picked a fallback provider for the turn.

boolean
status

ok: the provider answered. failed: the call threw.

string
Allowed values: ok failed
usage

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
promptTokens
required
integer
completionTokens
required
integer
cacheReadTokens
integer
cacheWriteTokens
integer
reasoningTokens
integer
thinking

The call’s thinking. asked without level: nothing was sent (the model doesn’t think, or its adapter doesn’t say). level without asked: the model’s thinking.default. asked and level differ: the level was rounded to one the model takes, and the call warned thinking-level-adjusted.

object
asked

The level the call asked for: the agent’s model settings, or a judge’s lowest.

string
Allowed values: lowest minimal low medium high xhigh max
level

The level its adapter sent.

string
Allowed values: lowest minimal low medium high xhigh max
sent

The vendor’s own fields as they went out ({ "thinkingLevel": "LOW" }, { "reasoning_effort": "low" }); on the AI SDK path, { "reasoning": <the portable value> }.

object
key
additional properties
string
durationMs
integer
finishReason
string
providerRequestId

The vendor’s id for the request.

string
attempts

HTTP attempts the call took, the client’s retries included.

integer
>= 1
error

Why a model call failed (status: failed).

object
message
required
string
rawUsage

The vendor’s own usage object, exactly as it reported it. Only with include=rawUsage.

object
provider
required
string
model
required
string
usage
required
object
key
additional properties
any
Example
{
  "status": "ok",
  "thinking": {
    "asked": "lowest",
    "level": "lowest"
  }
}

401

Section titled “401”

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

Section titled “404”

No cost record with that id under this tenant.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

503

Section titled “503”

The database was too busy to answer in time (database-busy); Retry-After (whole seconds) says when to try again.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also