> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracepilotai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Token and cost tracking for every LLM call you make

> TracePilot AI captures per-span token usage and estimated API cost automatically for every wrapOpenAI call, with no extra configuration needed.

TracePilot AI records token usage and estimated API cost for every LLM call your agent makes. This data is captured automatically when you wrap calls with `tp.wrapOpenAI()` — no additional configuration, no separate instrumentation, and no changes to your agent logic. Every span in the dashboard shows exactly what each step cost.

## What gets captured

Each span created by `wrapOpenAI` records:

* **Prompt tokens** — the number of tokens in the messages you sent
* **Completion tokens** — the number of tokens in the model's response
* **Total tokens** — prompt plus completion
* **Estimated cost** — calculated from the model's public pricing at the time of the call

These fields appear on every LLM span in the dashboard. You can view them individually per span or aggregated across an entire trace.

## Viewing costs in the dashboard

Open any trace in the [TracePilot dashboard](https://tracepilotai.com/dashboard). The trace summary shows total token usage and estimated cost for the full run. Expand individual spans to see the breakdown per step.

This makes it easy to identify which steps in your agent are the most expensive — whether that's a verbose system prompt, a high-frequency tool loop, or an unnecessarily large model choice.

<Note>
  Cost estimates are based on publicly listed model pricing. They are accurate for standard OpenAI models but may differ slightly from your actual invoice if you have custom pricing agreements.
</Note>

## No extra configuration required

You do not need to configure cost tracking separately. TracePilot extracts token counts from the OpenAI response object, which already includes usage data. Wrapping the call is sufficient:

```typescript theme={null}
import { TracePilot } from 'tracepilot-sdk';
import OpenAI from 'openai';

const tp = new TracePilot('tp_live_YOUR_KEY');
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function runAgent() {
  await tp.startTrace('support-agent');

  const messages = [{ role: 'user', content: 'How do I reset my password?' }];

  // Token usage and cost are captured automatically
  const { result, spanId } = await tp.wrapOpenAI(
    () => openai.chat.completions.create({ model: 'gpt-4o-mini', messages }),
    messages
  );

  console.log(result.choices[0].message.content);
}
```

The `result` you receive is the unmodified OpenAI response. TracePilot reads the `usage` field from it before returning, so you never lose access to any data.

## Tracking costs across a multi-step agent

For agents with multiple LLM calls, TracePilot accumulates token data across all spans in the trace. Each span contributes its own usage, and the trace summary aggregates them.

```typescript theme={null}
async function researchAgent(query: string) {
  await tp.startTrace('research-agent');

  const messages = [{ role: 'user', content: query }];

  // Step 1 — cost tracked automatically
  const { result: plan, spanId: planSpanId } = await tp.wrapOpenAI(
    () => openai.chat.completions.create({ model: 'gpt-4o', messages }),
    messages
  );

  // Step 2 — tool call (no token cost, but latency tracked)
  const { result: searchResult, spanId: searchSpanId } = await tp.wrapToolCall(
    'web-search',
    () => webSearch(plan.choices[0].message.content),
    planSpanId,
    2
  );

  // Step 3 — cost tracked automatically
  const followUp = [
    ...messages,
    plan.choices[0].message,
    { role: 'tool', content: JSON.stringify(searchResult) }
  ];

  const { result: answer } = await tp.wrapOpenAI(
    () => openai.chat.completions.create({ model: 'gpt-4o', messages: followUp }),
    followUp,
    searchSpanId,
    3
  );

  return answer.choices[0].message.content;
}
```

After this agent runs, the dashboard shows the token cost for step 1 and step 3 separately, and the trace-level total. Tool call spans (step 2) do not carry token cost since they are not LLM calls.

## Destructive call warnings

A related cost-saving feature is the `isDestructive` flag on `wrapToolCall`. When you mark a tool call as destructive, TracePilot adds a **Destructive** badge to that span in the dashboard.

```typescript theme={null}
const { result, spanId } = await tp.wrapToolCall(
  'send-email',
  () => sendEmail(to, subject, body),
  parentSpanId,
  2,
  true // marks this span with a ⚠ Destructive badge
);
```

<Warning>
  Use `isDestructive: true` for any tool that writes to a database, sends a message, charges a payment method, or modifies external state. This makes it immediately visible in the dashboard when debugging a run, and prevents you from accidentally re-triggering those operations during Fork & Rerun.
</Warning>

Destructive badges serve as a visual checkpoint when reviewing trace costs. If a trace was unexpectedly expensive, you can quickly identify which steps had side effects and whether they were called more times than expected.

<CardGroup cols={2}>
  <Card title="Token usage" icon="chart-bar">
    Per-span prompt and completion token counts, visible on every LLM span in the dashboard.
  </Card>

  <Card title="Estimated cost" icon="dollar-sign">
    Calculated from model pricing on each span. Aggregated at the trace level for total run cost.
  </Card>

  <Card title="No configuration" icon="check">
    Cost data is extracted automatically from every `wrapOpenAI` response. Nothing to set up.
  </Card>

  <Card title="Destructive flags" icon="triangle-exclamation">
    Mark side-effecting tool calls with `isDestructive: true` to surface them clearly during debugging.
  </Card>
</CardGroup>