Usage Tracking

Track LLM token usage per account with model-based cost calculation. Record usage after confirming a reservation, then query by account or view summaries. This guide walks through the flow with the TypeScript SDK.

Why usage tracking?

Credits can calculate cost from token counts and model ID using built-in pricing. By recording usage linked to a transaction (e.g. from a confirmed reservation), you get per-account and per-model breakdowns for dashboards, invoices, and analytics — without maintaining pricing tables yourself.

Step 1: Confirm a reservation (get a transaction)

Usage records for customer context must be tied to a transaction. The typical flow is: create a reservation → run the LLM call → confirm the reservation with the actual amount. The confirm response includes a transactionId to use when recording usage.

const { reservation } = await client.createReservation({
  externalId: "user_456",
  amount: 500,
});

// ... run your LLM, get input/output token counts ...

const confirmed = await client.confirmReservation(reservation.id, actualCreditsUsed);

// Use these when recording usage:
// - transactionId: confirmed.transactionId
// - accountId: confirmed.accountId (or externalId)

Step 2: Record usage (customer context)

Call recordUsage with context: "customer", the transaction ID from step 1, and the account identifier. Include modelId, usageType, and token counts. Cost is calculated automatically from built-in model pricing.

await client.recordUsage({
  context: "customer",
  transactionId: confirmed.transactionId,
  accountId: confirmed.accountId,  // or externalId: "user_456"
  modelId: "gpt-4o",
  usageType: "text",
  inputTokens: 1200,
  outputTokens: 380,
  cachedTokens: 0,           // optional, for cached context
  description: "Chat completion",
});

Step 3: Supported usage types and models

usageType can be text, audio_stt, audio_tts, or embedding. For audio, use audioDurationSeconds instead of tokens. List available models and pricing with client.listModels().

// List models and pricing
const { models } = await client.listModels();

// Estimate cost before recording (optional)
const estimate = await client.calculateCost({
  modelId: "gpt-4o",
  inputTokens: 1000,
  outputTokens: 500,
});
console.log("Estimated cost (USD):", estimate.estimatedCostUsd);

// Audio usage example
await client.recordUsage({
  context: "customer",
  transactionId: confirmed.transactionId,
  accountId: confirmed.accountId,
  modelId: "whisper-1",
  usageType: "audio_stt",
  audioDurationSeconds: 120,
  description: "Transcription",
});

Step 4: Query usage by account

Fetch usage records for an account (optionally filtered by model, date range, and context).

const result = await client.getUsage({
  externalId: "user_456",
  context: "customer",
  modelId: "gpt-4o",       // optional filter
  startDate: "2024-01-01",
  endDate: "2024-01-31",
});

if ("usageRecords" in result) {
  console.log("Records:", result.usageRecords);
} else {
  console.log("Summary:", result.summary);
}

Step 5: Get usage summary

Get aggregated totals and by-model breakdown. Use getUsageSummary or getUsage({ summary: true }).

const summary = await client.getUsageSummary("customer");

console.log("Total cost (USD):", summary.totalCostUsd);
console.log("Total input tokens:", summary.totalInputTokens);
console.log("Total output tokens:", summary.totalOutputTokens);
console.log("By model:", summary.byModel);
console.log("By context (customer vs system):", summary.byContext);

System vs customer context

Use context: "customer" when usage is billed to an account (transactionId and accountId/externalId required). Use context: "system" for internal or non-billable usage (e.g. background jobs); no transaction or account needed.