Usage

Aggregated cost and usage breakdown for your workspace.

Get Usage Summary

GET /v1/usage/summary

Returns aggregated cost breakdown for today, last 7 days, and last 30 days, plus breakdowns by model and by user.

Auth: JWT or API Key

Response 200

{
  "today": {
    "total_usd": 12.50,
    "total_tokens": 250000,
    "run_count": 45
  },
  "last_7_days": {
    "total_usd": 85.20,
    "total_tokens": 1700000,
    "run_count": 312
  },
  "last_30_days": {
    "total_usd": 340.00,
    "total_tokens": 6800000,
    "run_count": 1250
  },
  "by_model": [
    {
      "model": "gpt-4o",
      "total_usd": 280.00,
      "prompt_tokens": 4500000,
      "completion_tokens": 900000
    },
    {
      "model": "gpt-4o-mini",
      "total_usd": 60.00,
      "prompt_tokens": 1200000,
      "completion_tokens": 200000
    }
  ],
  "by_user": [
    {
      "user_id": "alice",
      "total_usd": 150.00,
      "run_count": 520
    },
    {
      "user_id": "bob",
      "total_usd": 190.00,
      "run_count": 730
    }
  ],
  "monthly_run_count": 1250,
  "monthly_run_limit": 50000
}

Response Fields

Field	Type	Description
today	CostBreakdown	Aggregated costs for today
last_7_days	CostBreakdown	Aggregated costs for the last 7 days
last_30_days	CostBreakdown	Aggregated costs for the last 30 days
by_model	ModelCost[]	Cost breakdown by model
by_user	UserCost[]	Cost breakdown by SDK user
monthly_run_count	integer	Total runs this calendar month
monthly_run_limit	integer | null	Monthly run limit from plan tier (null = unlimited)

CostBreakdown

Field	Type	Description
total_usd	number	Total cost in USD
total_tokens	integer	Total tokens consumed
run_count	integer	Number of runs

ModelCost

Field	Type	Description
model	string	Model identifier
total_usd	number	Total cost for this model
prompt_tokens	integer	Total prompt tokens
completion_tokens	integer	Total completion tokens

UserCost

Field	Type	Description
user_id	string	SDK user identifier
total_usd	number	Total cost for this user
run_count	integer	Number of runs by this user