Rolling window vs metered billing on Claude: two parallel systems, not two stages
Half the threads on this confuse one for the other. They are not stages of one model. They are two different endpoints, two different units, two different reset clocks, two different opt-in states, and they run at the same time. The rolling window does not stop ticking when metered billing kicks in. Metered billing does not exist on your account until you flip a toggle. Here is what is actually happening in the JSON, the open-source Rust types both endpoints deserialize into, and the line-by-line difference.
Direct answer (verified 2026-05-05)
Two parallel systems, not two stages. The rolling window is a time-based quota: utilization floats on GET /api/organizations/{org}/usage with auto-reset clocks (5 hour and 7 day). It is automatic on every paid plan. Metered billing is an opt-in dollar cap on a separate endpoint GET /api/organizations/{org}/overage_spend_limit with cents on the wire and a out_of_credits boolean as the gate. Hitting the rolling window does not turn metered billing on; you must enable it once at Settings > Usage > Extra usage > Enable. After that, both run simultaneously. Anthropic confirms the opt-in mechanic on Manage extra usage for paid Claude plans; the field shapes are in the open-source src/models.rs.
Rolling window vs metered billing, field by field
The two systems share zero fields on the wire. Here is what each dimension actually looks like, sourced from the live JSON and the Rust types claude-meter deserializes them into.
| Feature | Metered billing | Rolling window |
|---|---|---|
| Unit on the wire | Dollar amounts in integer cents (i64) and fractional cents (f64). monthly_credit_limit and used_credits divided by 100 in src/format.rs to render dollars. | Utilization floats from 0.0 to 1.0 (sometimes also 0 to 100 inconsistently). Plus an ISO 8601 resets_at timestamp per bucket. |
| Endpoint | GET /api/organizations/{org_uuid}/overage_spend_limit. 404 for free or workspace orgs without metered billing enabled. | GET /api/organizations/{org_uuid}/usage. Returns for every paid org; the rolling window is plan-side, not opt-in. |
| Reset clock | Monthly billing cycle. used_credits zeros out on next_charge_date from /subscription_details. No interpolated countdown in the JSON. | Continuous rolling. 5-hour bucket resets in roughly 5 hours from your first message in the window; 7-day buckets reset 168 hours from a per-account start. resets_at is exact to the second. |
| Opt-in mechanic | Required. Settings > Usage > Extra usage > Enable. Default for new paid accounts is is_enabled = false. Anthropic does not flip it for you. | Automatic on every paid plan. No setting, no toggle. The /usage endpoint just returns the buckets your account has. |
| Failure mode | BLOCKED. out_of_credits = true on /overage_spend_limit when used_credits hits monthly_credit_limit, or when disabled_reason names an external pause (admin_disabled, incident_pause). Hardcoded literal ' BLOCKED' string in src/format.rs line 26. | 429. utilization >= 1.0 on a bucket means rate-limited until that bucket's resets_at. No boolean; you infer the gate from the float. |
| Number of distinct sub-fields | Six on /overage_spend_limit (is_enabled, monthly_credit_limit, currency, used_credits, disabled_reason, disabled_until, out_of_credits) plus a sub-block on /usage that mirrors four of them. | Seven Window structs: five_hour, seven_day, seven_day_sonnet, seven_day_opus, seven_day_oauth_apps, seven_day_omelette, seven_day_cowork. Each carries its own utilization and resets_at independently. |
| Behavior when the OTHER system trips | Only spends when a prompt would have 429'd on the rolling window AND is_enabled is true AND out_of_credits is false. Otherwise the dollar count stays at 0.0 even with extra usage enabled. | Keeps ticking past 1.0 in the underlying float even when metered billing is the active ledger. The popup clamps to 100 visually with Math.min(100, v) but the JSON is uncapped. |
The /usage payload: rolling window plus a metered summary
One endpoint carries every rolling-window utilization float plus a small extra_usage block that mirrors a few metered fields. The rolling window data is the primary product of this response. Watch seven_day in this snapshot: it is at 1.04, not capped at 1.0. The underlying counter does not stop just because the included usage ran out.
The extension popup runs the float through Math.min(100, v ?? 0) on extension/popup.js line 37 to clamp the visual bar at 100% width. That is purely cosmetic. The JSON is uncapped, and so is the menu bar percent string when you read it from the CLI.
The /overage_spend_limit payload: metered billing only
Different endpoint, different shape, different units. Same cookies. Cents on the wire, out_of_credits as the gate, no resets_at because the only relevant clock is the monthly billing cycle on /subscription_details. This is the second ledger; it is stored independently in claude-meter's snapshot struct and rendered as a separate row.
On free workspace orgs and team orgs without metered billing enabled, this endpoint returns 404. The /usage endpoint above keeps working. That asymmetry is the cleanest proof these are not two stages of one billing model: one of the two systems can be entirely absent on an account that still has the other.
Two struct types in the open-source source
claude-meter is MIT licensed Rust, and the cleanest way to see how parallel these systems are is to look at the types it deserializes the responses into. Window and OverageResponse share zero fields. The Window type carries time-bucket utilization; the OverageResponse carries dollars and a BLOCKED flag.
And the API client itself calls both endpoints in sequence, with separate error handling, in src/api.rs. Neither is a fallback for the other.
Both running at the same time, in one menu bar dropdown
The most concrete proof these are parallel systems is what the dropdown looks like when both are lit. Rolling window pegged at 100% on the 7-day, metered ledger spending dollars under the cap. The rolling window did not stop ticking; it climbed past 1.0 in the float (clamped at 100% in the print). The metered ledger started at 0 and walked up to $17.20.
Common confusions, side by side
The two views people walk in with, and the actual mechanic. Toggle to flip between them.
The rolling window is the free included usage on a Pro or Max plan. When you blow through it, metered billing takes over and the rolling window stops tracking you. They are two stages of the same billing model: included first, metered after.
- Rolling window stops once metered kicks in
- Metered is the next stage, not a separate system
- Hitting 100 percent on the weekly bar opens metered automatically
- One endpoint, one billing surface, two phases
Reading both systems by hand
If you are wiring a tracker yourself, here is the read order. Both endpoints take the same browser session cookies. claude-meter does this on a 60 second tick; you can do it once when the next 429 lands.
Read the rolling window first
Pull /api/organizations/{org}/usage with your existing claude.ai cookies. The five_hour and seven_day fields each carry a utilization float and a resets_at timestamp. Under 1.0 on both means you are still in included usage and metered billing is irrelevant. This is the only system that exists for free workspace orgs and orgs without metered billing turned on.
If a bucket pegs, check extra_usage.is_enabled in the same response
The extra_usage sub-block on /usage is the cheapest read for 'is the second system wired up?'. is_enabled = false means hard 429 at the wall, wait for resets_at. is_enabled = true means metered billing is configured and a fall-through is possible on the next prompt.
Read the dedicated metered endpoint for the BLOCKED gate
GET /api/organizations/{org}/overage_spend_limit, same cookies. out_of_credits = false plus used_credits < monthly_credit_limit means the next prompt bills metered. out_of_credits = true is the BLOCKED state; raise monthly_credit_limit on Settings > Usage > Adjust limit, or wait for next_charge_date on /subscription_details.
Render both rows, not just one
Both systems are running simultaneously. claude-meter prints the rolling window rows AND the Extra usage row in one menu bar dropdown so the parallel state is legible at a glance. If you build your own tracker, do not flatten the two into a single percent; readers need to see which clock each line is on.
The shortest mental model
Two systems. Different units. Different clocks. Different opt-ins. Both running.
Rolling window
Time-bucket utilization floats on /usage. Auto-resets every 5 hours and 7 days. Plan-side, no opt-in. Failure mode is a 429 until the bucket's resets_at passes.
Metered billing
Dollar cap (in cents) on /overage_spend_limit. Resets on monthly billing cycle. Opt-in only. Failure mode is out_of_credits = true until next_charge_date or the cap is raised.
Where this gets people in trouble
The most common surprise: assuming metered billing is the default. People hit the weekly wall, expect their card to pick up the slack, and sit blocked for three days because extra_usage.is_enabled is still false. Anthropic does not flip it for you. You opt in once at Settings > Usage > Extra usage > Enable; from then on overruns spill into metered until you hit the cap or disable the toggle.
The second surprise: assuming the rolling window stops once metered is the active ledger. It does not. The 7-day float keeps climbing, just clamped at 100% width in the popup so the bar looks pegged. The actual gate moved to out_of_credits on the other endpoint. If you only watch the rolling-window bar, you cannot tell whether your next prompt 429s or bills.
The third surprise: assuming used_credits and ccusage's estimate should match. They never will. ccusage measures local token cost (Claude Code on disk against the public price card). used_credits is server-side metered spend with peak-hour multipliers and per-model weights folded in. ccusage at $4 next to claude-meter at $17 of metered used_credits is normal because they are measuring different ledgers, on different sides of the network.
The honest caveat
Both endpoints are undocumented. Anthropic can rename a field in any claude.ai release; the open-source models declare every nullable field as Option and the boolean as #[serde(default)] so a missing field deserializes as false. That is a forward-compat hedge, not a guarantee. If a field is renamed, the repo gets a same-day patch and the next brew release picks it up. Worth it for the live BLOCKED line and the live 7-day percent in one menu bar dropdown; the alternative is opening Settings every 30 minutes and inferring the rest from invoices.
Building a tracker that watches both systems at once?
Send a 15 minute call. Happy to compare endpoint shapes, talk through the BLOCKED diagnostic, and the moments the JSON shifts under us.
Frequently asked questions
If I enable extra usage, does the rolling window stop tracking me?
No. The rolling 5-hour and 7-day buckets keep ticking on /api/organizations/{org}/usage no matter what. seven_day.utilization will climb past 1.0 once you spill into metered (we have seen 1.04 and 1.12 in the JSON) but the included usage is already gone, so what you are watching is just a counter, not a gate. The actual gate moved to a different field on a different endpoint: out_of_credits on /api/organizations/{org}/overage_spend_limit. Two parallel systems, both running. The popup clamps the visual bar with Math.min(100, v) for cosmetic reasons.
Are rolling window and metered billing the same thing with different names?
No. They share zero fields. The rolling window is utilization floats keyed by time bucket (five_hour, seven_day, plus per-model and per-app sub-buckets) with an ISO resets_at on each one. Metered billing is dollar amounts keyed by billing cycle (monthly_credit_limit, used_credits, both in cents on the wire) with disabled_until and out_of_credits as the gate. In claude-meter's source, they are even different Rust struct types: Window in src/models.rs lines 3-7 and OverageResponse at lines 30-40. They could not be more separate.
If the rolling window hits 100% and I have not enabled extra usage, what happens?
Hard 429. seven_day.utilization >= 1.0 with extra_usage.is_enabled = false means the only remedy is waiting for seven_day.resets_at to pass. There is no silent fall-through into metered. Anthropic does not flip the toggle for you. New paid accounts default to is_enabled = false, and you have to opt in once on Settings > Usage > Extra usage > Enable for the second system to be wired up at all.
If extra usage is enabled and I have not hit the rolling window yet, am I being billed metered?
No. Metered billing only spends when included usage is exhausted on the per-prompt rate decision. While five_hour and seven_day utilization are both well under 1.0, your prompts are billed against the plan and used_credits stays at 0.0. The two systems coexist in the JSON; only one of them is active for any given prompt at any moment.
How does claude.ai decide which ledger gets a given prompt?
By the per-prompt rate-limit decision, not by the window that tripped. If a prompt would have 429'd on either the 5-hour or the 7-day rolling window, and extra_usage.is_enabled is true and out_of_credits is false on /overage_spend_limit, the prompt bills metered. Otherwise it bills against the plan. We do not have an endpoint that says 'this prompt was metered'; the diagnostic you have is used_credits ticking up by some integer cents on the next poll.
Why are the metered numbers in cents?
It is the API convention. monthly_credit_limit is i64 cents, used_credits is f64 cents (Anthropic's own folded peak-hour multipliers and per-model weights produce fractional cents). claude-meter divides by 100.0 before printing dollars (src/format.rs lines 25 and 29). If you scrape the endpoint yourself and skip the division, you will see $50000.00 instead of $500.00 and assume the cap is sky-high.
Where exactly does the BLOCKED state live?
On the metered side only. out_of_credits = true on /overage_spend_limit is the BLOCKED signal. The rolling window has no equivalent boolean; you infer 'blocked' from utilization >= 1.0 and the resets_at timestamp not yet passed. So a 100% weekly bar is not the same kind of state as a BLOCKED extra usage line. One auto-resets in hours or days; the other is hardcoded in src/format.rs line 26 to render the literal string ' BLOCKED' until you raise the cap or wait for next_charge_date.
Does ccusage track either of these?
Neither. ccusage reads ~/.claude/projects/<project>/<session>.jsonl on disk and sums Claude Code tokens against the public model price card. That is a faithful local-token estimate but it never makes an HTTP call to claude.ai, so it cannot see /usage (rolling window) or /overage_spend_limit (metered billing). You can run ccusage at $4 of estimated spend while claude-meter shows $17 of metered used_credits and 92% on the 7-day rolling window; all three numbers are correct because they measure three different things.
Will Anthropic eventually merge them into one billing model?
No public roadmap. The April 2026 metered billing rollout (extra usage on Pro and Max 5x and Max 20x) added the second system on top of the first; it did not replace the rolling window. We watch /api/organizations/{org}/usage and /overage_spend_limit on every release for field renames; the structure has stayed parallel since the rollout. claude-meter's Rust models are the running record of what each endpoint looks like.
If I am on a workspace or team org with no metered billing, is there still a rolling window?
Yes. The rolling window is plan-side and ships in /usage for every paid org. The metered billing endpoint /overage_spend_limit returns 404 in that case and claude-meter's api.rs handles it (lines 31-45) by storing None in the snapshot and skipping the Extra usage row in the menu bar. So absence of the metered row is informative: it means the second system is not wired up for your org, not that you are healthy on it.
Keep reading
Claude weekly limit and extra usage: the fall-through chain, field by field
Once you understand the two parallel systems, the next question is what happens when both are lit at once. The decision tree across both endpoints, with the JSON at every state.
Claude extra usage balance: what the dollar line on /settings/usage actually is
Deep dive on the metered billing side: where the cents come from, why monthly_credit_limit lives on its own endpoint, and the 17 Rust lines that turn the JSON into the BLOCKED row.
The Claude rolling window cap is seven windows, not one
Deep dive on the rolling window side: the seven sub-buckets the /usage endpoint actually returns, why Settings shows two of them, and how a per-model bucket can cap you with the aggregate looking healthy.