---
name: claude-code-quota-source
description: How to read Claude Code 5h/weekly quota programmatically — statusLine rate_limits is the only supported route; no server-side API exists
metadata:
  type: reference
---

Claude Code subscription quota (the thing Anthropic actually throttles on) is
readable **only** via the `statusLine` command's stdin JSON:

```
.rate_limits.five_hour.used_percentage       .rate_limits.five_hour.resets_at
.rate_limits.seven_day.used_percentage       .rate_limits.seven_day.resets_at
.rate_limits.spend_limit.used_percentage     (gateway/overage billing only)
```

`used_percentage` is utilization*100. `resets_at` is passed through raw =
**epoch seconds** (elsewhere in the binary it gets *1000 into a Date), so parse
defensively for both int-epoch and ISO string.

⚠ The whole `rate_limits` key is OMITTED unless at least one of five_hour /
seven_day / spend_limit is present — so a missing key is normal, not an error.
**`seven_day_opus` is NOT in the statusLine payload.** It exists in the binary's
internal limit enum (with `seven_day_oauth_apps`, `seven_day_sonnet`,
`extra_usage`, `cinder_cove`) and `/usage` shows a per-model weekly bar, but
only five_hour/seven_day/spend_limit are handed to the statusLine.

**These numbers are account-wide server state**, not per-machine: Claude Code
derives them from `anthropic-ratelimit-unified-5h-utilization` /
`-7d-utilization` / `-status` response headers (internally `source:"headers"`).
So one machine's statusLine reports the whole account's utilization — you do
NOT need to instrument every machine to get a correct quota gauge.

What does NOT work (verified 2026-09-10, Claude Code 2.1.252):
- Those headers are **not** written to `~/.claude/projects/*.jsonl`. Transcripts
  carry only `message.usage` token counts. Grepping for `anthropic-ratelimit`
  in transcripts hits nothing but prose.
- No public API. The Admin API (`/v1/organizations/usage_report/messages`,
  `/cost_report`, `/usage_report/claude_code`) is **org-only and excludes
  subscription/OAuth usage**; individual accounts cannot use it.
- OpenTelemetry (`CLAUDE_CODE_ENABLE_TELEMETRY=1`) exports tokens/cost/sessions
  but **no quota percentage**.
- `/usage` in the CLI shows it but has no machine-readable output.

⚠ **Do not** lift the OAuth token from `~/.claude/.credentials.json` to poll
`https://api.anthropic.com/api/oauth/usage` (the endpoint Claude Code itself
calls). Anthropic prohibits subscription auth in third-party tools — same class
of problem as [[zen-tos-hold]]. The statusLine route is Claude Code handing us
the data, which is fine.

**Token sums are a bad proxy for quota.** Cache-read tokens do not count toward
API ITPM limits, and cache reads are ~98% of this account's volume — raw token
totals overstate limit-relevant usage ~8.7x. If approximating, use
`input_tokens + cache_creation + output_tokens`.