Web fetch tool

The web fetch tool allows Claude to retrieve full content from specified web pages and PDF documents.

The latest web fetch tool version (web_fetch_20260318) supports dynamic filtering with Claude Fable 5, Claude Opus 4.8, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5, and Claude Sonnet 4.6. Claude can write and execute code to filter fetched content before it reaches the context window, keeping only relevant information and discarding the rest. This reduces token consumption while maintaining response quality. web_fetch_20260318 also adds response inclusion control for agentic workflows. The previous versions (web_fetch_20260309 for dynamic filtering and cache bypass, web_fetch_20260209 for dynamic filtering only, web_fetch_20250910 for basic fetch) remain available.

Web fetch (with and without dynamic filtering) is available on the Claude API, Claude Platform on AWS, and Microsoft Foundry. On Microsoft Foundry, web fetch requires a Hosted on Anthropic deployment. It is not currently available on Amazon Bedrock or Google Cloud.

For Zero Data Retention eligibility and the allowed_callers workaround, see Server tools.

For model support, see the Tool reference.



How web fetch works

Web fetch is a server tool: the API fetches the content during the request and inserts the results into the conversation. You don't run anything or return a tool_result. The exception is when Claude calls web fetch and one of your client tools in the same group of parallel tool calls: the API returns the response with stop_reason: "tool_use" before that fetch has run, then runs the fetch when you send back the client tool_result blocks. See Mixing server tools and client tools in one turn.

When you add the web fetch tool to your API request:

1. Claude determines when to fetch content based on the prompt and available URLs.
2. The API retrieves the full text content from the specified URL.
3. For PDFs, the API returns the content as base64-encoded data and processes it like a directly attached PDF document.
4. Claude analyzes the fetched content and provides a response with optional citations.



When Claude fetches

Claude fetches when the request points at a specific page or document:

• A URL is provided in the conversation (or a previous tool result)
• The user names a specific resource (a particular article, README, pricing page, or documentation section) without a URL, and the web search tool is also enabled so Claude can locate it first (see Combined search and fetch)

Claude does not fetch for general-knowledge or open-ended questions that don't reference a specific page. "Summarize this article: <url>" triggers a fetch. "What are best practices for REST API design?" is answered directly.



Dynamic filtering

Fetching full web pages and PDFs can quickly consume tokens, especially when only specific information is needed from large documents. With web_fetch_20260209 or later, Claude can write and execute code to filter the fetched content before loading it into context.

This dynamic filtering is particularly useful for:

• Extracting specific sections from long documents
• Processing structured data from web pages
• Filtering relevant information from PDFs
• Reducing token costs when working with large documents

To enable dynamic filtering, use web_fetch_20260209 or any later version. The following examples use web_fetch_20260318:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Fetch the content at https://example.com/research-paper and extract the key findings.",
        }
    ],
    tools=[{"type": "web_fetch_20260318", "name": "web_fetch"}],
)
print(response)



How to use web fetch

Provide the web fetch tool in your API request:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Please analyze the content at https://example.com/article",
        }
    ],
    tools=[{"type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 5}],
)
print(response)



Tool definition

The web fetch tool supports the following parameters:

{
  "type": "web_fetch_20250910",
  "name": "web_fetch",

  // Optional: Limit the number of fetches per request
  "max_uses": 10,

  // Optional: Only fetch from these domains
  "allowed_domains": ["example.com", "docs.example.com"],

  // Optional: Never fetch from these domains (cannot be combined with allowed_domains)
  "blocked_domains": ["private.example.com"],

  // Optional: Enable citations for fetched content
  "citations": {
    "enabled": true
  },

  // Optional: Maximum content length in tokens
  "max_content_tokens": 100000
}

Later tool versions add two more optional parameters: use_cache requires web_fetch_20260309 or later (see Cache bypass), and response_inclusion requires web_fetch_20260318 or later (see Response inclusion).



Max uses

The max_uses parameter limits the number of web fetches performed. Failed fetches count against the limit. If Claude attempts more fetches than allowed, the web_fetch_tool_result is an error with the max_uses_exceeded error code. There is currently no default limit.



Domain filtering

For domain filtering with allowed_domains and blocked_domains, see Server tools.



Content limits

The max_content_tokens parameter limits the amount of content included in the context. If the fetched content exceeds this limit, the tool truncates it. This helps control token usage when fetching large documents. The limit applies to text content, not to binary content such as PDFs.



Cache bypass

The use_cache parameter controls whether cached content may be returned. Set "use_cache": false to bypass the cache and fetch fresh content. The default is true. Only disable caching when the user explicitly requests fresh content or when fetching rapidly changing sources, because bypassing the cache increases latency.

{
  "tools": [
    {
      "type": "web_fetch_20260309",
      "name": "web_fetch",
      "use_cache": false
    }
  ]
}



Response inclusion

The response_inclusion parameter controls how fetch result blocks appear in the API response when the result was consumed by a completed code execution call in the same turn. Set "response_inclusion": "excluded" to drop those nested server_tool_use and result block pairs entirely from the response, reducing output token costs for agentic workflows that don't need to echo raw page content back to the client. The default is "full". Results from direct calls, or from code execution calls that paused before completing, are always returned in full so they can be sent back on the next turn.

{
  "tools": [
    {
      "type": "web_fetch_20260318",
      "name": "web_fetch",
      "response_inclusion": "excluded"
    }
  ]
}



Citations

Unlike web search where citations are always enabled, citations are optional for web fetch and disabled by default. Set "citations": {"enabled": true} to enable Claude to cite specific passages from fetched documents.



Response

Here's an example response structure:

{
  "role": "assistant",
  "content": [
    // 1. Claude's decision to fetch
    {
      "type": "text",
      "text": "I'll fetch the content from the article to analyze it."
    },
    // 2. The fetch request
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01234567890abcdef",
      "name": "web_fetch",
      "input": {
        "url": "https://example.com/article"
      }
    },
    // 3. Fetch results
    {
      "type": "web_fetch_tool_result",
      "tool_use_id": "srvtoolu_01234567890abcdef",
      "content": {
        "type": "web_fetch_result",
        "url": "https://example.com/article",
        "content": {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "Full text content of the article..."
          },
          "title": "Article Title",
          "citations": { "enabled": true }
        },
        "retrieved_at": "2025-08-25T10:30:00Z"
      }
    },
    // 4. Claude's analysis with citations (if enabled)
    {
      "text": "Based on the article, ",
      "type": "text"
    },
    {
      "text": "the main argument presented is that artificial intelligence will transform healthcare",
      "type": "text",
      "citations": [
        {
          "type": "char_location",
          "document_index": 0,
          "document_title": "Article Title",
          "start_char_index": 1234,
          "end_char_index": 1456,
          "cited_text": "Artificial intelligence is poised to revolutionize healthcare delivery..."
        }
      ]
    }
  ],
  "id": "msg_a930390d3a",
  "usage": {
    "input_tokens": 25039,
    "output_tokens": 931,
    "server_tool_use": {
      "web_fetch_requests": 1
    }
  },
  "stop_reason": "end_turn"
}



Fetch results

Fetch results include:

• url: The URL that was fetched
• content: A document block containing the fetched content
• retrieved_at: Timestamp when the content was retrieved

For PDF documents, content is returned as base64-encoded data:

{
  "type": "web_fetch_tool_result",
  "tool_use_id": "srvtoolu_02",
  "content": {
    "type": "web_fetch_result",
    "url": "https://example.com/paper.pdf",
    "content": {
      "type": "document",
      "source": {
        "type": "base64",
        "media_type": "application/pdf",
        "data": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmo..."
      },
      "citations": { "enabled": true }
    },
    "retrieved_at": "2025-08-25T10:30:02Z"
  }
}



Errors

When the web fetch tool encounters an error, the Claude API returns a 200 (success) response with the error represented in the response body. Claude sees the error result and continues the turn. For example:

{
  "type": "web_fetch_tool_result",
  "tool_use_id": "srvtoolu_a93jad",
  "content": {
    "type": "web_fetch_tool_result_error",
    "error_code": "url_not_accessible"
  }
}

These are the possible error codes:

• invalid_tool_input: Invalid tool input, such as a malformed URL or a non-HTTP(S) scheme
• url_too_long: URL exceeds maximum length (250 characters)
• url_not_allowed: URL blocked by domain filtering rules (including your organization's settings) or by Anthropic-side restrictions, such as private addresses and robots.txt
• url_not_in_prior_context: URL did not appear earlier in the conversation (see URL validation)
• url_not_accessible: Failed to fetch content (HTTP error)
• too_many_requests: Rate limit exceeded
• unsupported_content_type: Content type not supported (only text, HTML, and PDF)
• max_uses_exceeded: Maximum web fetch tool uses exceeded
• unavailable: An internal error occurred



URL validation

For security reasons, the web fetch tool can only fetch URLs that have previously appeared in the conversation context. This includes:

• URLs in user messages
• URLs in client-side tool results
• URLs from previous web search or web fetch results

The tool cannot fetch arbitrary URLs that Claude generates or URLs from container-based server tools (such as Code Execution and Bash).



Combined search and fetch

When both the web search and web fetch tools are enabled, and the user names a specific page or document without providing a URL (for example, "read the README from the anthropics/anthropic-sdk-python repository"), Claude uses web search to locate it, then fetches the result. The following example asks for a search and an analysis in one request:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Find recent articles about quantum computing and analyze the most relevant one in detail",
        }
    ],
    tools=[
        {"type": "web_search_20250305", "name": "web_search", "max_uses": 3},
        {
            "type": "web_fetch_20250910",
            "name": "web_fetch",
            "max_uses": 5,
            "citations": {"enabled": True},
        },
    ],
)
print(response)

In this workflow, Claude:

1. Uses web search to find relevant articles.
2. Selects the most promising results.
3. Uses web fetch to retrieve full content.
4. Provides detailed analysis with citations.



Prompt caching

For caching tool definitions across turns, see Tool use with prompt caching.



Streaming

With streaming enabled, fetch events are part of the stream with a pause during content retrieval:

event: message_start
data: {"type": "message_start", "message": {"id": "msg_abc123", "type": "message"}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

// Claude's decision to fetch

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_fetch"}}

// Fetch URL streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"url\":\"https://example.com/article\"}"}}

// Pause while fetch executes

// Fetch results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "web_fetch_result", "url": "https://example.com/article", "content": {"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "Article content..."}}}}}

// Claude's response continues...



Batch requests

You can include the web fetch tool in the Messages Batches API. Web fetch tool calls through the Messages Batches API are priced the same as those in regular Messages API requests.



Usage and pricing

Web fetch usage has no additional charges beyond standard token costs:

{
  "usage": {
    "input_tokens": 25039,
    "output_tokens": 931,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "server_tool_use": {
      "web_fetch_requests": 1
    }
  }
}

The web fetch tool is available on the Claude API at no additional cost. You only pay standard token costs for the fetched content that becomes part of your conversation context.

To protect against inadvertently fetching large content that would consume excessive tokens, use the max_content_tokens parameter to set appropriate limits based on your use case and budget considerations.

Example token usage for typical content:

• Average web page (10 kB): ~2,500 tokens
• Large documentation page (100 kB): ~25,000 tokens
• Research paper PDF (500 kB): ~125,000 tokens



Next steps