Usage Tracking

Monitor token usage and costs across accounts

Overview

The Usage Tracking API provides visibility into token consumption, costs, and usage patterns across all Claude accounts. You can retrieve summary statistics, historical usage data, and per-window breakdowns.

All Usage endpoints require dashboard authentication via session cookie.

Get Usage Summary

GET /api/usage/summary · endpoint

Retrieve aggregated usage statistics including current window state, costs, and key metrics.

Response

primary_window · object · required

Primary (daily) usage window aggregate

Show UsageWindow

remaining_percent · number

Average remaining capacity across accounts (0-100)

capacity_credits · number

Total capacity in credits

remaining_credits · number

Total remaining credits

reset_at · string

Next reset timestamp

window_minutes · integer

Window duration in minutes

secondary_window · object

Secondary (weekly) usage window aggregate (if applicable)

cost · object · required

Cost metrics

Show properties

currency · string

Currency code (e.g., “USD”)

totalUsd7d · number

Total cost in USD over last 7 days

metrics · object

Usage metrics

Show properties

requests7d · integer

Total requests in last 7 days

tokens_secondary_window · integer

Total tokens used in secondary window

cached_tokens_secondary_window · integer

Cached tokens in secondary window

errorRate7d · number

Error rate percentage over 7 days

top_error · string

Most common error message

Example Request

curl -X GET "https://your-instance.com/api/usage/summary" \
  -H "Cookie: dashboard_session=your-session-token"

Example Response

{
  "primary_window": {
    "remaining_percent": 68.5,
    "capacity_credits": 5000.0,
    "remaining_credits": 3425.0,
    "reset_at": "2026-03-04T00:00:00Z",
    "window_minutes": 1440
  },
  "secondary_window": {
    "remaining_percent": 82.3,
    "capacity_credits": 25000.0,
    "remaining_credits": 20575.0,
    "reset_at": "2026-03-10T00:00:00Z",
    "window_minutes": 10080
  },
  "cost": {
    "currency": "USD",
    "totalUsd7d": 125.48
  },
  "metrics": {
    "requests7d": 15420,
    "tokens_secondary_window": 2845000,
    "cached_tokens_secondary_window": 892000,
    "errorRate7d": 2.3,
    "top_error": "overloaded_error"
  }
}

Get Usage History

GET /api/usage/history · endpoint

Retrieve historical usage data per account over a specified time window.

Query Parameters

hours · integer · default: "24"

Number of hours to look back (1-168). Default is 24 hours.

Response

window_hours · integer · required

The number of hours covered by this response

accounts · array · required

Array of per-account usage history

Show UsageHistoryItem

account_id · string

Account identifier

remaining_percent_avg · number

Average remaining capacity over the window

capacity_credits · number

Account capacity

remaining_credits · number

Current remaining credits

Example Request

curl -X GET "https://your-instance.com/api/usage/history?hours=48" \
  -H "Cookie: dashboard_session=your-session-token"

Example Response

{
  "window_hours": 48,
  "accounts": [
    {
      "account_id": "acc_123abc",
      "remaining_percent_avg": 72.5,
      "capacity_credits": 1000.0,
      "remaining_credits": 680.0
    },
    {
      "account_id": "acc_456def",
      "remaining_percent_avg": 85.2,
      "capacity_credits": 1500.0,
      "remaining_credits": 1320.0
    }
  ]
}

Get Usage Window

GET /api/usage/window · endpoint

Retrieve current usage breakdown by window (primary or secondary) for all accounts.

Query Parameters

window · string · default: "primary"

Which window to query: primary (daily) or secondary (weekly)

Response

window_key · string · required

The window type queried (primary or secondary)

window_minutes · integer

Window duration in minutes

accounts · array · required

Array of per-account usage in this window (same structure as history endpoint)

Example Request

curl -X GET "https://your-instance.com/api/usage/window?window=secondary" \
  -H "Cookie: dashboard_session=your-session-token"

Example Response

{
  "window_key": "secondary",
  "window_minutes": 10080,
  "accounts": [
    {
      "account_id": "acc_123abc",
      "remaining_percent_avg": 78.0,
      "capacity_credits": 5000.0,
      "remaining_credits": 3900.0
    },
    {
      "account_id": "acc_456def",
      "remaining_percent_avg": 88.5,
      "capacity_credits": 7500.0,
      "remaining_credits": 6637.5
    }
  ]
}

Usage Windows

Claude accounts have two usage windows:

Primary Window (Daily)

• Resets every 24 hours
• Typically more restrictive quota
• Used for short-term rate limiting
• window_minutes: 1440

Secondary Window (Weekly)

• Resets every 7 days
• Larger quota for sustained usage
• Used for longer-term capacity planning
• window_minutes: 10080

Both windows are tracked independently. Codex-LB considers both when routing requests using the usage_weighted strategy.

Usage Metrics Explained

Credits vs Tokens

• Credits: Abstract capacity units used by Claude. Not directly equivalent to tokens.
• Tokens: Actual text units processed (input + output)
• Cached Tokens: Input tokens served from prompt cache

Cost Tracking

Costs are calculated based on:

• Model pricing (varies by model)
• Token counts (input, output, cached)
• Any reasoning effort multipliers

The totalUsd7d field aggregates costs across all accounts for the past 7 days.

Error Rate

The errorRate7d metric shows the percentage of requests that resulted in errors over the past week. Common error types:

• overloaded_error: Claude API is overloaded
• rate_limit_error: Account quota exceeded
• invalid_request_error: Malformed request

The top_error field shows the most frequent error message, helping identify systemic issues.

Aggregation Logic

Summary Endpoint

The summary endpoint aggregates across all active accounts:

• remaining_percent: Weighted average based on capacity
• capacity_credits: Sum of all account capacities
• remaining_credits: Sum of remaining credits across accounts
• reset_at: Earliest reset time across accounts (primary window)

History Endpoint

Historical data is sampled at regular intervals. The remaining_percent_avg represents the average remaining capacity over the requested time window.

Use Cases

Capacity Planning

Monitor primary and secondary window usage to predict when you’ll need additional accounts.

Cost Management

Track 7-day costs to stay within budget and identify expensive models or usage patterns.

Health Monitoring

Watch error rates and top errors to detect API issues or configuration problems.

Load Distribution

Use per-account history to verify load balancing is working as expected.

Authentication

All usage endpoints require dashboard authentication via session cookie.

Common Patterns

Dashboard Widget

Poll the summary endpoint every 30-60 seconds to power a real-time dashboard:

setInterval(async () => {
  const response = await fetch('/api/usage/summary', {
    credentials: 'include'
  });
  const data = await response.json();
  updateDashboard(data);
}, 30000);

Historical Analysis

Retrieve a week’s worth of history for trend analysis:

curl "https://your-instance.com/api/usage/history?hours=168"

Window Comparison

Compare primary and secondary window usage:

curl "https://your-instance.com/api/usage/window?window=primary"
curl "https://your-instance.com/api/usage/window?window=secondary"