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

# Token and cost tracking

> Understand how Orq.ai captures token usage from OpenTelemetry attributes, computes cost per LLM request, and where to find cost breakdowns.

**Orq.ai** captures token usage from every LLM request and computes cost automatically. No configuration is needed for most providers.

## How token counts are captured

Token counts arrive from provider responses via OpenTelemetry attributes:

* `gen_ai.usage.input_tokens` (input tokens)
* `gen_ai.usage.output_tokens` (output tokens)
* `gen_ai.usage.total_tokens` (sum, computed by Orq.ai)

Detailed breakdowns are captured when the provider reports them. These follow the provider's response shape (e.g. OpenAI, Anthropic) rather than a single standard:

* `input_tokens_details.cached_tokens` (tokens read from the prompt cache)
* `input_tokens_details.cache_creation_tokens` (tokens written to the prompt cache), with an Anthropic-only split into `cache_creation_5m_tokens` and `cache_creation_1h_tokens` by cache TTL
* `output_tokens_details.reasoning_tokens` (reasoning/thinking tokens)
* Audio input and output tokens

When a provider does not return usage data, the span is stored but cost attributes may be zero or absent.

## How cost is calculated

Cost is computed per span server-side. The **AI Gateway** multiplies token counts by the model's per-token rate:

```
cost = tokens × rate / 1,000,000
```

Rates are stored per model in the model catalog and expressed as USD per 1M tokens.

### Cost categories

| Category | Attribute | Description |
| - | - | - |
| Input | `orq.billing.input_cost` | Standard input tokens |
| Output | `orq.billing.output_cost` | Standard output tokens |
| Cache read | `orq.billing.cache_read_cost` | Tokens read from prompt cache |
| Cache write | `orq.billing.cache_write_cost` | Tokens written to prompt cache |
| Reasoning | `orq.billing.reasoning_cost` | Reasoning/thinking tokens |
| Audio input | `orq.billing.audio_input_cost` | Audio input tokens |
| Audio output | `orq.billing.audio_output_cost` | Audio output tokens |
| Web search | `orq.billing.web_search_cost` | Web search fees |
| **Total** | `orq.billing.total_cost` | Sum of all categories |

### Pricing tiers

Some providers charge different rates based on context length. **Orq.ai** applies the correct rate automatically:

| Tier | When applied |
| - | - |
| `standard` | Default context window pricing |
| `extended_128k` | Prompts exceeding 128K tokens |
| `extended_200k` | Prompts exceeding 200K tokens |

The active tier is recorded as `orq.billing.pricing_tier` on each span.

### Billable flag

`orq.billing.billable` is `false` for cached responses and automated [evaluations](/ai-studio/observability/trace-evaluations) run by the platform. These do not count toward workspace usage billing.

## Cost rollup

Cost rolls up through the data model:

| Level | How cost appears |
| - | - |
| **Span** | Per-span `orq.billing.*` attributes |
| **Trace** | Aggregated Total Cost in the Traces panel |
| **Thread** | Cost per thread in the Threads view |
| **Reporting API** | `genai.cost` (total) and `genai.usage` (bundle with input/output/cached/reasoning breakdown) |

## Where to see cost breakdowns

| Surface | What it shows |
| - | - |
| [Traces](/ai-studio/observability/traces) | Per-span cost, Total Cost filter, Economics panel |
| [Threads](/ai-studio/observability/threads) | Cost per thread |
| [Reporting API](/ai-studio/observability/reporting-api) | Aggregated cost by model, provider, project, identity |
| [Billing and Usage](/ai-studio/organization/billing-usage) | Platform billing: seats, storage, plan capacity |
| [Budgets](/ai-gateway/budgets) | Cost limits per scope with enforcement |
| [Alerts](/ai-studio/observability/alerts) | Cost threshold alerts |

## Related pages

* [Span Attributes](/ai-studio/observability/span-attributes): full reference of `orq.billing.*` attributes
* [Billing and Usage](/ai-studio/organization/billing-usage): platform billing (seats, storage, plan capacity), separate from LLM cost tracking
* [Budgets](/ai-gateway/budgets): set cost and token limits per scope


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