Usage API

A read-only, cached JSON API that reports current Claude usage (5-hour, weekly, weekly Sonnet, Claude Design) across all the accounts in your ccas pool.

If you pool multiple accounts, Hep.gg can expose their live usage as a single read-only JSON endpoint. It's meant to be the source of truth for your own dashboards: it polls Anthropic on a safe schedule, caches the result, and serves from that cache, so your tools can poll it as often as they like without ever hitting Anthropic directly (and without burning your per-account rate limits).

Get a usage token#

ccas usage-token        # show (creates one if you don't have it)
ccas usage-token new    # rotate (invalidates the old one)

You can also reveal/rotate it from the AI → Accounts page in the dashboard. Give consumers the token as a bearer header.

Endpoint#

Authenticate with Authorization: Bearer <usage-token>.

{
  "version": 1,
  "fetched_at": "2026-05-31T18:00:00Z",
  "accounts": [
    {
      "id": "stable-unique-id",
      "label": "Work Max",
      "plan": { "rate_limit_tier": "default_claude_max_5x", "label": "Max 5x" },
      "status": "ok",
      "error": null,
      "fetched_at": "2026-05-31T17:59:40Z",
      "windows": {
        "five_hour":        { "utilization": 35.2, "resets_at": "2026-05-31T21:30:00Z", "expected": 28.0, "pace_delta": 7.2, "pace": "high" },
        "seven_day":        { "utilization": 5.0,  "resets_at": "2026-06-04T09:00:00Z", "expected": 8.0,  "pace_delta": -3.0, "pace": "under" },
        "seven_day_sonnet": { "utilization": 0.0,  "resets_at": "2026-06-04T09:00:00Z", "pace": "none" },
        "claude_design":    { "utilization": 0.0,  "resets_at": "2026-06-04T09:00:00Z", "pace": "none" }
      },
      "raw_usage": { }
    }
  ]
}

Field contract#

• id - stable per account across restarts; key your display/visibility off it.
• label - human name (your slot label or the account email); optional.
• plan.rate_limit_tier - the raw tier (e.g. default_claude_max_20x, default_claude_max_5x, default_claude_ai). plan.label is a friendly form.
• status - one of:
  • ok - last fetch succeeded.
  • rate_limited - upstream returned 429/5xx/timeout; last good data is kept.
  • auth_error - the account needs re-auth. Re-add it with ccas account login (a dedicated authorization that won't drop again), or ccas account add to re-snapshot.
  • error - anything else.
• error - short string when status != ok, else null.
• fetched_at (per account) - UTC of the last successful fetch for that account. It keeps returning the last good windows while status is degraded, so an "updated N ago" stays accurate.
• windows.* - keys: five_hour, seven_day (weekly, all models), seven_day_sonnet, and claude_design. Each is { "utilization": 0..100, "resets_at": <ISO8601 UTC>, … }, or null if that window doesn't apply. utilization is a percentage. (The old seven_day_opus window was retired by Anthropic. claude_design reflects Claude Design usage, which Anthropic reports under an internal codename; consume the labelled claude_design field rather than the raw key.)
• On-pace fields (per window, added server-side): tell you whether you're burning faster or slower than a steady rate that would hit 100% exactly at reset.
  • expected - the utilization you'd be at right now if perfectly on pace (elapsed fraction of the window x 100).
  • pace_delta - utilization - expected. Positive = ahead of pace (burning fast).
  • pace - a bucket for easy coloring: none (0% used or no reset time -> render neutral/white), under (behind pace -> green), over (0-5% ahead -> yellow), high (5%+ ahead -> red). expected/pace_delta are omitted when pace is none.
• raw_usage - the verbatim upstream usage object, so new windows appear without an API change.

Guarantees#

• All timestamps are ISO 8601 UTC.
• Served from cache, a consumer request never triggers an upstream call.
• Returns 200 with per-account status; one failing account doesn't fail the whole response.
• ETag is supported for conditional GETs.
• Tokens are never exposed in any response.