What Is the Claude Web Search API? A Practical Guide for Developers

TLDR: Anthropic's web search capability is a server-side tool you attach to a Claude Messages API request, versioned today as web_search_20260318, which lets Claude decide when to search, filter results, and answer with citations, billed at $10 per 1,000 searches plus token costs (Anthropic documentation, fetched 2026-09-17). It is the right tool when Claude itself should reason over current web content, and the wrong tool when your application needs raw search results it can rank, cache, or hand to a different model. This guide covers the request shape, the domain and location controls, dynamic filtering, cost mechanics, and the failure mode to test for.

What is the Claude web search API? It is a tool definition of type web_search_20260318 (current version at time of writing) passed in the tools array of a Messages API call. Claude then decides when to search based on the request, retrieves results, and returns a response whose sources appear as citations, with each executed search counted in the usage block under server_tool_use.web_search_requests.

The mental model that prevents most confusion: this is not a search endpoint you call. It is a capability you grant Claude, and Claude exercises it inside the conversation. That is genuinely powerful for research-shaped tasks, and it is also why the billing and failure characteristics feel different from a search API you call directly.

How Do You Enable Web Search on a Claude Request?

Add the tool to the request's tools array. The documented cURL shape (Anthropic documentation, fetched 2026-09-17):

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 4096,
    "messages": [
      {"role": "user", "content": "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio."}
    ],
    "tools": [{"type": "web_search_20260318", "name": "web_search"}]
  }'

The tool is server-side: Anthropic's infrastructure executes the searches, and results flow into Claude's context window. The response includes citations for the sources drawn from search results, and the usage block reports how many searches ran, so cost attribution per request is inspectable in the response itself (Anthropic documentation, fetched 2026-09-17).

What Controls Exist Over What Claude Searches?

Four documented controls shape the tool's behavior. allowed_domains and blocked_domains restrict results to or from specified domain lists, and a user_location object of type approximate localizes results with city, region, country, and timezone fields (Anthropic documentation, fetched 2026-09-17).

How eagerly Claude searches is steerable through the system prompt: you can encourage searching more readily or prefer answering directly, and for a hard constraint, max_uses caps the number of searches per request (Anthropic documentation, fetched 2026-09-17). That cap is the single most useful cost control, because without it the number of searches per request is model-determined.

Every web search tool version also accepts allowed_callers, which controls whether Claude calls web search directly or from code execution, a setting tied to zero data retention eligibility on the server tools reference (Anthropic documentation, fetched 2026-09-17).

What Is Dynamic Filtering and When Does It Help?

With web_search_20260209 and later versions, Claude can write and run code that filters search results before they reach the context window, a feature Anthropic calls dynamic filtering, available with Claude 4.6 and later models (Anthropic documentation, fetched 2026-09-17). With basic web search, every search result loads into the context window, and much of that content can be irrelevant to the request. Dynamic filtering keeps only what matters.

The practical effect is on context and cost. A research-heavy question that would otherwise stuff ten results into context can be filtered down to the passages that matter, which reduces the token cost of search-generated content and keeps the model focused. The tradeoff is determinism: Claude is writing the filter, so the selection logic is model behavior rather than code you reviewed. When your compliance story requires that the source-selection logic be inspectable, a domain allowlist you wrote yourself beats a filter Claude generated.

How Does Billing Work for the Web Search Tool?

Two cost lines run in parallel. The search itself is billed at $10 per 1,000 searches, and search results retrieved throughout a conversation count as input tokens, both in the turn where the search executed and in subsequent turns, since the results stay in the conversation context. Each web search counts as one use regardless of the result count (Anthropic documentation, fetched 2026-09-17).

The subtle trap is the second line. A multi-turn conversation that keeps old search results in context pays for those tokens again on every later turn, which makes long research conversations the most expensive shape this tool supports. Two mitigations are documented behavior rather than folklore: max_uses caps the search count, and the usage block exposes server_tool_use.web_search_requests so you can meter per request and per turn in your own code (Anthropic documentation, fetched 2026-09-17).

Decision framework for cost control: cap with max_uses when the request shape is bounded (one question, one answer, done). Accept uncapped searches when the deliverable is deep research where stopping early produces a worse answer. The tradeoff is spend predictability against answer quality, and the usage reporting lets you check the actual cost per request type before picking a permanent policy.

Hosted Tool or Standalone Search API: Which Fits Your Architecture?

The architectural question is the same one that separates all first-party vendor search tools from standalone search APIs: who owns the retrieval step. Claude's web search gives you a research-capable assistant with zero retrieval code, where the model decides what is relevant and you get an answer with citations. A standalone search API returns the raw results to your application, where you can cache them, rank them, filter domains deterministically, and feed them to any model, including Claude (Anthropic documentation, fetched 2026-09-17, and You.com Web Search API documentation).

When the deliverable is Claude answering hard research questions, the hosted tool is the shortest path. When the deliverable is a corpus of results an application consumes, for example a RAG index, an agent audit trail, or a pipeline where retrieval must happen exactly once per request, the standalone shape wins because retrieval is no longer model discretion. The LLM web search API guide covers the retrieval-first architecture, and the hub page for the category is the search API overview.

What Failure Mode Should You Test For Before Shipping?

The concrete failure mode to detect: Claude decides not to search on a question that needed fresh data. Search triggering is steerable through the system prompt, which means it is also mis-steerable: a prompt tuned to "answer directly when you can" produces confident answers from training data on time-sensitive questions, and nothing errors. The symptom is a plausible, stale answer with no citations, which reads as clean output.

Detection is mechanical: check the usage block. A request whose answer should have required current information but reports web_search_requests: 0 is the exact signature of this failure, and you can alert on it in code because the count ships in every response (Anthropic documentation, fetched 2026-09-17). A one-line test in CI, asking a question about something published this week and asserting the search count is at least one, catches prompt regressions before they ship.

For the sibling guides in this series: the OpenAI web search guide covers the Responses API tool shape, and the Gemini grounding guide covers Google's equivalent. The web search API evaluation guide covers how to test any of them against real queries.

Next action: run the cURL example above with max_uses set to two and a question about something published this week, then check the usage block reports at least one search. If it does, you have the wiring and the metering needed to reason about cost. When you need raw results rather than Claude's reasoning over them, get a key on the You.com platform, with rates on the pricing page.