Your Claude weekly limit and extra usage are linked by one boolean

When the 7-day bar pegs at 100%, three things can happen, and which one you get is decided by three values across two undocumented endpoints on claude.ai. The chain is short. Get it right and you know whether the next prompt waits, bills, or 429s. Get it wrong and you either burn metered dollars you did not plan for or wait for a window that already opened. This page walks the chain, shows the JSON at every state, and points at the open-source code that prints all three signals in one menu bar row.

M
Matthew Diakonov
11 min read

Direct answer (verified 2026-05-01)

When your Claude weekly limit hits 100%, extra usage takes over only if you opted in. Specifically: extra_usage.is_enabled must be true on GET /api/organizations/{org}/usage, and out_of_credits must be false on GET /api/organizations/{org}/overage_spend_limit. If both are met, the next prompt bills at standard API rates against your monthly_credit_limit. If either fails, you wait for the relevant resets_at timestamp. Anthropic confirms the opt-in mechanic on Manage extra usage for paid Claude plans; the field names and the BLOCKED state are in the open-source src/models.rs.

Three states, three menu bar outputs

The weekly bar at 100% is a single condition with three different downstream outcomes. Run the bundled CLI in each state and you get three different prints. Read them carefully, because the difference between “wait three days” and “keep coding, dollars ticking” is one row.

State A: weekly pegged, extra usage enabled, plenty of cap left. The fall-through is live; the dollar count is small; the next prompt bills, does not 429.

State A: fall-through live, cap healthy

State B: weekly pegged, extra usage was never enabled. There is no Extra usage row at all. The 7-day at 100% is the wall. The only remedy is the 7-day resets_at.

State B: hard stop on the weekly wall

State C: weekly pegged, extra usage enabled, cap exhausted. The dollar row is at 100% and carries a literal BLOCKED suffix plus a date. Both gates are closed; the next prompt 429s.

State C: both gates closed, BLOCKED until next cycle

The /usage payload, with the extra_usage block

One endpoint carries every rolling-window field plus the metered billing summary. Note the cents-on-the-wire convention; that one detail is the source of half the off-by-100 reports in scrapers built from scratch.

GET /api/organizations/{org_uuid}/usage

The extra_usage block is the cheaper read for “am I in fall-through right now” because it ships in the same response as the weekly bar. The dedicated /overage_spend_limit endpoint adds the BLOCKED diagnostics that this block does not have: disabled_reason, disabled_until, and out_of_credits.

The /overage_spend_limit payload, healthy and blocked

The healthy response. Cap is $50, $4.80 spent so far, no lockout, no reason. This is what State A reads.

GET /api/organizations/{org}/overage_spend_limit (healthy)

The blocked response. Three fields move at once: used_credits equals monthly_credit_limit, out_of_credits flips, and disabled_until carries the cap re-open timestamp. This is what State C reads.

GET /api/organizations/{org}/overage_spend_limit (blocked)

The 17 lines that turn the JSON into the BLOCKED row

The fall-through state machine on the rendering side is short. Two divisions by 100 to convert cents to dollars. One match arm for the no-cap case. One conditional suffix for the lockout date. One hardcoded uppercase string when out_of_credits flips. That is the entire renderer for the row that distinguishes State A from State C:

src/format.rs

Line 26 is the gate. The literal " BLOCKED" string (two leading spaces, all caps) is the only place in the codebase where the fall-through outcome is named in plain text. If you read it in the menu bar you are in State C; if you do not, you are in State A or State B depending on whether the row exists at all.

The decision tree, four reads

If you are wiring your own dashboard or just curling the endpoints by hand, here is the order to read fields in. ClaudeMeter does this on a 60 second tick; you can do it once when the next 429 lands.

1

Step 1: read seven_day.utilization on /usage

Pull /api/organizations/{org}/usage with your existing claude.ai cookies. The seven_day field is a Window with a utilization float and a resets_at ISO timestamp. If utilization is well under 1.0 you are in the included usage; nothing in this page applies yet.

2

Step 2: if seven_day at 1.0 or above, read extra_usage.is_enabled

Same response, the extra_usage block. is_enabled = false means hard stop. Wait for seven_day.resets_at to pass and the bucket clears. is_enabled = true means a fall-through is possible; proceed to step 3.

3

Step 3: read out_of_credits on /overage_spend_limit

Different endpoint, GET /api/organizations/{org}/overage_spend_limit. The same cookies work. out_of_credits = false and used_credits < monthly_credit_limit means you are still spending and the next prompt will bill against the cap. out_of_credits = true means BLOCKED; read disabled_reason and disabled_until to know why and when it lifts.

4

Step 4: take the right action

Hard stop on weekly with no extra usage: wait. Spending against cap: keep going (the dollars are real). BLOCKED on extra usage: raise monthly_credit_limit on Settings > Usage > Adjust limit, or wait for next_charge_date on subscription_details. ClaudeMeter renders all three signals in one menu bar dropdown so you do not have to walk this tree manually.

Six possible states, side by side

What the Settings page shows you vs what ClaudeMeter prints in the menu bar dropdown for each combination of weekly utilization and extra usage state.

Featureclaude.ai/settings/usageClaudeMeter (menu bar dropdown)
weekly < 100, extra_usage.is_enabled = falsePlain weekly tracking; no Extra usage row visible.Five rolling-window rows render, no Extra usage row, no BLOCKED string. Normal coding state.
weekly < 100, is_enabled = true, used < capSettings page shows the bar plus a small dollar figure.Extra usage row prints '$X.XX / $Y.YY (Z%)' with no suffix. Dollar count > 0 if any prior fall-through happened this cycle.
weekly = 100, is_enabled = falseHard stop, no message about how to keep going.7-day row at 100%, no Extra usage row, error log notes is_enabled=false. Wait for resets_at.
weekly = 100, is_enabled = true, used < capBar pegged but the chat keeps working; dollar figure ticks up silently.7-day row at 100%, Extra usage row prints '$X.XX / $Y.YY (Z%)' and Z% ticks every minute. The fall-through is live.
weekly = 100, is_enabled = true, used = capBLOCKED banner appears on /settings/usage; chat 429s with no inline summary.Extra usage row prints '$Y.YY / $Y.YY (100%) BLOCKED until <date>'. Both gates closed; the date is disabled_until.
out_of_credits = true even though used < capBLOCKED banner appears with a paragraph naming an admin or incident reason.Extra usage row prints percent < 100 plus ' BLOCKED' suffix. disabled_reason names the cause (admin_disabled, incident_pause, etc.).

Six invariants the fall-through chain holds

What you can rely on at every state

  • The fall-through is gated by extra_usage.is_enabled. Default for new accounts is false. The flip happens at Settings > Usage > Extra usage > Enable; nothing in the API turns it on automatically when a weekly bar hits 100.
  • Once enabled, monthly_credit_limit is the dollar ceiling. used_credits keeps climbing until it reaches monthly_credit_limit. Both ship in cents on the wire; divide by 100 to render dollars (src/format.rs lines 25 and 29).
  • out_of_credits = true is the BLOCKED signal. It flips when used_credits >= monthly_credit_limit OR when disabled_reason names an external cause (admin_disabled, incident_pause). The literal ' BLOCKED' string is two leading spaces and uppercase, hardcoded at src/format.rs line 26.
  • disabled_until carries the timestamp the metered cap re-opens. It is almost always next_charge_date on /api/organizations/{org}/subscription_details. ClaudeMeter formats it as ' until <Day Mon D>' and appends to the same line.
  • If /overage_spend_limit returns 404 (free workspace org, team org with metered billing off), no Extra usage row prints at all. Absence of the row is informative: it means absence of the feature, not a UI bug.
  • Even with extra usage enabled, the rolling 5-hour window can still spill into metered. The fall-through is keyed on the per-prompt rate decision, not on which window tripped. In practice the 7-day case is the one most users feel because the 5-hour resets in minutes to hours.

Why a menu bar row beats opening Settings

Three signals on three lines, refreshed every minute, no tab switch. The point of the row is that you read the answer without leaving your editor.

Read 1

seven_day.utilization on /usage. Tells you whether the wall is in front of you.

Read 2

extra_usage.is_enabled on /usage. Tells you whether the wall has a door.

Read 3

out_of_credits on /overage_spend_limit. Tells you whether the door is locked.

Common gotchas when the weekly bar hits

The most common surprise is that nothing happens automatically. Anthropic does not flip extra usage on for you when the weekly bar pegs; you opt in once on Settings > Usage > Extra usage > Enable, and from then on every weekly overrun spills into metered until you hit the cap or disable the toggle. People who think extra usage is the default and then sit blocked for three days are reading the help center wrong.

The second surprise is that the dollar count keeps climbing silently. The Settings page renders it but you do not see the page during a normal coding session. Without a menu bar row you find out from the next invoice. The cheapest way to avoid that is a tracker that polls /overage_spend_limit once a minute and prints used_credits live.

The third surprise is that the rolling 5-hour limit also falls through. If you are deep in an agentic Claude Code loop and spike the 5-hour bucket, your next prompt with extra usage enabled bills against the cap just like a 7-day overrun would. The fall-through is keyed on the per-prompt rate decision, not the window that tripped. Most users feel the dollar tick on the 7-day case because it lasts much longer than a 5-hour reset.

Install ClaudeMeter and watch all three signals at once

The product is free, MIT licensed, and reads the same endpoints the Settings page renders from. No API key, no cookie paste, no second login. Three steps from zero to a live menu bar row.

1

brew install the menu bar app

brew install --cask m13v/tap/claude-meter. The cask installs ClaudeMeter.app under /Applications and registers a launch agent so the menu bar icon comes back after reboot.

2

Load the unpacked browser extension

Clone github.com/m13v/claude-meter, open chrome://extensions (or arc://extensions, brave://extensions, edge://extensions), enable Developer mode, click Load unpacked, select the extension/ folder. The extension fetches /usage and /overage_spend_limit with your existing cookies and pushes snapshots to the menu bar over localhost:63762. No cookie paste, no second login.

3

Open the menu bar dropdown when the weekly bar hits

Click the ClaudeMeter icon. The 7-day row tells you the included usage is spent. The Extra usage row, if present, tells you whether you are spending or BLOCKED. If the row is absent your org has not enabled metered billing on /settings/usage.

The honest caveat

Both endpoints are undocumented. Anthropic can rename a field in any claude.ai release and the renderer will fall back to None on that field. The Rust struct in src/models.rs declares everything but is_enabled and out_of_credits as Optional, and ships #[serde(default)] on the boolean so a missing field deserializes as false. That is a forward-compat hedge, not a guarantee. If a field gets renamed, the open-source repo gets a same-day patch and you pull the next brew release. Worth it for the live BLOCKED line; the alternative is finding out from the next invoice.

Building a tracker that walks the weekly to extra-usage chain?

Send a 15 minute call. Happy to compare endpoint shapes, the BLOCKED diagnostic, and the moments the JSON shifts under us.

Frequently asked questions

If I hit my Claude weekly limit, does extra usage automatically kick in?

Only if you opted in. The /api/organizations/{org}/usage response carries an extra_usage block with an is_enabled boolean. If is_enabled is false (the default for fresh accounts) the weekly cap is a hard stop and you wait for the resets_at timestamp. If is_enabled is true, your next prompt is billed against your metered cap at standard API rates and the dollar figure on /settings/usage starts ticking. There is no automatic fall-through; you have to flip the toggle on Settings > Usage > Extra usage > Enable first.

Where exactly is the boolean that controls fall-through?

Two places. The first is the extra_usage.is_enabled flag on /api/organizations/{org}/usage (typed as ExtraUsage in src/models.rs lines 9 to 16 of the open-source ClaudeMeter source). The second is the is_enabled flag on the dedicated /api/organizations/{org}/overage_spend_limit endpoint (typed as OverageResponse in src/models.rs lines 30 to 40). Both should agree; if they disagree, the overage endpoint is authoritative because that is what the Settings page reads when it draws the BLOCKED banner.

I enabled extra usage and I am still getting rate-limited after the weekly bar hit. Why?

Three possibilities. First, your monthly credit limit is set to zero or near zero, so any spend trips it instantly. Read monthly_credit_limit on /overage_spend_limit (it ships in cents, divide by 100 for dollars). Second, used_credits already equals monthly_credit_limit because earlier sessions in this billing cycle ate the cap. Third, out_of_credits is true and disabled_until is in the future because Anthropic itself paused metered billing for your org (rare, but possible during incident windows). The literal BLOCKED string in the menu bar surfaces case three; cases one and two show as 100 percent on the dollar line without a BLOCKED suffix.

Can I just keep coding through the weekly limit if I have a credit card on file?

Not on its own. A card on file enables the metered billing capability; you still have to flip the Extra usage toggle. Once flipped, your card on file is what the cap is billed against at the end of the cycle. There is no usage gate for credits you have not pre-authorized: Anthropic does not charge per-prompt at the moment of overage, it accumulates the dollar count against monthly_credit_limit and bills the card on the next billing cycle (the next_charge_date field on /api/organizations/{org}/subscription_details).

How do I tell, from the JSON, whether I am about to be blocked?

Read three fields in this order. First, the worst utilization across five_hour and seven_day on /usage; if either is at or near 100 you are about to fall through. Second, extra_usage.is_enabled on /usage; if false, you will be blocked at the wall. Third, out_of_credits on /overage_spend_limit; if true, you are blocked even with extra usage enabled because the metered cap is hit. ClaudeMeter prints all three on consecutive rows so you read them top to bottom: 5-hour percent, 7-day percent, Extra usage dollars with the optional BLOCKED suffix.

What is the difference between a 100 percent weekly bar and the BLOCKED extra usage line?

Different fields, different states, different remedies. A 100 percent weekly bar means seven_day.utilization >= 1.0 on /usage, and the only remedy is waiting for seven_day.resets_at to pass. A BLOCKED extra usage line means out_of_credits = true on /overage_spend_limit, and the remedy is either raising monthly_credit_limit on Settings > Usage > Adjust limit, or waiting for the billing cycle to roll on next_charge_date. They can both be lit at the same time: weekly bar pegged, extra usage disabled or capped, you wait for whichever resets first.

If extra_usage.is_enabled is true, does the weekly bar still tick on /usage?

Yes, in our reading. seven_day.utilization keeps climbing past 1.0 (so you can see 1.04 or 1.12 in the JSON when you have spilled into metered) but the included usage is already exhausted. The bar in the popup clamps to 100 visually because the width style uses Math.min(100, v ?? 0) on extension/popup.js line 37; the underlying float is uncapped. The dollar figure on overage_spend_limit is the more useful number once you are in fall-through.

Is metered extra usage cheaper or more expensive than just upgrading to Max?

Depends on your cycle. Anthropic bills extra usage at standard API rates (no plan discount), so a heavy week of metered spend can match or exceed the price gap between Pro and Max 5x. The honest comparison is: read used_credits at the end of a typical cycle and compare to (Max plan price - Pro plan price). If the dollar count is consistently higher than the price differential, the upgrade pays back. ClaudeMeter shows the running used_credits live so you can build that comparison from your own real numbers, not Anthropic's example invoices.

Where does ccusage fit into this question?

ccusage reads ~/.claude/projects/<project>/<session>.jsonl and sums input plus output tokens per turn, then multiplies by the public model price card. That is a faithful local-token estimate for Claude Code traffic only, and it cannot see either of the endpoints this page is about. ccusage at $4 of estimated spend next to ClaudeMeter at $17 of metered used_credits is normal: ccusage measures local token cost, the server measures actual billing with peak-hour multipliers and per-model weights folded in. Run both for the full picture.

Does the rolling 5-hour limit fall through to extra usage too?

Yes, if extra usage is enabled. The fall-through is keyed on the per-prompt rate-limit decision, not on which window tripped, so a 5-hour overrun and a 7-day overrun both spill dollars into used_credits when is_enabled is true. The 5-hour case is much shorter-lived (the window resets in minutes to a few hours) so most users feel the dollar tick on the 7-day overrun. Practically: a 5-hour overrun on metered billing is rare unless you are in a runaway agentic loop; a 7-day overrun on metered billing is the common case Anthropic introduced extra usage to handle.

Can my org admin disable extra usage on me even if I want it?

On a personal Pro or Max account you control your own toggle. On a Team or Enterprise org, the admin owns the org-level extra usage cap and can disable it for the seat, in which case is_enabled returns false on /overage_spend_limit no matter what your personal preference is. The disabled_reason field on /overage_spend_limit names the cause when this happens (admin_disabled is the typical string). ClaudeMeter does not separately distinguish personal vs admin disablement; it surfaces the field as-is.