[FEATURE] Expose enterprise spending limit data via /api/oauth/usage

[hongjun-bae]

Preflight Checklist

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

Problem Statement

I'm building a Claude Code statusline extension that displays real-time usage information. For subscription plans, the /api/oauth/usage endpoint provides five_hour and seven_day utilization data, which works great for showing usage limits with reset timers.

However, for enterprise plans, this endpoint returns no usage data at all. Enterprise users have per-user monthly spending limits visible in the Console UI (Settings > Usage), but there's no programmatic way to access this information. The statusline can only show rough session cost estimates, while subscription users get a much richer experience with actual limit tracking.

This makes it impossible to build tools that help enterprise users monitor their budget consumption in real time.

Proposed Solution

The /api/oauth/usage endpoint should return spending limit data for enterprise plans, similar to how it already returns five_hour/seven_day data for subscription plans:

{
  "spending_limit": {
    "limit_usd": 1000.00,
    "used_usd": 133.49,
    "utilization": 13.35,
    "resets_at": "2025-05-01T00:00:00Z"
  }
}

This keeps the response structure consistent — enterprise users get a spending_limit object, subscription users get five_hour/seven_day objects. Tools consuming this API can handle both plan types uniformly.

Alternative Solutions

• Console UI: Manually checking Settings > Usage in the browser — not programmatic, breaks workflow.
• Session cost estimation: Calculating approximate cost from token counts per model — inaccurate and doesn't reflect the actual spending limit or cumulative usage.

Priority

Nice to have — Enterprise users can still work without this, but it would significantly improve the developer experience and enable better tooling.

Feature Category

API / CLI behavior

Use Case Example

1. An enterprise user starts a Claude Code session with a $1,000/month spending limit
2. They've used $800 so far this month and want to be mindful of remaining budget
3. Their statusline currently shows: Opus 4.6 | v1.0.80 | main | 120k/1.0M | $2.35 (only session cost)
4. With this feature, the statusline could show: Opus 4.6 | v1.0.80 | main | 120k/1.0M | 80% (5d12h) — showing 80% of monthly limit used with reset timer, just like subscription plans show their 5h/7d limits
5. This helps users pace their usage and avoid hitting the limit unexpectedly

Additional Context

• The subscription plan response structure (five_hour.utilization, five_hour.resets_at) is a great pattern to follow
• The proposed spending_limit object mirrors the same shape for consistency
• This would enable the community to build richer statusline extensions and monitoring tools for enterprise environments

[github-actions]

Found 3 possible duplicate issues:

1. Feature Request: Expose enterprise spending limit & remaining budget via /api/oauth/usage #34346
2. No programmatic way to check usage - /usage rate limits paying Max subscribers #34199
3. [Feature Request] Add /v1/subscription/usage API endpoint for Claude Max plan metrics #29418

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[hongjun-bae]

Closing this issue — turns out the /api/oauth/usage endpoint already returns enterprise spending limit data under the extra_usage field:

{
  "extra_usage": {
    "is_enabled": true,
    "monthly_limit": 100000,
    "used_credits": 45710,
    "utilization": 45.71
  }
}

Using extra_usage.utilization and monthly_limit - used_credits, it's possible to display monthly usage percentage and remaining credits in the statusline — exactly what I was looking for.

The field name (extra_usage) wasn't documented, which is why I assumed it wasn't available. The proposed spending_limit shape in this issue would still be a cleaner API design, but functionally this is already solved.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.