# Cost Tracking

AxonHub provides real-time cost calculation and usage tracking for every request.

## Overview

Cost tracking in AxonHub helps you monitor and control your AI spending across all providers and models. Each request is automatically analyzed and cost is calculated based on configurable pricing.

## Features

### Token Type Tracking

AxonHub tracks the following token types:

| Token Type | Description | Code |
|------------|-------------|------|
| **Input (Prompt)** | Tokens sent to the model (excluding cached tokens) | `prompt_tokens` |
| **Output (Completion)** | Tokens generated by the model | `completion_tokens` |
| **Cache Read** | Tokens read from cache | `prompt_cached_tokens` |
| **Cache Write** | Tokens written to cache | `prompt_write_cached_tokens` |
| **Reasoning** | Reasoning tokens (for supported models) | `completion_reasoning_tokens` |
| **Cache Write (5 min)** | Anthropic 5-minute TTL cache write | `prompt_write_cached_tokens_5m` |
| **Cache Write (1 hour)** | Anthropic 1-hour TTL cache write | `prompt_write_cached_tokens_1h` |

### Pricing Modes

AxonHub supports three pricing modes:

| Mode | Description | Use Case |
|------|-------------|----------|
| **Flat Fee** (`flat_fee`) | Fixed fee per request | Fixed cost scenarios |
| **Usage Per Unit** (`usage_per_unit`) | Price per 1M tokens | Most models |
| **Tiered** (`usage_tiered`) | Tiered pricing based on usage | Volume discount scenarios |

### Cost Breakdown

Every request includes a detailed cost breakdown:

```json
{
  "costItems": [
    {
      "itemCode": "prompt_tokens",
      "quantity": 1000,
      "subtotal": 0.0015
    },
    {
      "itemCode": "completion_tokens",
      "quantity": 500,
      "subtotal": 0.0020
    },
    {
      "itemCode": "prompt_cached_tokens",
      "quantity": 2000,
      "subtotal": 0.0005
    }
  ],
  "totalCost": 0.0050
}
```

### Tiered Pricing Breakdown

When using tiered pricing, the cost breakdown includes tier details:

```json
{
  "itemCode": "prompt_tokens",
  "quantity": 150000,
  "tierBreakdown": [
    {
      "upTo": 100000,
      "units": 100000,
      "subtotal": 0.1000
    },
    {
      "upTo": null,
      "units": 50000,
      "subtotal": 0.0750
    }
  ],
  "subtotal": 0.1750
}
```

## Configuration

### Model Pricing

Configure pricing for each channel and model in the admin dashboard:

1. Go to **Channels** → **Model Prices**
2. Set pricing items for each model:

![Model Pricing](../../screenshots/axonhub-model-price.png)

   - Input price (`prompt_tokens`)
   - Output price (`completion_tokens`)
   - Cache read price (`prompt_cached_tokens`)
   - Cache write price (`prompt_write_cached_tokens`)

#### Cache Write Variants (Anthropic)

For Anthropic models, you can configure TTL variants for cache writes:
- **5 minutes** (`five_min`): Short-term cache
- **1 hour** (`one_hour`): Long-term cache

### Cost Calculation Logic

1. **Input Token Calculation**: `PromptTokens - CachedTokens - WriteCachedTokens`
   - Cached tokens are billed separately at different rates

2. **Cache Write Variant Processing**:
   - If `WriteCached5MinTokens` or `WriteCached1HourTokens` are present, use corresponding variant pricing
   - Otherwise, use the default cache write price

3. **Price Versioning**:
   - Each price change creates a new version record
   - Usage logs reference the specific price version via `cost_price_reference_id`

## Viewing Costs

### Usage Logs

Each request's usage log contains:

- **Token Usage**: prompt_tokens, completion_tokens, total_tokens
- **Token Details**: Breakdown of various token types
- **Cost Information**: total_cost, cost_items, cost_price_reference_id

### GraphQL API

Query usage logs with cost information:

```graphql
query GetUsageLogs {
  usageLogs {
    edges {
      node {
        modelId
        promptTokens
        completionTokens
        totalTokens
        totalCost
        costItems {
          itemCode
          quantity
          subtotal
          tierBreakdown {
            upTo
            units
            subtotal
          }
        }
        costPriceReferenceId
      }
    }
  }
}
```

### Cost Fields Description

| Field | Type | Description |
|-------|------|-------------|
| `totalCost` | Float | Total cost calculated based on channel model price |
| `costItems` | JSON | Array of cost breakdown items |
| `costPriceReferenceId` | String | Reference ID to the price version used for cost calculation |

## Best Practices

1. **Configure Model Prices**: Set accurate prices for each channel and model before use
2. **Monitor Cache Usage**: Cache can significantly reduce costs; monitor cache hit rates
3. **Use Price Versioning**: Price changes automatically create versions for cost traceability
4. **Review Regularly**: Check usage logs and cost reports to optimize usage

## Troubleshooting

### Missing Cost Data

If costs are not showing:

1. Verify channel model prices are configured
2. Check if the provider returns token usage
3. Review the `costPriceReferenceId` in usage logs

### Incorrect Costs

If costs seem incorrect:

1. Verify pricing configuration (especially cache prices)
2. Check token count details in usage logs
3. Confirm the correct price version was used
4. For tiered pricing, verify tier configuration is correct