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

# Cost Tracking

> Automatic token counting and cost calculation for LLM calls

traceroot captures token usage from instrumented LLM calls. It calculates cost when the reported model ID matches an entry in traceroot's pricing table, regardless of which integration emitted the span, or uses the cost you [report directly](#report-cost-directly).

> [tab] Python
>
> ```python theme={null}
> import traceroot
> from traceroot import Integration
> from openai import OpenAI
>
> traceroot.initialize(integrations=[Integration.OPENAI])
> client = OpenAI()
>
> # OpenAI calls are tracked automatically; cost requires a priced model ID
> client.chat.completions.create(
>     model="gpt-4o",
>     messages=[{"role": "user", "content": "Hello"}]
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import OpenAI from 'openai';
> import { TraceRoot } from '@traceroot-ai/traceroot';
>
> TraceRoot.initialize({ instrumentModules: { openAI: OpenAI } });
> const client = new OpenAI();
>
> // OpenAI calls are tracked automatically; cost requires a priced model ID
> await client.chat.completions.create({
>   model: 'gpt-4o',
>   messages: [{ role: 'user', content: 'Hello' }],
> });
> ```

## How It Works

1. **Auto-instrumentation** — traceroot integrations capture token usage from the provider response automatically.
2. **Fallback estimation** — When token counts aren't in the response, traceroot estimates using tiktoken.
3. **Model matching** — The reported model ID is matched against traceroot's pricing table, including supported provider-prefixed and hosted aliases.
4. **Cost calculation** — When a match exists, token counts are multiplied by that entry's prices. An unmatched model still records tokens but has no calculated cost unless you [report one](#report-cost-directly).
5. **Reported cost** — If the span carries a cost you reported, it is stored in place of the calculated cost from step 4. Tokens are unchanged.

## Pricing coverage

Pricing entries currently cover these model families:

* OpenAI
* Anthropic, including supported model IDs routed through Amazon Bedrock and Claude 3.x model IDs on Google Vertex AI
* Google Gemini
* xAI
* DeepSeek
* Moonshot (Kimi)
* Z.AI (GLM)
* TypeSafe AI (JEV)

Coverage is based on model-ID patterns, not merely the provider or integration name. Notable model families without pricing entries include Mistral, Groq-hosted models, Amazon Nova and Titan, and Meta Llama. Routed models, such as models called through OpenRouter or Bedrock, are priced only when the routed model ID matches a pricing entry. If you call these through your own instrumented code, you can [report the cost directly](#report-cost-directly).

## What Gets Tracked

Each LLM span captures:

| Metric | Description |
| - | - |
| Input tokens | Tokens in the prompt/messages |
| Output tokens | Tokens in the completion/response |
| Total tokens | Sum of input and output |
| Cost (USD) | Calculated when the model ID matches the pricing table, or the cost you report |

## Viewing Costs

In the dashboard, costs are visible at both the span and trace level:

* **Per span** — see the cost of each individual LLM, tool or API call
* **Per trace** — see the total cost aggregated across all calls in the trace

![Trace detail with the LLM span cost chip and its Cost breakdown card highlighted](https://mintcdn.com/tracerootai/TLv21OVXbJzkJk5L/images/cost_breakdown_v1.png?fit=max\&auto=format\&n=TLv21OVXbJzkJk5L\&q=85\&s=30f66a56292555aaaaba61749f0cf2d7)

Span cost: cost chip and its input and output cost breakdown

## Manual Token Reporting

For custom or unsupported providers, report token usage manually:

> [tab] Python
>
> ```python theme={null}
> from traceroot import observe, update_current_span
>
> class MockLLM:
>     def generate(self, prompt):
>         class Response:
>             text = "mock response"
>             input_token_count = 10
>             output_token_count = 20
>         return Response()
>
> my_llm = MockLLM()
>
> @observe(name="custom_llm", type="llm")
> def call_custom_llm(prompt: str):
>     response = my_llm.generate(prompt)
>
>     update_current_span(
>         model="claude-opus-5",
>         usage={
>             "input_tokens": response.input_token_count,
>             "output_tokens": response.output_token_count,
>         },
>     )
>
>     return response.text
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { observe, updateCurrentSpan } from '@traceroot-ai/traceroot';
>
> const myLlm = {
>   generate: async (prompt: string) => ({
>     text: 'mock response',
>     inputTokenCount: 10,
>     outputTokenCount: 20,
>   }),
> };
>
> const result = await observe({ name: 'custom_llm', type: 'llm' }, async () => {
>   const prompt = "hello";
>   const response = await myLlm.generate(prompt);
>
>   updateCurrentSpan({
>     model: 'claude-opus-5',
>     usage: {
>       input: response.inputTokenCount,
>       output: response.outputTokenCount,
>     },
>   });
>
>   return response.text;
> });
> ```

> [!NOTE]
>
> **Usage keys differ by language:**
> In Python, use `input_tokens` and `output_tokens` (and `reasoning_tokens`, `cache_read_tokens`, `cache_write_tokens`).
> In TypeScript, use `input`, `output`, `cacheRead`, `cacheWrite`, and `total`.

## Report cost directly

When you already know what a call cost (a negotiated rate, a gateway's bill, an unpriced model), report it with the usage:

> [tab] Python
>
> ```python theme={null}
> from traceroot import update_current_span
>
> update_current_span(
>     model="claude-opus-5",
>     usage={"input_tokens": 10, "output_tokens": 20},
>     cost=0.0123,  # USD
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { updateCurrentSpan } from '@traceroot-ai/traceroot';
>
> updateCurrentSpan({
>   model: 'claude-opus-5',
>   usage: { input: 10, output: 20 },
>   cost: 0.0123, // USD
> });
> ```

> [!NOTE]
>
> Requires the Python SDK `traceroot` 0.5.0 or later, or the TypeScript SDK `@traceroot-ai/traceroot` 0.7.0 or later.

A reported cost replaces traceroot's computed price for that span. Report it as a number on the span that made the call. A cost of `0` is accepted and sets the span's cost to zero. Reporting a total on a parent span whose child spans are also priced counts the cost twice. Tokens are still recorded. The per-category cost breakdown is shown only when it matches the computed price, so a different reported cost hides it for that span and its trace. The cost is read from the OpenInference `llm.cost.total` attribute, so an OpenInference instrumentor that sets it is picked up automatically.

### Tool and API calls

A paid tool or API call takes a cost the same way, with no model or token usage needed. Tools bill in different ways, so first work out the dollar amount for the call, then report it on the tool's own span. The cost counts toward the trace total.

| How the tool bills | What to report | Example |
| - | - | - |
| [Price in the response](#price-in-the-response) | The price from the response | Exa |
| [Fixed price per call](#fixed-price-per-call) | Your price per call | PredictLeads |
| [Credits or quota](#credits-or-quota) | Credits used × your price per credit | Tavily |
| [Time used](#time-used) | Minutes used × your price per minute | TinyFish browser |

#### Price in the response

Some providers, such as [Exa](https://exa.ai/docs/reference/search), return the dollar cost of each request. Pass it through:

> [tab] Python
>
> ```python theme={null}
> from exa_py import Exa
> from traceroot import observe, update_current_span
>
> exa = Exa()
>
> @observe(name="web_search", type="tool")
> def web_search(query: str):
>     response = exa.search(query, num_results=3)
>     if response.cost_dollars:
>         update_current_span(cost=response.cost_dollars.total)
>     return response
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import Exa from 'exa-js';
> import { observe, updateCurrentSpan } from '@traceroot-ai/traceroot';
>
> const exa = new Exa(process.env.EXA_API_KEY);
>
> async function webSearch(query: string) {
>   return observe({ name: 'web_search', type: 'tool' }, async () => {
>     const response = await exa.search(query, { numResults: 3 });
>     if (response.costDollars) updateCurrentSpan({ cost: response.costDollars.total });
>     return response;
>   });
> }
> ```

![Span details for an exa\_search tool span with a cost of 0.007000, its search query input and the search results output](https://mintcdn.com/tracerootai/3SDwRl5xRxfZvr-4/images/tool_cost_price_in_response_v1.png?fit=max\&auto=format\&n=3SDwRl5xRxfZvr-4\&q=85\&s=6863aef569ace737aaa4d86c9d313ff5)

Price in the response: the tool span carries the price the search API returned

Some providers settle the price after the call returns. [Apify](https://docs.apify.com/api/v2/actor-run-get), for example, recommends reading a run's cost again about 10 seconds after it finishes. Report the settled value.

#### Fixed price per call

When every call costs the same, report your price on each call. A retry is another call and gets its own cost. traceroot records the cost you report, so report it for every response your provider bills. [PredictLeads](https://docs.predictleads.com/v3), for example, bills a lookup that returns no data yet but not a rejected one.

> [tab] Python
>
> ```python theme={null}
> import os
>
> import httpx
> from traceroot import observe, update_current_span
>
> PRICE_PER_CALL = 0.04  # your plan's price per request
> HEADERS = {
>     "X-Api-Key": os.environ["PREDICTLEADS_API_KEY"],
>     "X-Api-Token": os.environ["PREDICTLEADS_API_TOKEN"],
> }
>
> @observe(name="company_lookup", type="tool")
> def company_lookup(domain: str):
>     response = httpx.get(f"https://predictleads.com/api/v3/companies/{domain}", headers=HEADERS)
>     if response.is_success:
>         update_current_span(cost=PRICE_PER_CALL)
>     return response.json()
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { observe, updateCurrentSpan } from '@traceroot-ai/traceroot';
>
> const PRICE_PER_CALL = 0.04; // your plan's price per request
> const headers = {
>   'X-Api-Key': process.env.PREDICTLEADS_API_KEY!,
>   'X-Api-Token': process.env.PREDICTLEADS_API_TOKEN!,
> };
>
> async function companyLookup(domain: string) {
>   return observe({ name: 'company_lookup', type: 'tool' }, async () => {
>     const response = await fetch(`https://predictleads.com/api/v3/companies/${domain}`, { headers });
>     if (response.ok) updateCurrentSpan({ cost: PRICE_PER_CALL });
>     return response.json();
>   });
> }
> ```

#### Credits or quota

Some providers bill in credits, and a credit's dollar price depends on your plan. [Tavily](https://docs.tavily.com/documentation/api-reference/endpoint/search) returns the credits a search used when you ask for usage:

> [tab] Python
>
> ```python theme={null}
> from tavily import TavilyClient
> from traceroot import observe, update_current_span
>
> PRICE_PER_CREDIT = 0.008  # your plan's price per credit
>
> client = TavilyClient()
>
> @observe(name="web_search", type="tool")
> def web_search(query: str):
>     response = client.search(query, max_results=3, include_usage=True)
>     credits = response.get("usage", {}).get("credits")
>     if credits is not None:
>         update_current_span(cost=credits * PRICE_PER_CREDIT)
>     return response
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { tavily } from '@tavily/core';
> import { observe, updateCurrentSpan } from '@traceroot-ai/traceroot';
>
> const PRICE_PER_CREDIT = 0.008; // your plan's price per credit
>
> const client = tavily({ apiKey: process.env.TAVILY_API_KEY });
>
> async function webSearch(query: string) {
>   return observe({ name: 'web_search', type: 'tool' }, async () => {
>     const response = await client.search(query, { maxResults: 3, includeUsage: true });
>     const credits = response.usage?.credits;
>     if (credits !== undefined) updateCurrentSpan({ cost: credits * PRICE_PER_CREDIT });
>     return response;
>   });
> }
> ```

![Span details for a tavily\_search tool span with a cost of 0.008000 and its search query input](https://mintcdn.com/tracerootai/3SDwRl5xRxfZvr-4/images/tool_cost_credits_v1.png?fit=max\&auto=format\&n=3SDwRl5xRxfZvr-4\&q=85\&s=a399f51f86b80f63d676c4b3f47e2ccd)

Credits or quota: one credit at the plan rate on the tool span

#### Time used

Some tools bill by time, such as a remote browser billed per minute. Time the session and multiply by your price per minute. This is an estimate: the provider bills from its own usage records, which can run a little longer. This [TinyFish](https://docs.tinyfish.ai/api-reference/create-a-remote-browser-session) browser session reports its cost when it closes:

> [tab] Python
>
> ```python theme={null}
> import os
> import time
>
> import httpx
> from traceroot import observe, update_current_span
>
> PRICE_PER_MINUTE = 0.002  # your price per browser minute
> API = "https://api.browser.tinyfish.ai"
> HEADERS = {"X-API-Key": os.environ["TINYFISH_API_KEY"]}
>
> @observe(name="browse", type="tool")
> def browse(url: str):
>     start = time.monotonic()
>     session = httpx.post(API, headers=HEADERS, json={"url": url}, timeout=60).json()
>     try:
>         ...  # drive the browser through session["cdp_url"]
>     finally:
>         minutes = (time.monotonic() - start) / 60
>         update_current_span(cost=minutes * PRICE_PER_MINUTE)
>         httpx.delete(f"{API}/{session['session_id']}", headers=HEADERS)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { observe, updateCurrentSpan } from '@traceroot-ai/traceroot';
>
> const PRICE_PER_MINUTE = 0.002; // your price per browser minute
> const API = 'https://api.browser.tinyfish.ai';
> const headers = { 'X-API-Key': process.env.TINYFISH_API_KEY!, 'Content-Type': 'application/json' };
>
> async function browse(url: string) {
>   return observe({ name: 'browse', type: 'tool' }, async () => {
>     const start = performance.now();
>     const session = await (await fetch(API, { method: 'POST', headers, body: JSON.stringify({ url }) })).json();
>     try {
>       // drive the browser through session.cdp_url
>     } finally {
>       const minutes = (performance.now() - start) / 60000;
>       updateCurrentSpan({ cost: minutes * PRICE_PER_MINUTE });
>       await fetch(`${API}/${session.session_id}`, { method: 'DELETE', headers });
>     }
>   });
> }
> ```

![Span details for a tinyfish\_open\_page tool span with a cost of 0.000092, the page URL input and the loaded page title output](https://mintcdn.com/tracerootai/3SDwRl5xRxfZvr-4/images/tool_cost_time_used_v1.png?fit=max\&auto=format\&n=3SDwRl5xRxfZvr-4\&q=85\&s=1926ae586939d607f3710c4eabc5fa46)

Time used: browser minutes at the per-minute rate on the tool span


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.