Pricing & Costs

Traccia automatically calculates LLM costs at the moment each span ends, using a pricing table bundled with the SDK. This gives you cost visibility with zero configuration, even without a Traccia account. When you use the Traccia platform, costs are also recomputed server-side using an authoritative, org-aware snapshot.

How Cost Estimation Works

Cost estimation is enabled by default whenever enable_costs=True (the default). For each LLM span the SDK:

1. 1Reads prompt_tokens and completion_tokens from the LLM response (or counts them via tiktoken for providers that don't return usage).
2. 2Looks up the model's per-1K-token rates from the active pricing snapshot (see resolution order below).
3. 3Computes cost = (prompt_tokens / 1000 × prompt_rate) + (completion_tokens / 1000 × completion_rate).
4. 4Writes the result to the span as llm.cost.usd, along with pricing context attributes (see below).

from traccia import init
from openai import OpenAI

init()  # enable_costs=True by default

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)

# The span automatically includes:
# llm.cost.usd              → 0.000125   (computed from token counts × rates)
# llm.token.prompt_tokens   → 10
# llm.token.completion_tokens → 15
# llm.pricing.source        → "local_cache"
# llm.pricing.generated_at  → "2026-04-18T00:00:00Z"
# llm.pricing.age_days      → 0

Pricing Resolution Order

The SDK checks pricing sources in this order, using the first match found:

Per-Span Pricing Attributes

Every LLM span includes these attributes so you (and the platform) can always see exactly what pricing the SDK used at emit time:

Keeping Prices Fresh

The bundled snapshot is generated at SDK release time from an upstream database of 2,500+ models. It is always accurate at the time of release, but model prices change frequently. Between SDK upgrades you can pull the latest pricing without touching your code:

# Pull the latest from the Traccia platform (or upstream if platform unreachable)
traccia pricing refresh

# Check the current snapshot age and source
traccia pricing status

# Force upstream (no account needed)
traccia pricing refresh --source upstream

Overriding Pricing

Use overrides for fine-tuned models, custom API pricing, or internal cost allocation rates. Overrides always win over any other source.

Programmatic (per-process)

Passed directly to init(). Affects only the current Python process.

import traccia

traccia.init(
    pricing_override={
        "gpt-4o": {"prompt": 0.005, "completion": 0.015},
        "my-fine-tuned-gpt4": {"prompt": 0.008, "completion": 0.024},
    }
)

Environment variable (persistent)

Persists across restarts without code changes. Set in your .env or deployment environment.

export TRACCIA_PRICING_OVERRIDE_JSON='{"gpt-4o": {"prompt": 0.005, "completion": 0.015}}'

Override JSON schema

{
  "<model-name>": {
    "prompt": 0.005,
    "completion": 0.015,
    "cache_write": 0.001,
    "cached_prompt": 0.0005
  }
}

All rates are USD per 1,000 tokens. cache_write and cached_prompt are optional — for models with prompt-caching pricing (e.g. Claude 3.5 Sonnet).

Non-LLM Spans

The cost processor only annotates spans that look like LLM calls. If a span has span.type set to anything other than llm (case-insensitive), cost attributes are skipped — even when token counts are present. Leave span.type unset or set it to llm on LLM spans.

# Tool span — no llm.cost.usd added
with span("search_web", {"span.type": "tool"}) as s:
    results = search(query)

# LLM span — cost calculated normally
with span("llm.call", {"span.type": "llm", "llm.model": "gpt-4o"}) as s:
    response = client.chat.completions.create(...)

Disabling Cost Calculation

Cost estimation is enabled by default. To disable it (for example, to reduce span attribute size or when you rely entirely on platform-side costs):

# Programmatic
traccia.init(enable_costs=False)

# Environment variable
# TRACCIA_ENABLE_COSTS=false

# traccia.toml
# [instrumentation]
# enable_costs = false

SDK Costs vs Platform Costs

The SDK's llm.cost.usd and the platform's platform_cost_usd are computed independently and may differ slightly. This is by design.

See Platform Costs for a detailed explanation of divergence scenarios and how to resolve them.

See Also