# List cost records

GET

/v1/cost/records

```sh
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

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

## Parameters

### Query Parameters

**limit**

integer

default: 25 >= 1 <= 100

1..100. Default 25.

**cursor**

string

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.

**runId**

string format: uuid

Filter records to this run id (exact match).

**agentId**

string

Filter records to this agent id (exact match).

**conversationId**

string format: uuid

Filter records to this conversation id (exact match).

**category**

string

Filter to a specific category (`llm.inference`, `tool.invocation`, `storage.write`, `sandbox.exec`, …). Exact match.

**providerId**

string

Filter records to this provider id (exact match).

**model**

string

Filter model calls to this model, the one actually called (exact match).

**servedModel**

string

Filter model calls to the exact model version the vendor reported (exact match).

**rootRunId**

string format: uuid

Every record of the run tree whose root is this run: a flow run and the agent turns and sub-flows it started.

**flowId**

string

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.

**includeDescendants**

boolean

With `runId`: the run’s records and those of every run it started, at any depth. `true` or `false` (default).

**from**

string format: date-time

ISO 8601 timestamp; records with `occurredAt >= from`. Required on `/v1/cost/aggregate` (or both endpoints omitted for default last-30-days window).

**to**

string format: date-time

ISO 8601 timestamp; records with `occurredAt < to` (exclusive). Required on `/v1/cost/aggregate` (or both endpoints omitted for default last-30-days window).

**scopeKind**

Discriminator for the ?scopeKind + ?scopeId + ?inherit triplet. Tenant carries no id (implicit from session); org/project require scopeId.

string

Allowed values: tenant org project

Optional scope discriminator. If absent, no scope filter is applied.

**scopeId**

string

\>= 1 characters

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.

**inherit**

boolean

default: true

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/…).

**include**

string

Allowed values: rawUsage

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

## Responses

### 200

Page of cost records.

application/json

object

**data**

required

Array\<object>

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

**nextCursor**

string

**hasMore**

required

boolean

##### Example

```json
{
  "data": [
    {
      "status": "ok"
    }
  ]
}
```

### 400

Malformed query parameter.

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"
  }
}
```

### 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"
  }
}
```

## See also

- [`GET /v1/cost/records/{recordId}`: Fetch a cost record](https://docs.kindgi.com/v0.1.10/reference/api/operations/costrecordsget.md)
- [Show runs in your app](https://docs.kindgi.com/v0.1.10/guides/runs/show-runs-in-your-app.md)
- [Kindgi 0.1.9](https://docs.kindgi.com/v0.1.10/releases/0.1.9.md)
- [Every error code](https://docs.kindgi.com/v0.1.10/reference/errors.md)