By Model
{Object.entries(data.byModel).map(([model, stats]) => (
{model}: {stats.tokens.toLocaleString()} tokens (${stats.cost.toFixed(2)})
))}
)
}
```
---
## Integration
### With Agent Factory
Token tracking is automatically integrated when using the agent factory:
```typescript
// In agent-factory.ts
const response = await model.invoke(messages)
// After LLM call, tokens are automatically tracked
await tokenTracker.trackUsage({
context,
sessionId,
provider: modelConfig.provider,
model: modelConfig.model,
usage: {
inputTokens: response.usage?.prompt_tokens || 0,
outputTokens: response.usage?.completion_tokens || 0,
totalTokens: response.usage?.total_tokens || 0,
},
agentName,
})
```
### With Graph Orchestrator
The graph orchestrator tracks usage at trace level:
```typescript
// End trace includes token stats
await tracer.endTrace(context, traceId, {
tokens: {
input: totalInputTokens,
output: totalOutputTokens,
total: totalInputTokens + totalOutputTokens,
},
cost: tokenTracker.calculateCost(model, usage).totalCost,
})
```
---
## Custom Pricing
### Override Default Pricing
```typescript
const customPricing = {
...DEFAULT_PRICING,
'my-custom-model': { input: 1.00, output: 2.00 },
}
const costs = tokenTracker.calculateCost('my-custom-model', usage, customPricing)
```
### Wildcard Pricing
Use wildcards for provider-level pricing:
```typescript
const pricing = {
'openai/*': { input: 0.50, output: 1.50 }, // Default for all OpenAI
'gpt-4o': { input: 5.00, output: 15.00 }, // Override specific model
}
```
---
## Query Periods
| Period | Description | SQL |
|--------|-------------|-----|
| `today` | Current date | `>= CURRENT_DATE` |
| `7d` | Last 7 days | `>= now() - 7 days` |
| `30d` | Last 30 days | `>= now() - 30 days` |
| `all` | All time | No filter |
---
## Cost Optimization Tips
### 1. Use Appropriate Models
```typescript
// For simple routing: use cheap model
'orchestrator': {
model: 'claude-3-haiku', // $0.25/$1.25 per 1M
}
// For complex synthesis: use capable model
'combiner': {
model: 'gpt-4o-mini', // $0.15/$0.60 per 1M
}
```
### 2. Monitor by Model
Check which models consume most tokens:
```typescript
const stats = await tokenTracker.getUsage(context, '30d')
// Sort by cost
Object.entries(stats.byModel)
.sort(([,a], [,b]) => b.cost - a.cost)
.forEach(([model, stats]) => {
console.log(`${model}: $${stats.cost.toFixed(2)}`)
})
```
### 3. Set Alerts
Monitor when usage exceeds thresholds:
```typescript
const stats = await tokenTracker.getUsage(context, 'today')
if (stats.totalCost > DAILY_BUDGET) {
// Send alert
await notifyAdmin(`Daily AI budget exceeded: $${stats.totalCost}`)
}
```
### 4. Use Local Models
For development or non-critical tasks:
```typescript
// Ollama models are free
'dev-agent': {
provider: 'ollama',
model: 'llama3.2', // Free (local)
}
```
---
## Troubleshooting
### Missing Token Counts
Some providers don't return usage in responses. Check:
1. Model supports usage metadata
2. Response includes `usage` field
3. Streaming mode may not include usage
### Zero Cost
If costs are $0.00:
1. Model might be using local provider (Ollama)
2. Model not in pricing table
3. Check for typos in model name
### High Costs
If costs are unexpectedly high:
1. Check model being used
2. Look for long inputs/outputs
3. Review request frequency
4. Consider caching responses
---
## Related Documentation
- [Observability](./01-observability.md) - Includes token tracking in traces
- [Graph Orchestrator](../03-orchestration/01-graph-orchestrator.md) - Optimized for fewer LLM calls
- [Configuration](../01-getting-started/03-configuration.md) - Model selection