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 requestusage- token counts for the requestduration_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
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗