[FEATURE] Official read-only usage endpoint for personal Pro/Max accounts (5h/7d limits, reset times, usage credits, product split)

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

As a Claude Max subscriber I want to show my current usage state in a local dashboard: 5-hour and 7-day utilization, reset times, remaining usage-credit balance, and - if available - the split between Claude.ai chats, Cowork and Claude Code. Today this information only exists on Settings -> Usage, and there is no supported way to read it programmatically for an individual account.

What exists today, and why it is not sufficient:

• The Claude Code status line exposes rate_limits.five_hour / seven_day (used_percentage, resets_at). This is documented and reliable, but push-only: values refresh only after an API response inside an active Claude Code session, and windows are dropped after resets_at. During idle periods or when working only in Claude.ai/Cowork there is no update.
• Usage credits and any product breakdown are visible only in Settings -> Usage. No API.
• The Admin API (Usage & Cost, Claude Code Analytics) and the Enterprise Analytics API are explicitly unavailable for individual accounts and measure tokens/cost, not the 5h/7d windows.
• Community tools work around this by reading the OAuth token from ~/.claude/.credentials.json and calling the undocumented /api/oauth/usage endpoint, or by scraping the settings page. Both are unsupported, fragile and - for credential reuse - undesirable from a security standpoint. We deliberately do not use either.

Proposed Solution

A documented, read-only, pull-based way for an individual Pro/Max account to obtain:

1. 5-hour and 7-day utilization (0-100 %) with resets_at (epoch seconds), same semantics as the status line
2. Usage-credit balance / extra-usage state
3. Usage split by product (chat, Cowork, Claude Code), if Anthropic tracks it
4. A server-side timestamp per reading, so clients can distinguish "connection OK" from "new measurement received"

Acceptable forms, in order of preference: (a) a documented account-scoped endpoint usable with a limited-scope token the user creates in Settings; (b) a claude usage --json CLI command that returns the same JSON the status line receives, callable outside an interactive session; (c) at minimum, documenting /api/oauth/usage with a stability guarantee.

Acceptance criteria:

• Works for a personal Max account without Admin/Analytics API access
• Returns the same numbers shown on Settings -> Usage at the same moment
• Each response carries a server timestamp
• Rate limit on the endpoint documented (polling every 1-2 min should be allowed)
• No reuse of browser cookies or Claude Code OAuth credentials required

Alternative Solutions

Current workarounds, all unsatisfactory: (1) Claude Code status line snapshot - solved for active sessions, not for the pull/idle case; (2) scraping Settings -> Usage with a browser extension - unsupported and fragile; (3) undocumented /api/oauth/usage with reused OAuth credentials - unsupported, security concern.

Related issues: #98197 (show account quota inside Claude Code - the interactive /usage view; this request is the programmatic, out-of-session counterpart), #13585 (Add Quota Information Access to Claude Code CLI - covers the CLI part), #89993 (programmatic usage/limit visibility as part of multi-account support), #20636 / #27915 / #34074 (status-line exposure, shipped). This request is broader: account-level, pull-based, including usage credits and product split, usable outside Claude Code.

The same request will also be submitted to Claude.ai support, since it concerns Claude.ai/Cowork as much as Claude Code.

Priority

Medium - Would be very helpful

Feature Category

Developer tools/SDK

Use Case Example

I run a local dashboard that shows my current Claude usage so I can pace my work across the day and week.

1. I work in Claude.ai chats and Cowork in the morning; no Claude Code session is running.
2. My dashboard polls a supported read-only endpoint (or runs claude usage --json) every 2 minutes.
3. It displays: 5h window 42% (resets 14:00), 7d window 63% (resets Tue 09:00), usage credits CHF/USD balance, and - if available - how much of the week went to chat vs. Cowork vs. Claude Code.
4. When I approach a limit I postpone heavy tasks until after the reset instead of being surprised mid-task.

Today step 2 is impossible without scraping or undocumented endpoints: the status line only updates while Claude Code is actively answering, and Settings -> Usage has no API.

Additional Context

_No response_