The Claude Code weekly cap is a float, not a count of hours.
Anthropic told the press 40 to 480 hours per week, depending on plan. The number your account actually hits is a seven_day.utilization float between 0.0 and 1.0, returned by an internal endpoint, and stacked with six other buckets the public docs never name. If you are hitting the weekly cap and you cannot tell which one tripped, this is why.
There is no single weekly cap number.
Anthropic publishes per-plan ranges in hours (Pro: 40 to 80h Sonnet; Max 5x: 140 to 280h Sonnet, 15 to 35h Opus; Max 20x: 240 to 480h Sonnet, 24 to 40h Opus, all per week, since 2025-08-28). The cap the server actually enforces is a utilization float (0.0 to 1.0) returned per bucket by /api/organizations/{org_uuid}/usage. There are at least three weekly buckets (seven_day, seven_day_sonnet, seven_day_opus) plus four sub-buckets in the same payload. "Hours" is a marketing label; the float is the contract.
Authoritative: Anthropic's rate-limits announcement and the live /api/organizations/{org_uuid}/usage endpoint your account already calls.
What Anthropic told you, in July 2025
Anthropic announced weekly rate limits on July 28, 2025 and rolled them out August 28, 2025. The framing was a per-plan range in hours of model time per week. Pro got 40 to 80 hours of Sonnet. Max 5x got 140 to 280 hours of Sonnet plus 15 to 35 hours of Opus. Max 20x got 240 to 480 hours of Sonnet plus 24 to 40 hours of Opus. Anthropic estimated fewer than 5 percent of subscribers would feel it. The press wrote it up as "hours per week" because that is what they were given.
The hours framing is convenient and wrong-shaped. It implies a stopwatch you can budget against. The cap is not a stopwatch. The cap is a continuous fraction the server keeps for you, weighted per message, and you do not see it directly anywhere on claude.ai. The settings page draws one bar (the 5-hour bucket) and a binary label that flips between "low" and "reset". Everything else is hidden behind a JSON payload.
What the server actually returns
When the settings page loads, your browser pulls /api/organizations/{your_org_uuid}/usage. That payload has the same shape ClaudeMeter polls. Every rolling bucket is a Window object with two fields: utilization (a float, sometimes 0 to 1, sometimes 0 to 100) and resets_at (an ISO-8601 UTC timestamp). The float is what blocks you. The timestamp is when it stops blocking you.
You can pull it yourself with curl and your existing session cookie. Here is what a real Pro account looked like on a Friday afternoon. The five-hour window was sitting at 42 percent, comfortable. The weekly Opus bucket, on the other hand, was at 83 percent and counting. Hours-used framing would have given you no warning.
Hours vs the float, side by side
Two different units for the same cap. One is for press releases. One is what your account is actually being measured against. Plan against the wrong one and Tuesday will surprise you.
| Feature | What Anthropic publishes | What the server enforces |
|---|---|---|
| Unit | Hours per week (e.g. 40 to 80h on Pro) | utilization float between 0.0 and 1.0 per bucket |
| Where it lives | anthropic.com news post and pricing page | /api/organizations/{org_uuid}/usage payload, every 60s |
| Number of weekly buckets | One ('the weekly cap') | Three named (seven_day, seven_day_sonnet, seven_day_opus) plus four sub-buckets |
| Stability of the conversion | Stated as a range, with no formula | Weighted per message; no public mapping from hours to float |
| Reset timing | Implied weekly, often described as a fixed day | Per-bucket resets_at ISO timestamp; rolling, not calendar |
| Visible to local-log tools (ccusage etc.) | No | Yes, via the live JSON payload |
The seven buckets you weren't told about
ClaudeMeter's Rust struct in src/models.rs lines 18 to 28 declares every bucket the live payload returns. Two of them are documented by Anthropic. Five more arrived quietly and are still emitted in every response.
Each one carries its own utilization float and its own resets_at. When you 429, the server does not name the bucket in the response body. The only way to know which ceiling you hit is to read the payload a moment later and find the field where utilization is at or past 1.0.
five_hour
The rolling 5-hour session window. Documented by Anthropic. Climbs fastest on weekday afternoons.
seven_day
The aggregate weekly cap. Documented. Rolling 168 hours from your first message of the cycle.
seven_day_sonnet
Sonnet-only weekly bucket. Not in public docs. Carries its own resets_at.
seven_day_opus
Opus-only weekly bucket. Not in public docs. Often gates Max 5x and Max 20x users first.
seven_day_oauth_apps
Weekly bucket for traffic via third-party OAuth integrations. Undocumented.
seven_day_omelette
Internal-codename weekly bucket that ships in the public payload. Undocumented. Exact semantics not published.
seven_day_cowork
Weekly bucket associated with shared workspaces. Undocumented.
The fair counterargument
Anthropic could fairly say that publishing a utilization float would confuse most users, and that the "hours" framing is a reasonable approximation for the median customer. That is probably true. Most Pro accounts in any given week sit at low utilization, never see 100 percent on any bucket, and would not benefit from a continuous percent. The 5-hour bucket is the one they bump into, and the binary label on settings is enough.
The argument fails for the population the cap was actually designed to slow down: Claude Code users running agentic loops on Max, researchers running batch analyses, and anyone whose workload includes Opus calls and tool use. For that group the float matters and the hours framing is misleading. The same payload that powers the binary label also contains the float. Surfacing it is one HTTP request per minute and a tiny bit of UI.
What to do about it
Read the JSON yourself.
Curl the endpoint with your claude.ai cookies and a referer of https://claude.ai/settings/usage. Pipe through jq to grab the four fields you care about. Free. No install. The downside is that you have to remember to do it, and the cap you are tracking moves every minute.
Run ClaudeMeter and let it poll.
One brew install, one browser-extension click, then your menu bar shows the worst weekly bucket as a live percent and the popup breaks out all four named buckets with their reset deltas. Polls once per minute via chrome.alarms in extension/background.js. MIT licensed. The Rust source is on GitHub. Same endpoint Anthropic's own page calls; nothing scraped.
Hitting the weekly cap mid-refactor and want a second pair of eyes?
Twenty minutes with the team to look at your /usage payload, figure out which bucket is gating you, and get ClaudeMeter set up so you stop being surprised.
Related guides
You have seven reset clocks, not one
Each of the seven weekly buckets carries its own resets_at. The one closest to 100 percent is the one blocking you. A single 'wait until Sunday' line is wrong for almost everyone.
Local counters vs server quota
ccusage reads tokens from disk. The cap is a server-side weighted utilization fraction. The two numbers can disagree by a wide margin and only the server's number gates you.
It is a 168-hour clock, not a calendar week
The seven-day bucket starts at your first message of the cycle. Heavy Sunday sessions land your cliff on Tuesday afternoon, and the resets_at timestamp tells you the exact minute.
Frequently asked questions
What does Claude Code's weekly cap actually count?
Not hours, despite the marketing. The server returns a utilization float between 0.0 and 1.0 (or sometimes 0 to 100) on each weekly bucket. The bucket called seven_day is your overall ceiling. seven_day_sonnet and seven_day_opus track Sonnet and Opus separately. Each one carries its own resets_at ISO timestamp. The 'hours per week' figures Anthropic published in July 2025 (Pro: 40 to 80h, Max 20x: 240 to 480h on Sonnet) are estimated upper and lower bounds for a typical workload, not a stable conversion. Two accounts at the same 'hours used' can sit at very different utilization fractions because the weighting depends on model class, attachments, tool calls, and time of day.
How many weekly buckets does the endpoint actually return?
Three named ones (seven_day, seven_day_sonnet, seven_day_opus) plus three more variants (seven_day_oauth_apps, seven_day_omelette, seven_day_cowork) on top of the five_hour bucket. ClaudeMeter's UsageResponse struct in src/models.rs lines 18-28 declares all of them as Option<Window> fields. Anthropic's own docs name only five_hour and seven_day. The other five quietly appeared in the JSON payload and are still emitted today.
Why do I hit the weekly cap on Tuesday when Anthropic said it covers a full seven days?
Because the seven-day bucket is rolling, not calendar. The window covers the trailing 168 hours from this exact moment, weighted by per-message compute. If you fired off a heavy refactor on Sunday afternoon, by Tuesday morning roughly 40 hours of charge is still inside the window. Combine that with the silent reweighting Anthropic shipped in early 2026 and the float climbs faster than the 'hours' framing suggests. The cap didn't shrink. The metric you can see (hours used) doesn't track the metric being enforced (utilization float).
Where is this float actually exposed?
GET https://claude.ai/api/organizations/{your_org_uuid}/usage with your existing claude.ai cookies. You will see seven Window-shaped fields, each with a utilization (a float) and a resets_at (an ISO timestamp). This is the same JSON the bar on claude.ai/settings/usage renders, but the page only draws one bar (five_hour) and prints a binary 'low' or 'reset' label for everything else. The full payload contains every weekly bucket. ClaudeMeter polls this endpoint every 60 seconds and shows all of them.
Doesn't ccusage already show my weekly usage?
ccusage reads ~/.claude/projects/*.jsonl and counts tokens. Tokens are not what the server is enforcing. The seven_day bucket on the server applies a weight to each message, and that weight depends on model class, attachments, tool calls, and weekday-peak multipliers that are not in your local logs. ccusage is excellent for token attribution per project. It is not a faithful proxy for seven_day.utilization. Run them together: ccusage tells you what you spent in tokens; ClaudeMeter tells you where that puts you against the server's actual ceiling.
Is the 'less than 5%' figure Anthropic gave still accurate?
Anthropic estimated less than 5% of subscribers would hit the weekly cap when they announced it on July 28, 2025. That figure was based on pre-rollout usage patterns. Reddit and the developer press logged a clear shift in early 2026: heavier weekday-peak weighting on the five_hour bucket, with the seven_day bucket holding its old curve. Whether 'less than 5%' still applies depends on what month and what hours you mostly code. The honest answer is that you can stop guessing by reading the float yourself.
Does the weekly cap reset all at once on a fixed day?
No. Each bucket carries its own resets_at, computed as the moment its oldest still-counted message will roll out of the window. As the rolling window slides, the timestamp slides too. ClaudeMeter polls every 60 seconds and renders the delta as 'in 12m', 'in 23h', or 'in 5d' depending on distance, via fmtResets in extension/popup.js lines 17-27. Two Pro users at identical utilization will have different resets_at values because their charging histories differ.
Can I check this without installing anything?
Yes. Open claude.ai, log in, open DevTools, copy your sessionKey cookie, and curl GET https://claude.ai/api/organizations/{org_uuid}/usage with a Cookie header and a Referer of https://claude.ai/settings/usage. Pipe through jq '{five_hour, seven_day, seven_day_sonnet, seven_day_opus} | with_entries(.value |= {utilization, resets_at})' and you will see the same numbers ClaudeMeter renders. ClaudeMeter just polls it every minute and saves you the cookie paste via the browser extension.
Will switching from Pro to Max push my Tuesday cliff later in the week?
It changes how much you can do before you hit the cliff, not when the cliff lands. The 168-hour rolling clock still starts at the first message of your cycle. A bigger seven_day allowance lets the utilization float climb to 0.7 instead of 0.95 on the same workload, but if your weekly usage doubles to fill the new headroom, the cliff lands at the same hour of the same day. To push the cliff later, push the start of your cycle later. Capacity moves the ceiling, not the clock.