Tools

Web fetch tool

Fetch and read content from specific URLs to augment Claude's context with live web content.

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_20260209) supports dynamic filtering with Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, 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. The previous tool version (web_fetch_20250910) remains available without dynamic filtering.

For Claude Mythos Preview, web fetch is supported on the Claude API and Microsoft Foundry only. It is not available for Mythos Preview on Amazon Bedrock or Google Vertex AI.

Use the feedback form to provide feedback on the quality of the model responses, the API itself, or the quality of the documentation.

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

Enabling the web fetch tool in environments where Claude processes untrusted input alongside sensitive data poses data exfiltration risks. Only use this tool in trusted environments or when handling non-sensitive data.

To minimize exfiltration risks, Claude is not allowed to dynamically construct URLs. Claude can only fetch URLs that have been explicitly provided by the user or that come from previous web search or web fetch results. However, there is still residual risk that should be carefully considered when using this tool.

If data exfiltration is a concern, consider:

Disabling the web fetch tool entirely
Using the max_uses parameter to limit the number of requests
Using the allowed_domains parameter to restrict to known safe domains

For model support, see the Tool reference.

How web fetch works

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

Claude decides when to fetch content based on the prompt and available URLs.
The API retrieves the full text content from the specified URL.
For PDFs, automatic text extraction is performed.
Claude analyzes the fetched content and provides a response with optional citations.

The web fetch tool currently does not support websites dynamically rendered via JavaScript.

Dynamic filtering

Fetching full web pages and PDFs can quickly consume tokens, especially when only specific information is needed from large documents. With the web_fetch_20260209 tool version, 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

Dynamic filtering requires the code execution tool to be enabled. The web fetch tool (with and without dynamic filtering) is available on the Claude API and Microsoft Azure.

To enable dynamic filtering, use the web_fetch_20260209 tool version:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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_20260209", "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-7",
    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:

JSON

{
  "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
  "blocked_domains": ["private.example.com"],

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

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

Max uses

The max_uses parameter limits the number of web fetches performed. 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 max_content_tokens parameter limit is approximate. The actual number of input tokens used can vary by a small amount.

Citations

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

When displaying API outputs directly to end users, citations must be included to the original source. If you are making modifications to API outputs, including by reprocessing and/or combining them with your own material before displaying them to end users, display citations as appropriate based on consultation with your legal team.

Response

Here's an example response structure:

Output

{
  "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

The web fetch tool caches results to improve performance and reduce redundant requests. The content returned may not always reflect the latest version available at the URL. The cache behavior is managed automatically and may change over time to optimize for different content types and usage patterns.

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

Output

{
  "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:

Output

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

These are the possible error codes:

invalid_input: Invalid URL format
url_too_long: URL exceeds maximum length (250 characters)
url_not_allowed: URL blocked by domain filtering rules and model restrictions
url_not_accessible: Failed to fetch content (HTTP error)
too_many_requests: Rate limit exceeded
unsupported_content_type: Content type not supported (only text 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 (Code Execution, Bash, etc.).

Combined search and fetch

Web fetch works seamlessly with web search for comprehensive information gathering:

Python

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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},
        },
    ],
)

In this workflow, Claude will:

Use web search to find relevant articles
Select the most promising results
Use web fetch to retrieve full content
Provide 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:

Output

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

Server tools

Shared mechanics for Anthropic-executed tools.

Tool reference

Directory of all Anthropic-provided tools.

Was this page helpful?

Tools

Web fetch tool

Fetch and read content from specific URLs to augment Claude's context with live web content.

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

For Claude Mythos Preview, web fetch is supported on the Claude API and Microsoft Foundry only. It is not available for Mythos Preview on Amazon Bedrock or Google Vertex AI.

Use the feedback form to provide feedback on the quality of the model responses, the API itself, or the quality of the documentation.

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

If data exfiltration is a concern, consider:

Disabling the web fetch tool entirely
Using the max_uses parameter to limit the number of requests
Using the allowed_domains parameter to restrict to known safe domains

For model support, see the Tool reference.

How web fetch works

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

Claude decides when to fetch content based on the prompt and available URLs.
The API retrieves the full text content from the specified URL.
For PDFs, automatic text extraction is performed.
Claude analyzes the fetched content and provides a response with optional citations.

The web fetch tool currently does not support websites dynamically rendered via JavaScript.

Dynamic filtering

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

Dynamic filtering requires the code execution tool to be enabled. The web fetch tool (with and without dynamic filtering) is available on the Claude API and Microsoft Azure.

To enable dynamic filtering, use the web_fetch_20260209 tool version:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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_20260209", "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-7",
    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:

JSON

{
  "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
  "blocked_domains": ["private.example.com"],

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

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

Max uses

Domain filtering

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

Content limits

The max_content_tokens parameter limit is approximate. The actual number of input tokens used can vary by a small amount.

Citations

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

Response

Here's an example response structure:

Output

{
  "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:

Output

{
  "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:

Output

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

These are the possible error codes:

invalid_input: Invalid URL format
url_too_long: URL exceeds maximum length (250 characters)
url_not_allowed: URL blocked by domain filtering rules and model restrictions
url_not_accessible: Failed to fetch content (HTTP error)
too_many_requests: Rate limit exceeded
unsupported_content_type: Content type not supported (only text 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 (Code Execution, Bash, etc.).

Combined search and fetch

Web fetch works seamlessly with web search for comprehensive information gathering:

Python

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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},
        },
    ],
)

In this workflow, Claude will:

Use web search to find relevant articles
Select the most promising results
Use web fetch to retrieve full content
Provide 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:

Output

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.

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

Server tools

Shared mechanics for Anthropic-executed tools.

Tool reference

Directory of all Anthropic-provided tools.

Was this page helpful?