[DOCS] Status line docs missing `rate_limits` field for Claude.ai usage windows
Documentation Type
Missing documentation (feature not documented)
Documentation Location
https://code.claude.com/docs/en/statusline
Section/Topic
"Available data" table and "Full JSON schema" example
Current Documentation
The "Available data" table lists all top-level fields passed to statusline scripts via stdin: session, model, account, system, currentCost, and tool. The full JSON schema accordion shows a complete example payload. Neither the table nor the schema include a rate_limits field.
No documentation currently exists for the rate_limits statusline field, its sub-fields (used_percentage, resets_at), or the 5-hour and 7-day usage windows it exposes.
What's Wrong or Missing?
Changelog v2.1.80 added a rate_limits field to statusline scripts for displaying Claude.ai rate limit usage (5-hour and 7-day windows with used_percentage and resets_at). This field is not documented in the statusline page's "Available data" table or the full JSON schema example.
Users writing custom statusline scripts have no way to discover this field exists, what structure it contains, or how to use it to display rate limit information.
Suggested Improvement
Add a rate_limits row to the "Available data" table:
| Field | Description |
|-------|-------------|
| rate_limits | Claude.ai rate limit usage for 5-hour and 7-day windows, including used_percentage and resets_at for each window |
Update the full JSON schema example to include the rate_limits object with its nested structure showing both usage windows and their sub-fields.
Note: This field may be null or absent for non-Claude.ai authentication methods (e.g., API key, Bedrock, Vertex). Document null-handling behavior if applicable.
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/statusline | "Available data" table and full JSON schema example |
Total scope: 1 page affected
Source: Changelog v2.1.80
Addedrate_limitsfield to statusline scripts for displaying Claude.ai rate limit usage (5-hour and 7-day windows withused_percentageandresets_at)
4 Comments
Found 3 possible duplicate issues:
This issue will be automatically closed as a duplicate in 3 days.
🤖 Generated with Claude Code
I've been consuming the
rate_limitsfield in a statusline script since v2.1.80 landed. A few things I found that would be good to document:used_percentageis a float (e.g.7.000000000000001), needs flooring before displayresets_atis a Unix timestamp, not ISO 8601 like the API endpoint returnsFor reference, here's a working implementation that uses it for real-time 5h/7d quota display with pace tracking: https://github.com/Astro-Han/claude-lens
Issue #36383 Verification
Title: [DOCS] Status line docs missing
rate_limitsfield for Claude.ai usage windowsIssue Date: 2026-03-19
Verification Date: 2026-03-20
Status: RESOLVED
---
Issue Summary
This issue reports that the statusline documentation page is missing the
rate_limitsfield (added in changelog v2.1.80) from both the "Available data" table and the "Full JSON schema" example. The reporter notes that users writing custom statusline scripts have no way to discover therate_limitsfield, its sub-fields (used_percentage,resets_at), or the 5-hour and 7-day usage windows it exposes.---
Verification Results
Claim 1: "Available data" table missing
rate_limitsfieldStatus: RESOLVED
At https://code.claude.com/docs/en/statusline, the "Available data" table now includes two rows for rate limits:
Verdict: The
rate_limitsfield and all its sub-fields are now documented in the "Available data" table with clear descriptions.---
Claim 2: Full JSON schema example missing
rate_limitsobjectStatus: RESOLVED
At https://code.claude.com/docs/en/statusline, the "Full JSON schema" accordion now includes the complete
rate_limitsobject with nested structure:Verdict: The JSON schema example now shows the full
rate_limitsstructure with both usage windows and their sub-fields.---
Claim 3: No documentation for null/absence handling of
rate_limitsStatus: RESOLVED
At https://code.claude.com/docs/en/statusline, the "Fields that may be absent" section within the JSON schema accordion now documents:
Additionally, a dedicated "Rate limit usage" example section provides complete Bash, Python, and Node.js scripts demonstrating how to display rate limit information with graceful handling of absent fields.
Verdict: Null/absence behavior is documented, and practical usage examples are provided.
---
Current State
| Claim | Status |
|-------|--------|
| "Available data" table missing
rate_limits| RESOLVED || Full JSON schema missing
rate_limitsobject | RESOLVED || No documentation for null/absence handling | RESOLVED |
---
Suggested Fix
N/A - issue has been resolved.
---
References
rate_limitsfields in "Available data" tablerate_limitsobject in Full JSON schema examplerate_limitsabsence behavior---
Conclusion & Recommendation
Primary Concern: The statusline documentation was missing the
rate_limitsfield from the "Available data" table and JSON schema example, leaving users unable to discover rate limit information for custom statusline scripts.Resolution Status: RESOLVED
Recommendation: CLOSE
All three aspects of the reported issue have been addressed: the
rate_limitsfield is now in the "Available data" table with descriptions of all sub-fields, the full JSON schema example includes the complete nested structure, and absence/null handling is documented with a dedicated usage example section.---
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.