Usage - Complete API Reference

Track token usage, estimate costs, and analyze AI consumption across sessions and users.

---

Chat Commands

View Usage

/usage                                      Current session usage
/usage today                                Today's total usage
/usage week                                 This week's usage
/usage month                                This month's usage

Detailed Breakdown

/usage breakdown [today]                    Cost breakdown by model
/usage by-model                             Usage by AI model (alias)
/usage by-user                              Usage by user
/usage history [days]                       Historical usage (default 7 days)
/usage estimate <model> <in> <out>          Estimate cost for tokens
/usage user <id> [today]                    User-specific usage

Management

/usage reset                                Clear all usage data

---

TypeScript API Reference

Create Usage Service

import { createUsageService } from 'clodds/usage';

const usage = createUsageService({
  // Storage
  storage: 'sqlite',  // 'sqlite' | 'postgres' | 'memory'
  dbPath: './usage.db',

  // Pricing (per 1M tokens)
  pricing: {
    'claude-3-opus': { input: 15.00, output: 75.00 },
    'claude-3-sonnet': { input: 3.00, output: 15.00 },
    'claude-3-haiku': { input: 0.25, output: 1.25 },
    'gpt-4': { input: 30.00, output: 60.00 },
    'gpt-4o': { input: 5.00, output: 15.00 },
  },

  // Footer mode
  footerMode: 'tokens',  // 'off' | 'tokens' | 'full'
});

Record Usage

// Record a request
await usage.record({
  userId: 'user-123',
  sessionId: 'session-456',
  model: 'claude-3-sonnet',
  inputTokens: 1500,
  outputTokens: 800,
  durationMs: 2300,
  cached: false,
});

Get Session Usage

const session = await usage.getSessionUsage('session-456');

console.log(`Session: ${session.sessionId}`);
console.log(`Requests: ${session.requests}`);
console.log(`Input tokens: ${session.inputTokens.toLocaleString()}`);
console.log(`Output tokens: ${session.outputTokens.toLocaleString()}`);
console.log(`Total tokens: ${session.totalTokens.toLocaleString()}`);
console.log(`Est. cost: $${session.estimatedCost.toFixed(4)}`);
console.log(`Duration: ${session.totalDurationMs}ms`);

Get User Usage

const user = await usage.getUserUsage('user-123', {
  period: 'month',  // 'day' | 'week' | 'month' | 'all'
});

console.log(`User: ${user.userId}`);
console.log(`Sessions: ${user.sessions}`);
console.log(`Total tokens: ${user.totalTokens.toLocaleString()}`);
console.log(`Est. cost: $${user.estimatedCost.toFixed(2)}`);

Get Total Usage

const total = await usage.getTotalUsage({
  from: '2024-01-01',
  to: '2024-01-31',
});

console.log(`Total requests: ${total.requests}`);
console.log(`Total tokens: ${total.totalTokens.toLocaleString()}`);
console.log(`Total cost: $${total.estimatedCost.toFixed(2)}`);

Usage by Model

const byModel = await usage.getUsageByModel({
  period: 'month',
});

for (const [model, stats] of Object.entries(byModel)) {
  console.log(`${model}:`);
  console.log(`  Requests: ${stats.requests}`);
  console.log(`  Tokens: ${stats.totalTokens.toLocaleString()}`);
  console.log(`  Cost: $${stats.cost.toFixed(2)}`);
}

Format Footer

// Get formatted usage footer for messages
const footer = usage.formatFooter({
  inputTokens: 1500,
  outputTokens: 800,
  model: 'claude-3-sonnet',
});

// Output: "Tokens: 1.5k in / 800 out | Cost: ~$0.02"

Format Summary

// Get formatted summary
const summary = await usage.formatSummary({
  userId: 'user-123',
  period: 'today',
});

console.log(summary);
// "Today: 15 requests | 45k tokens | ~$0.85"

Estimate Cost

// Estimate cost for a request
const cost = usage.estimateCost({
  model: 'claude-3-opus',
  inputTokens: 5000,
  outputTokens: 2000,
});

console.log(`Estimated cost: $${cost.toFixed(4)}`);

---

Model Pricing (per 1M tokens)

Model	Input	Output
claude-3-opus	$15.00	$75.00
claude-3-sonnet	$3.00	$15.00
claude-3-haiku	$0.25	$1.25
gpt-4	$30.00	$60.00
gpt-4o	$5.00	$15.00
gpt-4o-mini	$0.15	$0.60

---

Footer Modes

Mode	Output
off	No usage shown
tokens	Tokens: 1.5k in / 800 out
full	`Tokens: 1.5k in / 800 out

---

Budget Alerts

// Set monthly budget
usage.setBudget({
  userId: 'user-123',
  monthly: 50.00,  // $50/month
  alertAt: [0.5, 0.8, 0.95],  // Alert at 50%, 80%, 95%
});

// Check budget status
const budget = await usage.checkBudget('user-123');

console.log(`Budget: $${budget.limit}`);
console.log(`Used: $${budget.used.toFixed(2)} (${budget.percent}%)`);
console.log(`Remaining: $${budget.remaining.toFixed(2)}`);

---

Best Practices

1. Monitor regularly — Check usage weekly
2. Set budgets — Prevent unexpected costs
3. Use appropriate models — Haiku for simple tasks
4. Cache when possible — Reduce duplicate queries
5. Review by user — Identify heavy users