Claude Max weekly quota enforcement is three gates, two endpoints, one BLOCKED string
Most articles on this describe one wall. The server actually enforces a Max plan through three gates in sequence. Two of them live on /api/organizations/{org}/usage. The third lives on a separate endpoint, /api/organizations/{org}/overage_spend_limit, and only fires if you turned metered billing on. This page walks all three with the exact field that flips at each gate.
Direct answer (verified 2026-05-04)
Anthropic enforces the Claude Max weekly quota through three sequential server-side gates. Gate 1: five_hour.utilization >= 1.0 on the usage endpoint. Gate 2: seven_day.utilization >= 1.0 on the same endpoint. Gate 3: out_of_credits == true on /api/organizations/{org}/overage_spend_limit, only if your workspace has metered billing turned on. Each gate returns a resets_at (or disabled_until) timestamp you can read before it fires. The free open-source way to watch all three live is ClaudeMeter, source verified at src/models.rs. Authoritative dashboard: claude.ai/settings/usage.
The three gates, in order
On a Max plan with metered billing enabled, every prompt goes through three checks in sequence. If any one of them rejects, the prompt is rejected. Most online guides describe Gate 2 only, because that is the one users name “the weekly limit.” Gates 1 and 3 are the silent ones; Gate 1 hits earliest in a heavy session, Gate 3 is the one that sneaks up when both rolling windows look green.
Gate 1: the 5-hour rolling window
five_hour.utilization climbs from 0 to 1.0 across the rolling 5 hours since your first message of the window. The cap is reached when the float crosses 1.0 (or 100 if the server shipped the 0-100 scale). Anthropic returns 429 on the next prompt and quotes the resets_at timestamp on /settings/usage. This gate hits Max users running tight Claude Code agentic loops first; you can ride it out without losing weekly quota.
Gate 2: the 7-day weekly bucket
seven_day.utilization is the cumulative spend across the rolling 168-hour window. It does not reset when 5-hour resets; the two clocks are independent. Reaching seven_day.utilization >= 1.0 is the gate most people mean when they say 'weekly limit reached.' On Max it can hit by Tuesday on a heavy refactor week. The endpoint also returns seven_day_sonnet and seven_day_opus, so you can see which model carried the spend.
Gate 3: metered billing cap (only if enabled)
If your Max workspace has metered billing turned on, blowing past Gate 2 hands off to a pay-as-you-go cap on /api/organizations/{org}/overage_spend_limit. used_credits ticks up against monthly_credit_limit (both in cents). When used_credits hits the cap, out_of_credits flips to true and disabled_until carries the cycle-boundary timestamp. The rolling windows can look green during this state. The boolean is the only single-field signal that the cap is enforcing right now.
Gate 1: 5-hour at the cap
The 5-hour bucket is the fastest-moving counter. On a tight Claude Code agentic loop with Sonnet, you can cross five_hour.utilization in a couple of hours. The endpoint returns the float; ClaudeMeter normalizes 0-1 vs 0-100 scale (both are shipped in the same payload) and renders the row.
The good news at this gate: the 7-day bucket is barely touched. Sit out the 2 hours, five_hour.resets_at ticks over, and you keep the rest of the weekly cycle. The bad news: a Max user who is paying for the plan because they want unbounded throughput sees this as their main day-to-day enforcement boundary. The menu bar shows the percent climbing on every poll, so you know whether you have time to start one more big task.
Gate 2: 7-day at the cap
Cross seven_day.utilization >= 1.0 and you are out for the rest of the rolling 168 hours. The clock started with your first message of the cycle, not at calendar midnight, so “week” here means literally 7 times 24 hours from message zero. The reset timestamp lives at seven_day.resets_at on the same response.
The 5-hour row being green and the 7-day row being hot is the tell-tale shape of Gate 2. People misread this as a 5-hour issue (“but I just reset!”); the percent column makes it obvious that the weekly counter is the one carrying the gate. The per-model rows (seven_day_sonnet, seven_day_opus) tell you which model carried the spend. Heavy Opus users with tight reasoning loops usually see seven_day_opus near the cap before the all-up row.
Gate 3: metered cap, the silent one
This is the gate that catches people. On Max with metered billing turned on, going past Gate 2 hands off to a pay-as-you-go cap. Your rolling windows reset on their normal cadence, but used_credits ticks up against monthly_credit_limit on a separate endpoint. When that hits 100 percent, out_of_credits flips to true and the next prompt 429s with both rolling windows looking green.
The shape is the trap: 5-hour green at 37 percent, 7-day green at 62 percent, and you cannot send. The Extra usage row carries a BLOCKED until <date> suffix because disabled_until is set on the response. claude.ai/settings/usage shows a banner above the bars; the menu bar shows the same fact in one row, beside the rolling windows it does not blame.
The schema each gate sources from
Two endpoints. Two structs. The boolean that flips at Gate 3 lives on the second one. The rolling-window utilizations that flip at Gates 1 and 2 live on the first.
And the dedicated billing-state endpoint:
The diff between the two is what makes Gate 3 invisible to anyone reading only the usage endpoint: disabled_reason, disabled_until, and out_of_credits ship only on /overage_spend_limit. If you are building a tracker on the usage endpoint alone, you have no way to render the BLOCKED state.
Two endpoints feed one snapshot
Both calls go out per poll, both with your existing claude.ai cookies, and the merge happens client-side.
Two GETs, one snapshot, three surfaces
Whichever surface you read, you read the same merged UsageSnapshot. The merge step is the only place all three gates appear in the same struct.
The fetch loop that pulls both
Sequential, both with cookie auth, both wrapped in match arms so a missing endpoint surfaces a warning instead of a panic. The order matters: usage is required (Gates 1 and 2), overage is optional (Gate 3, free orgs 404).
The same pattern lives in the browser extension at extension/background.js line 22-30, with credentials: ‘include’ on the fetch. That is what makes the “no manual cookie paste” bit work: the extension already has the claude.ai cookies because the browser is already logged in. The Rust side re-uses them by reading the browser cookie store.
Gate 1+2 endpoint vs Gate 3 endpoint
Same auth, same poll cadence, different fields, different reset clocks. The right column is the one most articles never mention.
| Feature | overage_spend_limit (Gate 3) | usage endpoint (Gates 1 + 2) |
|---|---|---|
| Endpoint | /api/organizations/{org}/overage_spend_limit | /api/organizations/{org}/usage |
| Required for Max plan? | Only if metered billing is enabled (404 otherwise) | Yes (always returned) |
| Gate signal | out_of_credits == true | five_hour.utilization >= 1.0 OR seven_day.utilization >= 1.0 |
| Reset field | disabled_until (ISO 8601) | five_hour.resets_at / seven_day.resets_at (ISO 8601) |
| Reset cadence | Billing cycle boundary | 5h rolling / 168h rolling from first message |
| Visible on /settings/usage? | Yes, as a BLOCKED banner with prose | Yes, as two progress bars |
| Visible to local-log tools (ccusage)? | No (no HTTP call to claude.ai) | No (no HTTP call to claude.ai) |
| Polled by ClaudeMeter | Every 60 seconds, same loop | Every 60 seconds (POLL_MINUTES = 1) |
How to identify which gate is enforcing right now
A 6-step read of the menu bar dropdown
- Open the menu bar dropdown. Look at the percent column. The row at or above 100 percent is the active gate. If two rows are above 100, the slowest reset wins.
- If 5-hour is hot and 7-day is green, you are at Gate 1. Wait until five_hour.resets_at. The 7-day bucket is intact when you come back.
- If 7-day is hot and 5-hour is green or recently reset, you are at Gate 2. Wait until seven_day.resets_at. New work counts against the next weekly cycle.
- If both windows are green and the next prompt still 429s, scroll to the Extra usage row. A BLOCKED suffix and a 'until <date>' tail mean Gate 3 fired. The rolling windows are not the cause; metered billing is.
- If you do not see an Extra usage row at all, your org does not have metered billing turned on. The 7-day bucket is the hardest gate you can hit. Plan around seven_day.resets_at, not a dollar cap that does not exist.
- If two rows look near the cap at the same time and you cannot tell which one will fire next, watch the slope between two 60-second polls. The faster-climbing percent is the gate that will hit first; the slower one stays a warning.
The numbers behind the boundary
All readable straight from the source repo. Nothing invented.
Why local-log tools cannot show enforcement
ccusage and Claude-Code-Usage-Monitor read ~/.claude/projects/<project>/<session>.jsonl and sum input + output tokens against the public model price card. Useful, faithful, and entirely local-truth. None of those token counts carry the bucket Anthropic charged the request to, the peak-hour multiplier the server applied, or the metered-billing flag that flips at Gate 3. There is no HTTP call to claude.ai in either tool, so there is no way for them to read out_of_credits. They were not built for this; that is fine. But on a Max plan the enforcement boundary is server-side, and only a server-truth reader can show you what is currently blocking.
Run them side by side. ccusage tells you what tokens you spent locally; ClaudeMeter tells you which gate the server is enforcing. The two ledgers are complementary; the numbers do not match because they measure different things.
Verify the schema yourself
The endpoints are undocumented. The way to confirm is to open DevTools on claude.ai/settings/usage, filter the Network tab on usage, and read the JSON response. The two requests you care about are GET /api/organizations/{org_uuid}/usage and GET /api/organizations/{org_uuid}/overage_spend_limit. The first should match UsageResponse field-for-field. The second should match OverageResponse field-for-field, including the three Gate 3 fields. If the wire shape ever shifts, the open-source repo is the lagging side and you can open an issue at github.com/m13v/claude-meter.
Install and start watching
Install the menu bar app
brew install --cask m13v/tap/claude-meter. Cask installs ClaudeMeter.app under /Applications and registers a launch agent so the menu bar icon comes back after reboot. CLI lives at /Applications/ClaudeMeter.app/Contents/MacOS/claude-meter.
Load the browser extension
Clone github.com/m13v/claude-meter, open chrome://extensions (or arc://, brave://, edge://), enable Developer mode, click 'Load unpacked', pick the extension/ folder. The extension makes the cookie-authenticated GETs against claude.ai with credentials: 'include'. No manual cookie paste.
Visit claude.ai once
Sign in to claude.ai if you are not already. The extension reads your session cookie and starts polling /api/organizations/{org}/usage and /api/organizations/{org}/overage_spend_limit on a 60-second tick. The badge lights up within one minute.
Watch which row carries the gate
Three rows in the dropdown: 5-hour, 7-day, Extra usage. Whichever one tips into BLOCKED state first is the gate enforcing right now. The others are warnings.
Hitting an enforcement gate and want a second pair of eyes on the JSON?
Book a 15 minute call. Happy to walk through which gate is firing, the field that flipped, and what the resets_at is telling you.
Frequently asked questions
How does Anthropic actually enforce the Claude Max weekly quota?
Through three sequential server-side gates. Gate 1 is five_hour.utilization on /api/organizations/{org_uuid}/usage; once it reaches 100 percent, claude.ai rejects the next message until five_hour.resets_at. Gate 2 is seven_day.utilization on the same endpoint; same rejection rule, but the reset clock is 168 hours from your first message of the cycle. Gate 3 is the metered-billing cap on /api/organizations/{org_uuid}/overage_spend_limit, surfaced as out_of_credits: true and a disabled_until timestamp. A Max user who has metered billing enabled walks through all three. A Max user without metered billing stops at Gate 2 and waits until seven_day.resets_at. ClaudeMeter polls both endpoints every 60 seconds and renders the active gate as a row in the menu bar.
Where do I see which gate is currently blocking me?
In the menu bar dropdown, the row whose percent is at or above 100 is the active gate. If 5-hour is hot and 7-day is green, it is Gate 1; sit out until the 5-hour reset and you keep your weekly bucket. If 7-day is hot and 5-hour just reset, Gate 2 fired; you wait until seven_day.resets_at, which the popup shows in days/hours. If both windows look green and the next prompt still 429s, scroll to the Extra usage row: a BLOCKED suffix means Gate 3 fired, and you wait until disabled_until. The prose on claude.ai/settings/usage does not separate the three; the menu bar does because each gate has its own row.
Why is Gate 3 a separate endpoint from Gates 1 and 2?
Because Gate 3 is a billing state, not a usage state. /api/organizations/{org}/usage carries the rolling-window utilization fractions for the plan limits Anthropic enforces by default. /api/organizations/{org}/overage_spend_limit carries the metered-billing cap, which only matters once the plan limits are spent and the user has chosen to pay-as-you-go past them. The two responses overlap on a few fields (used_credits, monthly_credit_limit) and diverge on three (out_of_credits, disabled_reason, disabled_until). A free workspace org or a Max account without metered billing turned on returns 404 on overage_spend_limit; the rolling-window endpoint still returns the two windows. ClaudeMeter wraps the overage call in try/catch (extension/background.js line 26-27, src/api.rs lines 31-45) and falls through cleanly when the endpoint is missing.
What does the request that hits the enforcement boundary look like?
From the server's perspective the enforcement is a precondition check before message generation. When utilization on the relevant bucket is at or above 1.0 (or out_of_credits is true on the overage response), claude.ai short-circuits the request with an HTTP 429 and a JSON body explaining which limit was hit. The check runs on every prompt, so the boundary is real-time, not eventually-consistent. ClaudeMeter does not see the 429 itself (it polls usage; it does not send chat prompts), but the moment the gate flips, the next 60-second poll lights up the row. That is the practical refresh rate of the boundary from a user's point of view.
Why can't ccusage or Claude-Code-Usage-Monitor show the enforcement state?
Because they read ~/.claude/projects/<project>/<session>.jsonl on disk and sum input/output tokens against the model price card. That is local truth: the tokens you sent and received from your machine. Enforcement is server truth: which bucket Anthropic charged the request to, what fraction of the cap that landed at, whether out_of_credits flipped. The local logs do not contain bucket-state, peak-hour multipliers, or metered-billing flags. Only the cookie-authenticated calls to /api/organizations/{org}/usage and /api/organizations/{org}/overage_spend_limit carry that. ClaudeMeter is the open-source tracker that fetches both with your existing claude.ai cookies through a browser extension, so there is no manual cookie paste.
What is the exact reset cadence for each gate?
Gate 1 (five_hour) resets 5 hours after your first message of the rolling window. The endpoint returns five_hour.resets_at as an ISO 8601 timestamp; the popup formats it as a relative duration (m / h / d). Gate 2 (seven_day) resets 168 hours after your first message of the cycle, returned as seven_day.resets_at on the same response. Gate 3 (overage_spend_limit) resets on your billing cycle boundary, returned as disabled_until on the overage response when out_of_credits is true. The clocks are independent: a fresh 5-hour reset does not push the seven_day reset, and a billing-cycle rollover does not move the rolling windows.
Can I see the enforcement timestamp before it fires?
Yes. Both endpoints return the resets_at field whether or not the bucket is at the cap. So at 62 percent on five_hour you can see the eventual reset, plan around it, and decide if a heavy refactor is worth crossing the gate. ClaudeMeter formats that timestamp on every row: the popup shows 'in 4h' or 'in 3d 15h' or 'now' next to the percent bar, and the dropdown title says '7d: 81%' so you can hover the icon and read the slow-moving gate without clicking. The forward-look is the part claude.ai/settings/usage hides behind a vague 'usage will reset at' label.
How fast does the menu bar pick up that a gate just flipped?
Within 60 seconds. extension/background.js line 3 sets POLL_MINUTES = 1, and chrome.alarms.create('refresh', { periodInMinutes: 1 }) ticks at minute boundaries. The Rust side mirrors that: src/main.rs schedules the same 60-second cadence. So the worst-case latency between a gate flipping on the server and the menu bar showing it is one poll. Anthropic's own /settings/usage page also recomputes against the same cadence, so the two stay in lockstep without a busy-loop on the endpoint.
Is there an HTTP signal I can read directly when a request gets enforced?
Yes, but you have to be in the chat path to see it. Sending a prompt to /api/organizations/{org}/chat_conversations/{id}/completion when the active gate is at the cap returns HTTP 429 with a JSON error body that names the limit. That signal is observable in DevTools while you chat. The trade-off is that you only learn about enforcement when you try to send and bounce. Polling the usage and overage_spend_limit endpoints (no chat path needed, no prompt cost) is the cheaper read because you watch the gauge approach 100 percent rather than discovering it the hard way.
Is the endpoint stable? Can the field names change?
The endpoints are undocumented and Anthropic-internal. They power claude.ai/settings/usage. Field names can change in any release. ClaudeMeter deserializes into explicit Rust structs (UsageResponse, OverageResponse in src/models.rs), so a schema change surfaces as a parse error rather than silent corruption. The seven bucket names on /usage (five_hour, seven_day, seven_day_sonnet, seven_day_opus, seven_day_oauth_apps, seven_day_omelette, seven_day_cowork) and the seven fields on /overage_spend_limit (is_enabled, monthly_credit_limit, used_credits, currency, disabled_reason, disabled_until, out_of_credits) were stable through 2026-05-04. The repo is open-source MIT, so a same-day patch lands when the wire shifts and you pull the next brew release.
Where is the canonical authoritative source for what these fields mean?
There is none from Anthropic; the endpoints are internal. The closest thing to a canonical source is the open-source Rust struct in src/models.rs at github.com/m13v/claude-meter, which is reverse-engineered from the live JSON the Settings page renders against. Verify by opening DevTools on claude.ai/settings/usage, copying the response of /api/organizations/{org}/overage_spend_limit, and matching it against the OverageResponse struct. If the two diverge, the repo is the lagging side and lands a patch within a release cycle.
Keep reading
Claude extra usage balance: the dollar line on /settings/usage
What used_credits / monthly_credit_limit and the BLOCKED suffix actually mean, line by line.
Claude weekly limit by Tuesday: it's a 168-hour clock
The seven_day bucket starts at your first message and ends 168 hours later, not Sunday at midnight.
Claude Max weekly quota tightening: the 5-hour decay shifted
The change everyone calls a weekly tightening is actually a 5-hour bucket weight change. Endpoint proof.