hermes-skills/ask-claude/references/usage-api-details.md

Anthropic OAuth Usage API — Confirmed Details

Verified live on 10.0.0.28 by Claude Opus, 2026-06-27.

Endpoint

GET https://api.anthropic.com/api/oauth/usage
Authorization: Bearer <token from ~/.claude/.credentials.json → .claudeAiOauth.accessToken>
anthropic-beta: oauth-2025-04-20

Response Fields

Field	Meaning	Notes
five_hour.utilization	Rolling 5-hour session usage (0–100)	Account-wide, not per-session
five_hour.resets_at	UTC ISO-8601 reset timestamp
seven_day.utilization	Weekly cap usage (0–100)	ALL models combined
seven_day.resets_at	UTC ISO-8601 reset timestamp
seven_day_opus	Opus-specific weekly	null on this plan
limits[]	Array with severity (normal/warning)	For threshold alerts

Token Expiry

~/.claude/.credentials.json has expiresAt. If expired, the curl 401s. Token auto-refreshes on next interactive claude run, but a headless-only loop can go stale. Not blocking for normal use — interactive runs keep it fresh.

Context % Formula (from print-mode JSON)

context_pct = (input_tokens + cache_creation_input_tokens + cache_read_input_tokens)
            / modelUsage[model].contextWindow * 100

All fields come from the same --output-format json envelope — zero extra HTTP calls.