Feature request: programmatic access to subscription usage/budget consumption

Summary

The claude.ai web UI and app show a weekly/monthly subscription usage gauge (e.g., "60% of Pro plan used"), but there is no API endpoint or programmatic way to query this data.

Problem

Users on Pro/Max plans who want to:

• Set up warnings at usage thresholds (50%, 75%)
• Automatically switch from Opus to Sonnet when budget is running low
• Monitor usage via cron jobs or custom dashboards

...have no way to do so. The usage gauge data is only visible in the claude.ai web interface.

Note: The existing per-minute rate-limit headers (anthropic-ratelimit-*) are a different metric — they show RPM/ITPM/OTPM capacity, not subscription budget consumption.

Proposed solution

Add an API endpoint (e.g., GET /v1/usage/subscription or similar) that returns:

{
  "plan": "pro",
  "period": "weekly",
  "period_start": "2026-03-09T00:00:00Z",
  "period_end": "2026-03-16T00:00:00Z",
  "usage_percentage": 60.5,
  "model_breakdown": {
    "opus": { "percentage": 45.0 },
    "sonnet": { "percentage": 15.5 }
  }
}

Use case

• Claude Code hooks/status line scripts that warn at budget thresholds
• Cron jobs that monitor usage and send notifications
• Automated model switching to conserve budget (e.g., switch default to Sonnet after 75%)