How to Use Claude Web Search | claude.ai Settings, API Pricing, and Citations

What is Claude Web Search?

Claude Web Search is a search tool that Anthropic runs on the server side. Whether in the claude.ai chat interface or through the Claude API, Claude automatically issues queries whenever it determines they are necessary — even without explicit instructions to "search" — and returns answers with citations based on the results.

The feature launched in the United States in March 2025, expanded globally on May 27 of the same year, and is now available without regional restrictions. It is well suited for topics that go beyond the knowledge cutoff, news, real-time information such as prices and exchange rates, and verifying the latest documentation. For general questions that Claude can answer from internal knowledge, it skips the search, so the design minimizes unnecessary charges and response delays.

In the API, a server_tool_use block is inserted into the response, giving you the query Claude issued, the returned URLs, titles, page_age, and citation text as structured JSON. In the chat UI, transparency is maintained through a "Searching the web…" status indicator and source links displayed below the answer.

How to use Web Search on claude.ai

Using Web Search on claude.ai is straightforward: click the slider icon in the input field and toggle "Web search" ON. You can switch it ON or OFF with each prompt, so you can keep it OFF for casual conversation or routine tasks that don't require live information, and turn it ON when you need to check news or verify real-time data.

1. Log in to claude.ai and open a new chat.
2. Click the slider icon (tool selection menu) at the bottom left of the input field.
3. Toggle "Web search" ON in the dropdown.
4. Type your question as usual and send it.
5. Click the source links in the response to verify the facts in the original source.

Web search and fetch are available on the Free plan, but search and retrieval activity counts toward your daily usage limit. Heavily using long URLs can consume your allowance quickly, so Free users are advised to avoid unnecessary links and turn Web Search OFF for questions where a general answer is sufficient.

Supported models and plan-specific limits

As of May 2026, the API supports Web Search on Opus 4.7, Sonnet 4.6, Opus 4.6, Opus 4.5, Haiku 4.5, and Sonnet 4.5. Dynamic filtering with the latest tool version web_search_20260209 is limited to Opus 4.7, Opus 4.6, and Sonnet 4.6; for other models, use the older web_search_20250305.

Note that the latest flagship Opus 4.8 launched on June 1, 2026. Whether Opus 4.8 has been added to the supported model list for web_search_20260209 (dynamic filtering) may change shortly after release, so this article refrains from making a definitive statement. We recommend checking Anthropic's official model list and Web Search tool documentation as the primary source. At minimum, the stable web_search_20250305 is a foundational tool available across generations, so you can continue using Web Search after upgrading to Opus 4.8 as before. Keep in mind that the list above reflects the state as of May 2026, and the tools themselves are not outdated.

Here is how each claude.ai plan handles Web Search:

• Free: Available. Web search usage counts toward the daily usage limit.
• Pro / Max: Available. Generally free to use within the usage limit.
• Team / Enterprise: Available, but the toggle only appears for members after an Owner or Primary Owner enables the feature in Admin settings > Capabilities.
• Cloud providers: Supported on Microsoft Foundry and Google Vertex AI. Vertex AI supports only the basic version without dynamic filtering. Web Search is not available in the Amazon Bedrock Mythos Preview.

For organizational deployments, first have an admin enable Web Search in the Capabilities screen, then verify per-API-key usage permissions in Claude Console's Privacy settings. Organizations with Zero Data Retention (ZDR) have additional allowed_callers requirements — refer to the Server tools documentation for details.

How to integrate Web Search in the API

To use Web Search in the API, add a tools array to your Messages API request and pass either web_search_20260209 or web_search_20250305. The minimal setup looks like this:

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-opus-4-7",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "What is the weather in NYC?"}
    ],
    "tools": [{
      "type": "web_search_20250305",
      "name": "web_search",
      "max_uses": 5
    }]
  }'

This minimal example intentionally uses the stable web_search_20250305, which works across all supported models. A good rule of thumb is to switch to web_search_20260209 only when you need dynamic filtering (available only on Opus 4.7, Opus 4.6, and Sonnet 4.6), so you never have to wonder which version to write for your first implementation.

In the Python SDK, simply pass the same dictionary to the tools argument of client.messages.create(). Official SDKs for TypeScript, Java, C#, Go, PHP, and Ruby all provide equivalent classes such as WebSearchTool20250305 and WebSearchTool20260209, letting you integrate with minimal code and full type completion.

Responses include a server_tool_use block (the issued query), a web_search_tool_result block (URL, title, and encrypted_content of results), and a text block with a citations array (mapping citations to body text). In multi-turn conversations, you must pass encrypted_content and encrypted_index back in subsequent requests, so include them in your persistence layer.

Parameters you can specify in a request

There are four main parameters you can pass in the tool definition, which you can combine based on your product requirements:

• max_uses: The maximum number of searches per request. Setting it to something like 5 prevents runaway multi-step searches from inflating costs. Exceeding the limit returns a max_uses_exceeded error in the tool result.
• allowed_domains: Restricts search results to specific domains. Useful for custom RAG-style setups that only reference internal knowledge bases or official documentation.
• blocked_domains: Blocks results from untrusted sources or competitors. Mutually exclusive with allowed_domains — choose one based on your use case.
• user_location: Pass city, region, country, and timezone using the approximate type to localize results for location-sensitive searches (weather, stores, news). timezone uses IANA IDs (e.g., Asia/Tokyo).

One implementation note: even when a search error occurs, the API returns HTTP 200 with an error_code inside the web_search_tool_result. The main error codes are too_many_requests (rate limit), invalid_input, max_uses_exceeded, query_too_long, and unavailable. Surfacing differentiated error messages to users instead of silently swallowing failures reduces support load.

Pricing and its relationship to token billing

The price is $10 per 1,000 searches, meaning $0.01 per search. If a single request triggers multiple searches, each one is billed separately. Searches that fail due to errors are not charged. Calls via the Batch API are billed at the same rate — no batch discount applies.

Separately from the per-search charge, search result text is billed as input tokens. When designing agents that use Web Search heavily, you can significantly reduce token consumption by using max_uses to cap the number of searches, using allowed_domains to exclude sites that return large HTML pages, or enabling dynamic filtering with web_search_20260209 to discard irrelevant content before it enters the context.

Also worth noting for accurate cost estimation: citation fields (cited_text, title, url) are not counted in either input or output token usage. You can also use prompt caching alongside Web Search — caching a fixed tool definition reduces the cost of subsequent requests.

Citation features and display requirements

Citations in Claude Web Search are always enabled; no additional configuration is needed from API users. The text block in the response includes a citations array, where each entry of type web_search_result_location contains url, title, encrypted_index, and cited_text (up to 150 characters).

Worth highlighting is the display policy that Anthropic explicitly states in its documentation. If you display API output directly to end users, you must include citations linking to the original source. If you process or reprocess API output before displaying it, you are advised to consult your legal team about appropriate citation display. For products that integrate Claude in a RAG-like manner, common UI patterns include showing cited_text on hover and listing source URLs as footnotes.

In the claude.ai chat UI, citations are automatically formatted as source links, letting users open the original source with a single click. Across Free, Pro, and Max plans, the Web Search feature is designed so that citation-free responses do not occur.

Using the code execution tool with dynamic filtering

The latest Web Search version web_search_20260209 includes a mechanism that dynamically filters search results before adding them to the context. To use this, you must also enable the code execution tool (code_execution). Claude writes Python code to post-process the search results, retains only the relevant snippets, discards the rest of the HTML, and then proceeds to the reasoning step.

This is best suited for tasks that involve noisy long-form text: searching technical documentation, literature reviews, citation verification, and grounding checks. In your implementation, add both web_search_20260209 and code_execution_20250522 to the tools array and set model to one of Opus 4.7, Opus 4.6, or Sonnet 4.6.

import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Search the current AAPL and GOOGL prices and compute P/E ratios."
    }],
    tools=[
        {"type": "web_search_20260209", "name": "web_search"},
        {"type": "code_execution_20250522", "name": "code_execution"},
    ],
)

Dynamic filtering is available through the Claude API and Microsoft Azure; Google Vertex AI offers only the basic version. While the code execution step adds latency per search, Anthropic states that response quality and final token consumption tend to improve as a result.

Frequently asked questions and troubleshooting

Here are five common questions that come up in practice:

• "Search isn't working": On claude.ai, confirm that Web Search is toggled ON from the input field slider. For Team/Enterprise, check that an admin has configured Capabilities settings. In the API, verify that the tool definition is included in the tools array and that the model is on the supported model list.
• "Citations aren't showing": In API responses, citations are included in the text block. A common implementation mistake is extracting only the text and discarding citations — log the full response to check.
• "Costs are higher than expected": The main culprit is usually not the per-search charge ($0.01), but the search result text billed as input tokens. Try capping max_uses to 3–5, and consider enabling dynamic filtering with web_search_20260209 if needed.
• "I want to use only information from a specific site": Use allowed_domains to restrict results to official documentation or internal sites. Note that allowed_domains and blocked_domains are mutually exclusive by design, so choose one based on your use case.
• "pause_turn was returned": This is an interruption signal when search processing takes too long. Follow the Server tools documentation to continue by resending the message history as-is.

Sources

• Anthropic official blog "Claude can now search the web": https://claude.com/blog/web-search
• Claude API documentation "Web search tool": https://platform.claude.com/docs/ja/docs/agents-and-tools/tool-use/web-search-tool
• Anthropic Help Center "Enabling and Using Web Search": https://support.claude.com/en/articles/10684626-enabling-and-using-web-search