> ## 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 and 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` (cached input tokens)
* `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](/docs/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](/docs/ai-studio/observability/traces)                  | Per-span cost, Total Cost filter, Economics panel     |
| [Threads](/docs/ai-studio/observability/threads)                | Cost per thread                                       |
| [Reporting API](/docs/ai-studio/observability/reporting-api)    | Aggregated cost by model, provider, project, identity |
| [Billing and Usage](/docs/ai-studio/organization/billing-usage) | Platform billing: seats, storage, plan capacity       |
| [Budgets](/docs/ai-gateway/budgets)                             | Cost limits per scope with enforcement                |
| [Alerts](/docs/ai-studio/observability/alerts)                  | Cost threshold alerts                                 |

## Related pages

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