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

# Rastreamento de tokens e custos

> Entenda como o Toqan Router captura o uso de tokens a partir de atributos do OpenTelemetry, calcula o custo por solicitação de LLM e onde encontrar os detalhamentos de custo.

O **Toqan Router** captura o uso de tokens de cada solicitação de LLM e calcula o custo automaticamente. Nenhuma configuração é necessária para a maioria dos provedores.

## Como as contagens de tokens são capturadas

As contagens de tokens chegam das respostas dos provedores por meio de atributos do OpenTelemetry:

* `gen_ai.usage.input_tokens` (tokens de entrada)
* `gen_ai.usage.output_tokens` (tokens de saída)
* `gen_ai.usage.total_tokens` (soma, calculada pelo Toqan Router)

Detalhamentos são capturados quando o provedor os informa. Eles seguem o formato de resposta do provedor (por exemplo, OpenAI, Anthropic), e não um padrão único:

* `input_tokens_details.cached_tokens` (tokens lidos do cache de prompt)
* `input_tokens_details.cache_creation_tokens` (tokens gravados no cache de prompt), com uma divisão exclusiva da Anthropic em `cache_creation_5m_tokens` e `cache_creation_1h_tokens` por TTL do cache
* `output_tokens_details.reasoning_tokens` (tokens de raciocínio/thinking)
* Tokens de entrada e saída de áudio

Quando um provedor não retorna dados de uso, o span é armazenado, mas os atributos de custo podem ser zero ou estar ausentes.

## Como o custo é calculado

O custo é calculado por span no servidor. O **AI Gateway** multiplica as contagens de tokens pela tarifa por token do modelo:

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

As tarifas são armazenadas por modelo no catálogo de modelos e expressas em USD por 1M de tokens.

### Categorias de custo

| Categoria | Atributo | Descrição |
| - | - | - |
| Entrada | `orq.billing.input_cost` | Tokens de entrada padrão |
| Saída | `orq.billing.output_cost` | Tokens de saída padrão |
| Leitura de cache | `orq.billing.cache_read_cost` | Tokens lidos do cache de prompt |
| Gravação de cache | `orq.billing.cache_write_cost` | Tokens gravados no cache de prompt |
| Raciocínio | `orq.billing.reasoning_cost` | Tokens de raciocínio/thinking |
| Entrada de áudio | `orq.billing.audio_input_cost` | Tokens de entrada de áudio |
| Saída de áudio | `orq.billing.audio_output_cost` | Tokens de saída de áudio |
| Pesquisa na web | `orq.billing.web_search_cost` | Tarifas de pesquisa na web |
| **Total** | `orq.billing.total_cost` | Soma de todas as categorias |

### Faixas de preço

Alguns provedores cobram tarifas diferentes de acordo com o tamanho do contexto. O **Toqan Router** aplica a tarifa correta automaticamente:

| Faixa | Quando é aplicada |
| - | - |
| `standard` | Preço padrão da janela de contexto |
| `extended_128k` | Prompts com mais de 128K tokens |
| `extended_200k` | Prompts com mais de 200K tokens |

A faixa ativa é registrada como `orq.billing.pricing_tier` em cada span.

### Flag de faturável

`orq.billing.billable` é `false` para respostas em cache e para [avaliações](/docs/pt-BR/ai-studio/observability/trace-evaluations.md) automatizadas executadas pela plataforma. Elas não contam para o faturamento de uso do workspace.

## Consolidação de custos

O custo é consolidado ao longo do modelo de dados:

| Nível | Como o custo aparece |
| - | - |
| **Span** | Atributos `orq.billing.*` por span |
| **Trace** | **Total cost** agregado no cabeçalho da página [Traces](/docs/pt-BR/ai-studio/observability/traces.md) |
| **Thread** | Custo por thread na visualização Threads |
| **Reporting API** | `genai.cost` (total) e `genai.usage` (pacote com detalhamento de entrada/saída/cache/raciocínio) |

## Onde ver os detalhamentos de custo

| Superfície | O que mostra |
| - | - |
| [Traces](/docs/pt-BR/ai-studio/observability/traces.md) | Custo por span, filtro Total Cost, painel Economics |
| [Threads](/docs/pt-BR/ai-studio/observability/threads.md) | Custo por thread |
| [Reporting API](/docs/pt-BR/ai-studio/observability/reporting-api.md) | Custo agregado por modelo, provedor, projeto e identidade |
| Billing and Usage | Faturamento da plataforma: assentos, armazenamento, capacidade do plano |
| [Budgets](/docs/pt-BR/ai-gateway/budgets.md) | Limites de custo por escopo, com aplicação |
| [Alerts](/docs/pt-BR/ai-studio/observability/alerts.md) | Alertas de limite de custo |

## Páginas relacionadas

* [Span Attributes](/docs/pt-BR/ai-studio/observability/span-attributes.md): referência completa dos atributos `orq.billing.*`
* Billing and Usage: faturamento da plataforma (assentos, armazenamento, capacidade do plano), separado do rastreamento de custos de LLM
* [Budgets](/docs/pt-BR/ai-gateway/budgets.md): defina limites de custo e de tokens por escopo


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