# Fetch a cost record

GET

/v1/cost/records/{recordId}

```sh
curl --request GET \
  --url 'https://example.com/v1/cost/records/example?include=rawUsage' \
  --header 'Authorization: Bearer <token>'
```

## Authorizations

- **[bearerAuth](https://docs.kindgi.com/v0.1.9/reference/api.md#bearerauth)**

## Parameters

### Path Parameters

**recordId**

required

string

CostRecordId — opaque string identifier chosen by the binding.

### 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

### 200

Cost record.

application/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

**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

```json
{
  "status": "ok"
}
```

### 401

Missing / malformed / expired / revoked bearer token.

application/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

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 404

No cost record with that id under this tenant.

application/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

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

## See also

- [`GET /v1/cost/records`: List cost records](https://docs.kindgi.com/v0.1.9/reference/api/operations/costrecordslist.md)
- [Every error code](https://docs.kindgi.com/v0.1.9/reference/errors.md)