Problem
As a user with multiple Claude Max accounts, I need programmatic access to subscription usage data. Currently, usage limits (session cap, weekly cap, extra usage balance) are only visible in the Claude Code status bar during an active session. There is no way to query this data across accounts or outside of an active session.
Requested Feature
A claude usage CLI command and/or Admin API endpoint that exposes:
- Current session usage vs limit — how much of the current session's capacity has been consumed
- Weekly usage vs limit — usage against the weekly cap
- Extra usage credit balance — remaining extra usage credits, if purchased
- Subscription tier — Max, Pro, etc. (already available via
claude auth status)
Ideal CLI interface
# Human-readable
claude usage
# Machine-readable for scripting
claude usage --json
Example JSON output:
{
"email": "user@example.com",
"subscriptionType": "max",
"session": {
"used": 45,
"limit": 100,
"unit": "messages"
},
"weekly": {
"used": 320,
"limit": 500,
"resetAt": "2026-04-13T00:00:00Z"
},
"extraUsage": {
"balanceUsd": 15.00,
"enabled": true
}
}Ideal Admin API endpoint
GET /v1/organizations/{org_id}/usage/subscription
This would complement the existing /usage_report/claude_code analytics endpoint by providing real-time subscription limit data rather than historical activity metrics.
Use Case
Users managing multiple Claude Code accounts (e.g., personal + multiple work accounts) currently have no way to:
- Check which account has remaining capacity before starting work
- Monitor usage across accounts without logging into each one individually
- Build dashboards or alerts around approaching limits
- Automate account switching when one account is near its cap
Current Workarounds
claude auth status --json — returns account info and subscription type, but no usage numbers~/.claude/stats-cache.json — local activity stats (messages, sessions, tool calls per day), but this is client-side tracking only and does not reflect server-side limits- Status bar — shows limits during an active session, but not queryable or scriptable
- Browser scraping claude.ai — fragile and not officially supported
None of these provide the actual server-side usage limit data.
Problem
As a user with multiple Claude Max accounts, I need programmatic access to subscription usage data. Currently, usage limits (session cap, weekly cap, extra usage balance) are only visible in the Claude Code status bar during an active session. There is no way to query this data across accounts or outside of an active session.
Requested Feature
A
claude usageCLI command and/or Admin API endpoint that exposes:claude auth status)Ideal CLI interface
Example JSON output:
{ "email": "user@example.com", "subscriptionType": "max", "session": { "used": 45, "limit": 100, "unit": "messages" }, "weekly": { "used": 320, "limit": 500, "resetAt": "2026-04-13T00:00:00Z" }, "extraUsage": { "balanceUsd": 15.00, "enabled": true } }Ideal Admin API endpoint
This would complement the existing
/usage_report/claude_codeanalytics endpoint by providing real-time subscription limit data rather than historical activity metrics.Use Case
Users managing multiple Claude Code accounts (e.g., personal + multiple work accounts) currently have no way to:
Current Workarounds
claude auth status --json— returns account info and subscription type, but no usage numbers~/.claude/stats-cache.json— local activity stats (messages, sessions, tool calls per day), but this is client-side tracking only and does not reflect server-side limitsNone of these provide the actual server-side usage limit data.