Cost Tracking for Claude Agent SDK Applications

## Overview

The Claude Agent SDK reports detailed token usage for each interaction. This
guide covers reading cost and usage correctly, especially with parallel tool use
and multi-step conversations.

## Scopes

- **query() call**: one `query()` invocation; produces one `result` message.
- **Step**: one request/response cycle within a call; produces assistant messages
  with usage.
- **Session**: multiple `query()` calls linked by a session id (`resume`); each
  call reports its own cost.

## Get the total for a call

The `result` message includes `total_cost_usd` (estimated) and cumulative usage:

```typescript
for await (const message of query({ prompt: "Summarize this project" })) {
  if (message.type === "result") {
    console.log(`Total cost: $${message.total_cost_usd}`);
  }
}
```

This is a **client-side estimate** from a bundled price table, not authoritative
billing. Use the Usage and Cost API or the Console for real charges.

## Per-step and per-model usage

Each assistant message carries `usage` (input/output tokens) and an `id`. Parallel
tool calls in one turn share an `id`, so deduplicate by id to avoid double
counting:

```typescript
const seen = new Set();
let input = 0, output = 0;
for await (const message of query({ prompt: "..." })) {
  if (message.type === "assistant" && !seen.has(message.message.id)) {
    seen.add(message.message.id);
    input += message.message.usage.input_tokens;
    output += message.message.usage.output_tokens;
  }
}
```

The result message's `modelUsage` (TS) / `model_usage` (Python) breaks cost and
tokens down per model, useful when subagents run a cheaper model.

## Accumulate across calls

The SDK has no session-level total; sum each call's `total_cost_usd` yourself when
running multiple `query()` calls.

## Cache tokens and failures

The SDK uses prompt caching automatically. The usage object includes
`cache_creation_input_tokens` (written, higher rate) and `cache_read_input_tokens`
(read, reduced rate); track them to understand caching savings. Both success and
error results include cost, so always read it regardless of subtype. To extend
cache TTL to one hour on API-key/Bedrock/Vertex/Foundry, set
`ENABLE_PROMPT_CACHING_1H`.

## Source

- Track cost and usage: https://code.claude.com/docs/en/agent-sdk/cost-tracking