Skip to content
Documentation
API referenceWeb search / Web fetch

Web search / Web fetch

Web search and page fetching: APIs, limits and cost.

Model protocol

Claude Messages: Web search and Web fetch

Anthropic Messages with and without a server prompt supports exactly two server tools. Claude API executes them, so your application does not send an ordinary client tool_result.

ToolExact typeRequired limits
Web searchweb_search_20250305max_uses: 1–5
Web fetchweb_fetch_20250910max_uses: 1–3; max_content_tokens: 1–25,000 (approximate, text only)
json
{
  "model": "claude-opus-5",
  "max_tokens": 2048,
  "tools": [
    {
      "type": "web_search_20250305",
      "name": "web_search",
      "max_uses": 3,
      "allowed_domains": ["docs.python.org"]
    },
    {
      "type": "web_fetch_20250910",
      "name": "web_fetch",
      "max_uses": 2,
      "max_content_tokens": 12000,
      "allowed_domains": ["docs.python.org"],
      "citations": {"enabled": true}
    }

Strict object shape

ObjectAllowed fields
Web searchtype, name, max_uses; optional allowed_domains or blocked_domains, allowed_callers
Web fetchWeb search fields + required max_content_tokens; optional citations
  • name must be exactly web_search or web_fetch; at most one server tool of each type is allowed per request. Guard accepts only the listed fields: unknown fields (including the official search option user_location) and other typed tool variants are rejected with 400.
  • If supplied, allowed_callers must be exactly ["direct"].
  • allowed_domains and blocked_domains are mutually exclusive. Each list accepts at most 100 ASCII domains, with no scheme, IP address, query/fragment, backslash, or wildcard in the hostname.
  • Web search may include an optional path after the domain, such as docs.python.org/3/*; Web fetch accepts a bare domain only, with no path.
  • Web fetch citations, when supplied, must be exactly {"enabled": true} or {"enabled": false} with no extra fields. Client tools must omit type or use type: "custom".

Limits

  • The client must pass the limits above explicitly. A value over the limit or an unknown server-tool version is rejected with 400 before execution.
  • Both tools first return server_tool_use, followed by the corresponding web_search_tool_result or web_fetch_tool_result; search citations are always on, while fetch citations are optional.
  • A tool failure may arrive inside a successful HTTP 200: find a tool-result block whose content.type ends in _tool_result_error, then read content.error_code.
  • Web fetch accepts a URL no longer than 250 characters that already appeared in a user message, client tool result, or earlier search/fetch result. It supports text, HTML, and PDF; sites that require JavaScript rendering are unsupported, and failed fetches consume max_uses.
  • A successful Web search with no matches returns content: []; this is not a tool error.

Pricing

ItemCharge
Web search$0.01 per provider-reported billed request + ordinary input tokens for generated content
Provider-nonbillable Web search errorNo $0.01 tool charge
Web fetchNo separate fee; fetched content is billed as input tokens

Kimi, Composer and Grok

  • Kimi. Search and page fetch live in two separate endpoints, POST /v1/kimi/search and POST /v1/kimi/fetch. They never call the model: they return text that you put into your next chat request yourself. There is no separate charge for them, you pay only for the tokens of that request. Request bodies, limits and error codes are on Kimi: Chat Completions.
  • Composer and Grok. Built-in web search is available during a reply. There is no separate public call for controlling this search; typed Anthropic server tools are not accepted. Client functions are supplied separately through tools and run by your client.

Search is model-directed: tools permits the operation, but the model decides whether to use it. These are the three exact shapes; similar objects from another API are not substitutes.

Chat Completions:

json
{
  "type": "web_search",
  "web_search": {
    "enable": true,
    "search_engine": "search-prime",
    "search_result": true,
    "count": 2
  }
}

Messages:

json
{
  "type": "web_search_20250305",
  "name": "web_search",
  "max_uses": 1
}

Responses:

json
{"type": "web_search_preview"}
APIConfirmed operation marker
ChatA non-empty terminal web_search
MessagesA server_tool_use (web_search) with its web_search_tool_result
ResponsesA completed web_search_call

Guard adds $0.10 only for a confirmed call. Chat count: 2 means two result rows, not two paid operations. Messages max_uses reserves the allowed operations, while final billing uses confirmed calls.

Gemini searches the web with Google search. Search works on all three APIs and is switched on by an object in tools; it is billed separately, by the number of search requests.

APIObject in tools
Messages{"type": "web_search_20250305", "name": "web_search"}
Chat Completions{"type": "web_search"}
Responses{"type": "web_search"}
json
{
  "model": "gemini-4-argon",
  "max_tokens": 4096,
  "messages": [{"role": "user", "content": "What is new today?"}],
  "tools": [{"type": "web_search_20250305", "name": "web_search"}]
}
ItemCharge
A search request$0.014 for each request, starting with the first
Before the answerthe cost of one search ($0.014) is held; the final charge uses the actual number of searches
Retrieved textordinary input tokens
  • Claude Code sends the web_search_20250305 tool too, so search from Claude Code works.
  • Gemini has no separate web_fetch tool yet: a request with it gets a clear refusal, while Google search works.
  • The search limit max_uses is accepted but not kept: Google decides how many searches to run. Every search is billed at the price above.
  • Site lists (allowed_domains, blocked_domains) are not supported: a request with them gets a clear refusal.

Muse searches the web with Meta search through Messages and Responses; Chat Completions has no search. Guard translates the web_search_20250305 tool that Claude Code sends into Meta search.

json
{
  "model": "muse-wonder-1.0",
  "max_tokens": 4096,
  "messages": [{"role": "user", "content": "What is new today?"}],
  "tools": [{"type": "web_search_20250305", "name": "web_search"}]
}
ItemCharge
A search request$0.0025 for each request, starting with the first
Before the answerthe cost of five searches (5 × $0.0025 = $0.0125) is held; the final charge uses the actual number of searches
Reading a pagegoes through the native Meta search and is not counted as a paid search by itself
  • The native Meta search reads the pages. Muse has no separate web_fetch tool.
  • The search limit max_uses, which Claude Code sends with every search, is accepted but not kept: Meta decides how many searches to run. Every search is billed at the price above. Search from Claude Code works.
  • Meta does not support site lists (allowed_domains, blocked_domains): a request with them gets a clear refusal.

Sections

On this page