The Claude API web search tool: fresh data with citations, and what it costs

Every model has a training cutoff. Ask about today's stock price, this week's news or the latest version of a library, and the answer is easily stale or invented. You could write your own tool that calls a search API, but the Claude API has a built-in server-side web search tool: Anthropic runs the searches, feeds the results to Claude, and the answer always comes with source citations.

Enabling web search

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What were this week's top AI stories?"}],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 5,
        "allowed_domains": ["reuters.com", "theverge.com"],
    }],
)

Claude decides when to search: for recent events, prices and information that may have changed, it searches; for stable knowledge, maths or creative writing, it answers directly. You can encourage or discourage searching via the system prompt.

Tool versions

Key parameters

• max_uses: caps searches per request. Simple questions usually take 1–3; comparative research can take 10 or more.
• allowed_domains / blocked_domains: use one or the other; setting both returns a 400 error.
• user_location: localises results (city, country, timezone).

Cost and citations

• $10 per 1,000 searches, plus normal token costs. Search results count as input tokens, including in later turns.
• Failed searches aren't billed.
• Citations are always on; the cited_text, title and url fields don't count toward tokens. When showing output to end users, you must display citations to the original sources.

Handling the response

• Search errors (exceeding max_uses, rate limits…) still return HTTP 200, with the error inside the web_search_tool_result block. Your code must check inside.
• Multi-turn conversations: send the result blocks back unchanged, including encrypted_content; modified or missing content returns a 400.
• stop_reason: "pause_turn": a long search turn was paused; send that message back to continue.

Risks and caveats

• Web content is untrusted data: pages can contain prompt injection. Don't give an agent with web search sensitive action permissions without an approval layer.
• Cost grows with context: search results take many input tokens; use dynamic filtering or limit max_uses.
• Admins can disable it: if your organisation turns off web search in the Console, requests with the tool return a 400.

How to apply it

• Dev: Start with a small max_uses and a trusted domain list; log usage.server_tool_use to track searches.
• Tech Lead: Separate a "research" agent (web search, no write access) from an "action" agent to reduce injection risk.
• PM: Budget by searches × users; show sources clearly to build trust.