Feature request: claude usage command / API endpoint for Max subscription limits #44328

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:

1. Check which account has remaining capacity before starting work
2. Monitor usage across accounts without logging into each one individually
3. Build dashboards or alerts around approaching limits
4. 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.