Usage & Budget API

Track token usage and manage spending budgets.

Endpoints

GET /usage

curl http://localhost:4200/usage

Response (200)

{
  "period": "2026-06",
  "total_tokens": 1284500,
  "total_requests": 892,
  "by_provider": {
    "anthropic": {"tokens": 980000, "requests": 650},
    "groq": {"tokens": 304500, "requests": 242}
  },
  "by_agent": {
    "claims-agent": {"tokens": 520000, "requests": 380},
    "assistant-01": {"tokens": 450000, "requests": 310}
  }
}

GET /usage/summary

curl http://localhost:4200/usage/summary

Response (200)

{
  "today": {"tokens": 42000, "requests": 28},
  "this_week": {"tokens": 285000, "requests": 195},
  "this_month": {"tokens": 1284500, "requests": 892},
  "estimated_cost_usd": 18.45
}

GET /budget

curl http://localhost:4200/budget

Response (200)

{
  "monthly_limit_usd": 100.00,
  "current_spend_usd": 18.45,
  "remaining_usd": 81.55,
  "percentage_used": 18.45,
  "action_on_limit": "warn"
}

PUT /budget

curl -X PUT http://localhost:4200/budget \
  -H "Content-Type: application/json" \
  -d '{
    "monthly_limit_usd": 200.00,
    "action_on_limit": "block"
  }'

Request Body

Response (200)

{
  "monthly_limit_usd": 200.00,
  "action_on_limit": "block",
  "updated": true
}