feat: expose account usage/quota information via SDK

Resolved 💬 2 comments Opened Feb 2, 2026 by paolino Closed Mar 3, 2026

Summary

Add the ability to query account-level usage and quota information through the Claude SDK, similar to what's shown at https://claude.ai/settings/usage

Use Case

When building applications on top of Claude Code (like Telegram voice agents), users want to see their usage stats including:

  • Weekly token usage and remaining quota (for Max plan users)
  • Rate limit status (requests/tokens per minute remaining)
  • Context window usage

Current Situation

The SDK's ResultMessage provides per-request metrics:

  • total_cost_usd - cost of the request
  • usage - token counts for the request
  • duration_api_ms - API duration

But there's no way to query:

  • Account-level weekly usage/quota (Max plan)
  • Rate limit headers (anthropic-ratelimit-requests-remaining, etc.)
  • Overall context window state

Proposed Solution

Add a method to ClaudeSDKClient to query usage/quota:

async def get_usage(self) -> UsageInfo:
    """Get account usage and quota information."""
    ...

@dataclass
class UsageInfo:
    # Weekly usage (Max plan)
    weekly_tokens_used: int | None
    weekly_tokens_limit: int | None
    weekly_reset_time: datetime | None
    
    # Rate limits
    requests_remaining: int | None
    tokens_remaining: int | None
    rate_limit_reset: datetime | None

Alternatively, expose the rate limit headers from API responses.

Workarounds Attempted

  • Checked CLI for usage command - not available
  • Checked SDK response objects - only per-request data
  • Web scraping claude.ai/settings/usage - not reliable/recommended

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗