Claude Web Search: The App, the API, and Claude Code

Claude searches the web and cites its sources. That's true in three different places — the chat app, the API, and Claude Code — and they behave differently enough to be worth separating.

• In the Claude app, search is on by default and included on every plan, including Free.
• In the API, it's an explicit web_search tool you add to a request, billed per search on top of tokens.
• In Claude Code, it's a built-in tool the agent can call while working.

The one behaviour that surprises everyone: Claude decides when to search. You can't force a search from a chat prompt, and in the API you can only cap searches, not compel them.

When Claude searches, and when it doesn't

Search fires when the request depends on information that's current, changing, or outside training data:

• Recent events, news, announcements
• Prices, rates, scores, statistics
• Details about specific organisations, people, or products that may have changed
• An explicit "look this up"

It answers directly, without searching, for stable knowledge: established facts, maths, science, coding concepts, creative writing, analysis of material already in the conversation, and ordinary conversational turns.

This is why "why didn't Claude search?" usually has a boring answer — the model judged the question answerable from what it already knows. In the API you can nudge this through the system prompt, encouraging it to search more readily or prefer answering directly. What you get as a hard control is a ceiling, not a floor.

In the Claude app

Web search is available on Free, Pro, Max, Team, and Enterprise — see Anthropic's pricing page for what else separates the tiers. On Team and Enterprise it's gated behind an admin toggle, so if it's missing at work, that's the reason and your administrator is the fix.

Results come back with citations attached, which is the practical difference between this and asking a model to recall something. You can check the source.

Worth setting expectations: this is search in service of an answer, not a research product. If citation-first research is the job rather than a side effect, dedicated answer engines are built around it — we compared the field in Perplexity alternatives. Search also works the same way in the desktop app as on the web.

In the API: the web_search tool

Add it to the tools array and Claude handles the rest — deciding when to search, running the searches server-side, and returning a final answer with citations:

{
  "type": "web_search_20250305",
  "name": "web_search",
  "max_uses": 5
}

There are three versions of the tool, and the differences matter:

Dynamic filtering is the upgrade worth understanding. With basic search, every result is loaded into the context window whole, and most of it is irrelevant to your question. On web_search_20260209 and later, Claude instead writes and runs code that filters results before they reach the context. On search-heavy requests that's a straightforward reduction in token use, and it needs no extra setup — the API provisions the code execution it requires, at no charge beyond the tokens.

The catch is that a new tool version isn't sufficient on its own. Three things have to line up:

Miss any one of them and you're on basic search — or on an error. On web_search_20260209 and later the tool's allowed_callers defaults to ["code_execution_20260120"], because dynamic filtering runs web search from inside code execution. A model that doesn't support programmatic tool calling needs allowed_callers: ["direct"] set explicitly; without it the API returns a 400 telling you exactly that. So if you pin the newest tool version against an older model and get a 400 on your first call, this is why.

The parameters that matter

• max_uses caps searches per request. Simple factual queries typically use one to three; comparative or multi-entity research can use ten or more.
• allowed_domains or blocked_domains — one or the other, never both, or the request fails with a 400. Entries are bare domains with an optional path (example.com, example.com/blog), no scheme.
• user_location localises results. Supply at least one of city, region, country, or timezone.

Domain filtering is the underrated one. Pointing a research agent at a whitelist of primary sources does more for output quality than most prompt engineering.

Cost

Web search runs $10 per 1,000 searches on the Claude API, plus normal token costs for the content that search pulls in. Each search counts as one use regardless of how many results come back, and a search that errors isn't billed. Results retrieved during a conversation count as input tokens — both within a turn and on later turns.

That second clause is the one that quietly inflates bills. A long agentic conversation carries its accumulated search results forward as input tokens on every subsequent turn, which is precisely the problem dynamic filtering was built to reduce. Prices change; the tool documentation is the number to trust.

Citations, and the encrypted content rule

Citations are always on. Each one carries the source URL, title, and up to 150 characters of cited text — and those three fields don't count toward token usage, so there's no cost argument against showing your sources.

One implementation detail catches people building multi-turn apps: search results include an encrypted_content field, and you must pass the assistant's content blocks back exactly as received, that field included. Modify or drop it and the next request fails validation. The API decrypts it to restore the results into Claude's context.

Errors are the other quirk. A failed search still returns HTTP 200 — the failure is described inside the response body, with codes like max_uses_exceeded, too_many_requests, or query_too_long. If you're checking status codes to detect search failures, you won't find any.

Where it runs

Web search itself is available on the Claude API, Claude Platform on AWS, and Microsoft Foundry. Which versions you get depends on where the deployment lives:

The Foundry split is the one that bites, because "we're on Foundry" isn't a complete answer — an Azure-hosted deployment there is limited to web_search_20250305, while an Anthropic-hosted one supports every version. Amazon Bedrock doesn't support web search at all, which is worth knowing before you architect around it.

The table above describes Claude 4.6 and later. Claude Mythos Preview follows a different map: web search is supported on the Claude API, Google Cloud, and Microsoft Foundry, and is not available for Mythos Preview on Claude Platform on AWS or Amazon Bedrock. So "Claude Platform on AWS supports web search" is true of 4.6 and later and false of Mythos Preview — check the model and the platform together rather than either alone.

In Claude Code

Claude Code has web search as a built-in tool, so yes, it can search the web while working — reading current documentation for a library instead of relying on what it remembers.

If you're building on the Claude Agent SDK, naming it in allowed_tools pre-approves it so the agent searches without prompting:

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "WebSearch"],
    permission_mode="acceptEdits",
)

Note what this does not do. allowed_tools is an auto-approve list, not a whitelist. WebSearch is part of the default toolset, so leaving it out of the list doesn't remove it; search calls just fall through to permission_mode and your can_use_tool callback instead of running without a prompt. To take web tools away from the agent, use disallowed_tools=["WebSearch", "WebFetch"], which removes both tool definitions so Claude doesn't see them. Or pair your allow list with permission_mode="dontAsk", so anything not pre-approved is denied instead of prompting. Neither is a network sandbox: if Bash is still available, a curl command can still fetch a page, so deny or scope Bash too if network access is the real concern. For a coding agent, cutting web tools is often the right call — reproducibility beats freshness when you're editing code.

FAQ

Can Claude search the web?

Yes, on every plan including Free, with citations. Team and Enterprise require an administrator to enable it.

Can Claude Code search the web?

Yes — web search is one of its built-in tools. In the Agent SDK it's part of the default toolset: adding WebSearch to allowed_tools only pre-approves it so calls don't prompt, while disallowed_tools=["WebSearch"] is what removes it.

How much does the Claude web search API cost?

$10 per 1,000 searches plus standard token costs for the content retrieved. Errored searches aren't billed. Check the official tool documentation for current pricing.

Why doesn't Claude search when I ask it to?

Claude searches only when it judges the question to need current information. In the API you can steer this with the system prompt and cap it with max_uses, but there's no parameter that forces a search.

Can I restrict which sites Claude searches?

Yes, with allowed_domains or blocked_domains — one or the other, not both in the same request.

Does web search work on Amazon Bedrock?

No. It's supported on the Claude API, Claude Platform on AWS, and Microsoft Foundry, with basic search only on Google Cloud.

Why can't I get dynamic filtering to run?

Check all three requirements, not just the tool version: you need web_search_20260209 or later, a Claude 4.6 or later model (or Claude Mythos Preview), and a platform that supports it. On Microsoft Foundry that last one depends on the deployment — Anthropic-hosted supports every version, Azure-hosted is limited to basic search. On an older model, the newer tool versions need allowed_callers: ["direct"] or the request fails with a 400.

The short version

In the app, search is free and automatic. In the API, it's a tool you add, priced per search, with domain filters and citation data that make it genuinely useful for research agents — and dynamic filtering keeps long conversations affordable once your tool version, model, and platform all support it.

A research agent with domain filters and a sensible max_uses is a genuinely good thing to own — and almost nobody who reads a page like this ends up owning one, because the distance between understanding the parameters and having the thing running is where the idea dies. Taku closes that distance by making a working setup something you open rather than something you build. Taku is in Beta, and the Mac app is available now.