Usage Tracking - Codex-LB

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

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"

Overview

OpenAI-Compatible Endpoints

Codex Endpoints

Management API

​Overview

​Get Usage Summary

​Response

​Example Request

​Example Response

​Get Usage History

​Query Parameters

​Response

​Example Request

​Example Response

​Get Usage Window

​Query Parameters

​Response

​Example Request

​Example Response

​Usage Windows

​Primary Window (Daily)

​Secondary Window (Weekly)

​Usage Metrics Explained

​Credits vs Tokens

​Cost Tracking

​Error Rate

​Aggregation Logic

​Summary Endpoint

​History Endpoint

​Use Cases

Capacity Planning

Cost Management

Health Monitoring

Load Distribution

​Authentication

​Common Patterns

​Dashboard Widget

​Historical Analysis

​Window Comparison

Build docs developers (and LLMs) love

Overview

Get Usage Summary

Response

Example Request

Example Response

Get Usage History

Query Parameters

Response

Example Request

Example Response

Get Usage Window

Query Parameters

Response

Example Request

Example Response

Usage Windows

Primary Window (Daily)

Secondary Window (Weekly)

Usage Metrics Explained

Credits vs Tokens

Cost Tracking

Error Rate

Aggregation Logic

Summary Endpoint

History Endpoint

Use Cases

Authentication

Common Patterns

Dashboard Widget

Historical Analysis

Window Comparison