# How Claude web search works

Published: 16 November 2026
Updated: 20 November 2026
Author: Omar Trkzi
URL: https://omartrkzi.com/blog/how-claude-web-search-works

> Claude Code's WebSearch is a server tool: Anthropic runs the search, returns titles, URLs and encrypted results, and charges $10 per 1,000 searches.

**In short: **Claude Code's WebSearch sends a plain-language query to a search tool that Anthropic runs on its own servers, which can run up to eight searches per call and returns only titles and URLs. Claude reads a page with a separate WebFetch call, the results come back encrypted, and the API charges $10 per 1,000 searches.

Lately I've been running Claude Opus on medium effort for almost everything. It's good enough for most of what I throw at it, and it's fast enough that I split one topic into several tasks and send each to its own session. It can range from a couple to a dozen of terminals side by side, and I'll admit I get some pride watching Claude clauding through the clauded tasks.

![Tmux Terminal splitting multiple claude CLI sessions](https://cdn.sanity.io/images/r7fauxgo/production/08450417ea3669eeda7e366736bd493ebc0bc2a2-2996x1904.png?w=1360)

If you use the CLI too, you've seen the tool calls. One of them is `WebSearch`, and the queries in it are quite intriguing: oddly specific, sometimes phrased like a question a person would ask. It's clearly not a regex. So what is that parameter, and what happens after Claude writes it?

## What does Claude send when it searches the web?

Well, it's just a (human) sentence. Claude writes it the way you'd type into a Google search box (ah, the good ol' days), and it's not parsed on your machine. From Claude Code's tools reference:

> "WebSearch runs a query against Anthropic's web search backend and returns result titles and URLs. It doesn't fetch the result pages." ([Claude Code docs](https://code.claude.com/docs/en/tools-reference))

First, one `WebSearch` call "may issue up to eight backend searches per call, refining the search internally before returning results." The query you see is only the start of the search. Second, it only returns titles and URLs!! When you see `WebFetch` right after a search, that's Claude opening one of the results to actually read it.

![Claude Code Web Search calls](https://cdn.sanity.io/images/r7fauxgo/production/ba0b8045126c15e40cdcef7c9af5c5c5b7adcfb1-1412x466.png?w=1360)

So what is "Anthropic's web search backend", and where does the search run?

## Where does Claude's web search actually run?

Claude Code's `WebSearch` sits on top of the [web search tool in Anthropic's API](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool), and that tool works differently from most tools.

With a normal tool, which Anthropic calls a client tool, Claude returns a `tool_use` block, your code runs the tool, and you send back a `tool_result`. Web search is a server tool: Anthropic runs it. You turn it on with one entry in your request:

```json
"tools": [{ "type": "web_search_20250305", "name": "web_search" }]
```

From there the docs describe three steps. Claude decides whether to search based on the prompt. The API runs the search and hands Claude the results, and this "can repeat multiple times throughout a single request." Then Claude writes its answer with cited sources. You never execute anything and you never send a result back. You only see what happened, after the fact, in the response.

![client tool vs server tool](https://cdn.sanity.io/images/r7fauxgo/production/d02440a08d6cfbf8ee4587fd22387c801c3d3bee-2540x1100.png?w=1360)

Claude doesn't search for everything. The docs list when it does: recent events, current prices and scores, facts about people or companies that may have changed, or when you ask it to look something up. Stable facts, math and coding concepts it answers from memory. You can nudge that (a bit) with the system prompt and cap it with `max_uses`.

A trimmed response looks like this:

```json
[
  { "type": "text", "text": "I'll search for when Claude Shannon was born." },
  { "type": "server_tool_use", "id": "srvtoolu_01WYG3...",
    "name": "web_search", "input": { "query": "claude shannon birth date" } },
  { "type": "web_search_tool_result", "tool_use_id": "srvtoolu_01WYG3...",
    "content": [{ "type": "web_search_result",
      "url": "https://en.wikipedia.org/wiki/Claude_Shannon",
      "title": "Claude Shannon - Wikipedia",
      "encrypted_content": "EqgfCioIARgB...", "page_age": "April 30, 2025" }] },
  { "type": "text", "text": "Claude Shannon was born on April 30, 1916...",
    "citations": [{ "type": "web_search_result_location",
      "url": "https://en.wikipedia.org/wiki/Claude_Shannon",
      "cited_text": "Claude Elwood Shannon (April 30, 1916 – February 24, 2001)..." }] }
]
```

There's the query again: `"claude shannon birth date"`, a sentence Claude wrote. The ID starts with `srvtoolu_`, which is how you tell a server call from a client one. Each citation carries up to 150 characters of the text it relies on, and those citation fields don't count toward your token usage.

![Quote from Simon Willison's blog](https://cdn.sanity.io/images/r7fauxgo/production/0cdab27499dbb64be9d0e545b972f50c589060f4-1132x152.png?w=1360)

Which search engine sits behind it? Anthropic's docs don't say. When the tool launched in May 2025, Simon Willison wrote that it's ["presumably still powered by Brave"](https://simonwillison.net/2025/May/7/anthropic-api-search/), the provider behind Claude's consumer search.

## Why are the results encrypted, and why do errors return 200? 🧐

Three things in particular in the docs are, ummm, "interesting" 👀.

The first is that the results are **encrypted**. Each result comes with an `encrypted_content` field, and each citation with an `encrypted_index`. To continue the conversation, you send them back exactly as you got them, and the API **decrypts** them to put the results back in Claude's context. If they're missing or modified, the request fails with a **400**. You're holding the search results the whole time, **but** you can't read them.

The second: errors come back as a **200 !!!** If a search hits a rate limit or runs out of uses, the HTTP response still **succeeds**. The error sits inside the **result** block, as `web_search_tool_result_error` with a code like `max_uses_exceeded` or `too_many_requests`. A search that finds nothing returns an empty list, not an error. If your code only checks the status code, it will miss all of this.

The third is that Claude now filters its own results. Basic search loads every result into Claude's context, relevant or not. Since version `web_search_20260209`, in Anthropic's words, Claude can ["write and execute code during web searches to filter results before they reach the context window"](https://claude.com/blog/improved-web-search-with-dynamic-filtering). The search runs from inside a code execution sandbox that the API sets up on its own, and only what the code keeps reaches the model.

![basic vs dynamic filtering](https://cdn.sanity.io/images/r7fauxgo/production/25bab63ad1ac2f06e10d498a462829a3fd98faa0-1680x880.png?w=1360)

Anthropic's numbers from February: on BrowseComp, Opus 4.6 went from 45.3% to 61.6%. Across their two benchmarks, filtering averaged an 11% gain while using 24% fewer input tokens. The same post notes that for Opus 4.6 the cost went up, so whether it saves money depends on the workload.

If you build with it, also know that long searches can stop with `stop_reason: "pause_turn"`. You continue by sending the paused message back unchanged. Nothing is lost, but you have to handle it.

## How much does Claude web search cost? 💸

- Price: $10 per 1,000 searches, plus tokens
- Failed searches: not billed
- Searches per `WebSearch` call in Claude Code: up to 8
- Claude Code session cap: 200 calls, refills about 100 per hour
- Not available on: Amazon Bedrock

One cent per search sounds like nothing, and mostly it is. The bigger cost is quieter: search results count as input tokens, in the turn where they arrive and in every later turn of the conversation. A research session that searches a lot gets more expensive with each message, which is a good argument for the filtering above.

The session cap is the one I'd actually hit. Searches from subagents count against the same 200, so one session that fans out to many subagents burns through it fast. You can raise it with `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION`.

## Takeaways

What I take from all this: the query is actually the least interesting part 😂. It's the first line of a small research loop that runs on "someone else's servers". Claude writes a "human" sentence, searches, reads the titles, (maybe) searches again, opens a page, and (now) even writes code to throw away garbage, and all we see is one line in the terminal 😌.
