How do I change Claude Code's WebSearch limit with `CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR`?

On Claude Code 2.1.290 or later, the interactive session's WebSearch budget refills over time instead of ending after 200 calls. The CHANGELOG gives the rate as 100 calls/hour. To change it, set CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR. Per the CHANGELOG, 0 turns the refill off. One catch: as of 2026-10-06, the official env-vars page and tools reference still describe a fixed 200-per-session cap set by CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION. Neither page has a row for the refill variable yet.

TL;DR: Variable CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR · CHANGELOG rate 100 calls/hour · 0 = refill off · floor 2.1.290 (take 2.1.291 for its regression fixes) · docs still say 200/session · how the old and new variables interact is [GAP]. Checked 2026-10-06.

What 2.1.290 changed

The Claude Code CHANGELOG entry for 2.1.290 reads:

Changed the interactive session's WebSearch budget to refill over time (100 calls/hour; CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR sets the rate, 0 turns it off) instead of ending after 200 calls

That bullet supports five facts, and no more:

• It's about the interactive session's WebSearch budget.
• The budget now refills over time.
• The stated rate is 100 calls/hour.
• CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR sets the rate, and 0 turns it off.
• It replaces the old behavior of ending after 200 calls.

For context, the old cap came from 2.1.212: "Added a session-wide limit on WebSearch tool calls (default 200, tunable via CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION) to stop runaway search loops." The 2.1.290 bullet doesn't mention that variable. The CHANGELOG doesn't date its entries, so the release day is [GAP]. Go by version number.

How to set CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR

Shell, before launching:

export CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR=50   # example only: accepted range unpublished, see caveats
claude

Settings file, using the generic env key. The env-vars page documents this for any variable, but not for this one by name:

{
  "env": {
    "CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR": "50"
  }
}

Use ~/.claude/settings.json for yourself, or managed settings to set it org-wide. Whether project .claude/settings.json may set this variable isn't documented [GAP]. The same release (2.1.290) stopped project settings from setting CLAUDE_CODE_DISABLE_ATTACHMENTS, so don't assume. Shell, user, or managed is the safe choice.

What the value means. The CHANGELOG says only that the variable "sets the rate" and that 0 turns it off. The variable name suggests a count per hour, matching the 100 calls/hour default. That's an inference, though. No accepted range, maximum, or format is published. Use whole numbers and don't expect anything to say if you go out of range.

Relaunch. The docs say settings env changes apply to a running session unless the feature reads its variables once at startup. They don't say which kind this is [GAP], so relaunch claude. Shell exports always need a relaunch.

Check claude --version. The variable first appears in the 2.1.290 entry. If you're on 2.1.290, 2.1.291 fixes a regression where cloud sessions could drop answers to permission prompts.

Docs still say 200: what to trust

As of 2026-10-06, 08:06 CEST:

Source	What it says
CHANGELOG 2.1.290	Budget refills (100 calls/hour). CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR sets the rate, and 0 turns it off. Replaces ending after 200
env-vars	CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION: "Cap on the total number of WebSearch calls one session can make (default: 200)". It takes a positive whole number, so the cap "can be raised but not turned off". No refill row
tools reference	"A session can make at most 200 WebSearch calls", counted across the main conversation and its subagents. /clear resets the count. No mention of refill

Our read: the CHANGELOG describes the shipped behavior, and the reference pages haven't caught up. What we don't know [GAP]:

• Whether CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION still does anything on 2.1.290+, or how it combines with the refill.
• What the budget does with refill set to 0, such as whether it goes back to a fixed cap.
• Whether the refill budget is still shared with subagents, and whether /clear still resets it.
• How non-interactive (-p) sessions are budgeted.

We won't guess. We'll update this page when the docs publish a row.

Not WebFetch, not structured outputs

• 0 here turns off the refill. It doesn't turn off WebSearch. The tools reference documents a bare WebSearch entry in permission deny as the way to block the tool.
• Turning off WebFetch is a different variable: How do I turn off WebFetch in Claude Code?
• Gateway errors on output_config are a different variable too: How do I turn off structured outputs in Claude Code?
• Claude in Chrome is a browser extension, not the WebSearch tool.

Pitfalls

• Expecting the docs to list the variable. They don't yet (2026-10-06).
• Setting it on a build older than 2.1.290. Nothing in the CHANGELOG says older builds read it.
• Reading 0 as "unlimited" or "WebSearch off." Per the CHANGELOG, it turns the refill off.
• Mixing it up with plan usage limits. The WebSearch budget counts tool calls. Your plan's usage limits are a separate thing (rate limits).
• Inventing a slash command. We found none for this budget.

FAQ

What's the exact variable name?

CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR, from CHANGELOG 2.1.290.

What's the default rate?

The CHANGELOG says 100 calls/hour.

How do I turn the refill off?

Set it to 0. What the budget does after that isn't documented.

Why do the docs still say 200?

They hadn't been updated as of 2026-10-06. The 200 figure and CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION describe the pre-2.1.290 cap.

Sources (checked 2026-10-06, 08:06 CEST)

• Claude Code CHANGELOG, entries 2.1.290 and 2.1.291 (latest entry at fetch: 2.1.291)
• Environment variables
• Tools reference, "Session search limit"

Related: Turn off WebFetch · Turn off structured outputs · Managed settings · Rate limits