# 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_20260209`) supports **dynamic filtering** with Claude Opus 4.6 and 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.¶
¶
<Note>¶
Please use [this form](https://forms.gle/NhWcgmkcvPCMmPE86) to provide feedback on the quality of the model responses, the API itself, or the quality of the documentation.¶
</Note>¶
¶
<Note>¶
This feature is [Zero Data Retention (ZDR)](/docs/en/build-with-claude/zero-data-retention) eligible. When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.¶
</Note>¶
¶
<Warning>¶
Enabling the web fetch tool in environments where Claude processes untrusted input alongside sensitive data poses data exfiltration risks. We recommend oOnly usinge 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¶
</Warning>¶
¶
## Supported models¶
¶
Web fetch is available on:¶
¶
- Claude Opus 4.6 (`claude-opus-4-6`)¶
- Claude Opus 4.5 (`claude-opus-4-5-20251101`)¶
- Claude Opus 4.1 (`claude-opus-4-1-20250805`)¶
- Claude Opus 4 (`claude-opus-4-20250514`)¶
- Claude Sonnet 4.6 (`claude-sonnet-4-6`)¶
- Claude Sonnet 4.5 (`claude-sonnet-4-5-20250929`)¶
- Claude Sonnet 4 (`claude-sonnet-4-20250514`)¶
- Claude Sonnet 3.7 ([deprecated](/docs/en/about-claude/model-deprecations)) (`claude-3-7-sonnet-20250219`)¶
- Claude Haiku 4.5 (`claude-haiku-4-5-20251001`)¶
- Claude Haiku 3.5 ([deprecated](/docs/en/about-claude/model-deprecations)) (`claude-3-5-haiku-latest`)¶
¶
## How web fetch works¶
¶
When you add the web fetch tool to your API request:¶
¶
1. Claude decides 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, automatic text extraction is performed.¶
4. Claude analyzes the fetched content and provides a response with optional citations.¶
¶
<Note>¶
The web fetch tool currently does not support web sites dynamically rendered via Javascript.¶
</Note>¶
¶
### Dynamic filtering with Opus 4.6 and Sonnet 4.6¶
¶
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¶
¶
<Note>¶
Dynamic filtering requires the [code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool) to be enabled. The web fetch tool (with and without dynamic filtering) is available on the Claude API and Microsoft Azure.¶
</Note>¶
¶
To enable dynamic filtering, use the `web_fetch_20260209` tool version with the `code-execution-web-tools-2026-02-09` beta header:¶
¶
<CodeGroup>¶
```bash Shell¶
curl https://api.anthropic.com/v1/messages \¶
--header "x-api-key: $ANTHROPIC_API_KEY" \¶
--header "anthropic-version: 2023-06-01" \¶
--header "anthropic-beta: code-execution-web-tools-2026-02-09" \¶
--header "content-type: application/json" \¶
--data '{¶
"model": "claude-opus-4-6",¶
"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"¶
}]¶
}'¶
```¶
¶
```python Python¶
import anthropic¶
¶
client = anthropic.Anthropic()¶
¶
response = client.beta.messages.create(¶
model="claude-opus-4-6",¶
max_tokens=4096,¶
betas=["code-execution-web-tools-2026-02-09"],¶
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)¶
```¶
¶
```typescript TypeScript¶
import { Anthropic } from "@anthropic-ai/sdk";¶
¶
const anthropic = new Anthropic();¶
¶
async function main() {¶
const response = await anthropic.beta.messages.create({¶
model: "claude-opus-4-6",¶
max_tokens: 4096,¶
betas: ["code-execution-web-tools-2026-02-09"],¶
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" }]¶
});¶
¶
console.log(response);¶
}¶
¶
main().catch(console.error);¶
```¶
</CodeGroup>¶
¶
## How to use web fetch¶
¶
Provide the web fetch tool in your API request:¶
¶
<CodeGroup>¶
```bash Shell¶
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-6",¶
"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¶
}]¶
}'¶
```¶
¶
```python Python¶
import anthropic¶
¶
client = anthropic.Anthropic()¶
¶
response = client.messages.create(¶
model="claude-opus-4-6",¶
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)¶
```¶
¶
```typescript TypeScript¶
import { Anthropic } from "@anthropic-ai/sdk";¶
¶
const anthropic = new Anthropic();¶
¶
async function main() {¶
const response = await anthropic.messages.create({¶
model: "claude-opus-4-6",¶
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¶
}]¶
});¶
¶
console.log(response);¶
}¶
¶
main().catch(console.error);¶
```¶
</CodeGroup>¶
¶
### Tool definition¶
¶
The web fetch tool supports the following parameters:¶
¶
```json 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` will be an error with the `max_uses_exceeded` error code. There is currently no default limit.¶
¶
#### Domain filtering¶
¶
When using domain filters:¶
¶
- Domains should not include the HTTP/HTTPS scheme (use `example.com` instead of `https://example.com`)¶
- Subdomains are automatically included (`example.com` covers `docs.example.com`)¶
- Subpaths are supported (`example.com/blog`)¶
- You can use either `allowed_domains` or `blocked_domains`, but not both in the same request.¶
¶
<Warning>¶
Be aware that Unicode characters in domain names can create security vulnerabilities through homograph attacks, where visually similar characters from different scripts can bypass domain filters. For example, `аmazon.com` (using Cyrillic 'а') may appear identical to `amazon.com` but represents a different domain.¶
¶
When configuring domain allow/block lists:¶
- Use ASCII-only domain names when possible¶
- Consider that URL parsers may handle Unicode normalization differently¶
- Test your domain filters with potential homograph variations¶
- Regularly audit your domain configurations for suspicious Unicode characters¶
</Warning>¶
¶
#### Content limits¶
¶
The `max_content_tokens` parameter limits the amount of content that will be included in the context. If the fetched content exceeds this limit, it will be truncated. This helps control token usage when fetching large documents.¶
¶
<Note>¶
The `max_content_tokens` parameter limit is approximate. The actual number of input tokens used can vary by a small amount.¶
</Note>¶
¶
#### 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.¶
¶
<Note>¶
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.¶
</Note>¶
¶
### Response¶
¶
Here's an example response structure:¶
¶
```json¶
{¶
"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¶
¶
<Note>¶
The web fetch tool caches results to improve performance and reduce redundant requests. This means the content returned may not always be 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.¶
</Note>¶
¶
For PDF documents, the content will be returned as base64-encoded data:¶
¶
```json¶
{¶
"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:¶
¶
```json¶
{¶
"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¶
import anthropic¶
¶
client = anthropic.Anthropic()¶
¶
response = client.messages.create(¶
model="claude-opus-4-6",¶
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:¶
1. Use web search to find relevant articles¶
2. Select the most promising results¶
3. Use web fetch to retrieve full content¶
4. Provide detailed analysis with citations¶
¶
## Prompt caching¶
¶
Web fetch works with [prompt caching](/docs/en/build-with-claude/prompt-caching). To enable prompt caching, add `cache_control` breakpoints in your request. Cached fetch results can be reused across conversation turns.¶
¶
```python¶
import anthropic¶
¶
client = anthropic.Anthropic()¶
¶
# First request with web fetch¶
messages = [¶
{¶
"role": "user",¶
"content": "Analyze this research paper: https://arxiv.org/abs/2024.12345",¶
}¶
]¶
¶
response1 = client.messages.create(¶
model="claude-opus-4-6",¶
max_tokens=1024,¶
messages=messages,¶
tools=[{"type": "web_fetch_20250910", "name": "web_fetch"}],¶
)¶
¶
# Add Claude's response to conversation¶
messages.append({"role": "assistant", "content": response1.content})¶
¶
# Second request with cache breakpoint¶
messages.append(¶
{¶
"role": "user",¶
"content": "What methodology does the paper use?",¶
"cache_control": {"type": "ephemeral"},¶
}¶
)¶
¶
response2 = client.messages.create(¶
model="claude-opus-4-6",¶
max_tokens=1024,¶
messages=messages,¶
tools=[{"type": "web_fetch_20250910", "name": "web_fetch"}],¶
)¶
¶
# The second response benefits from cached fetch results¶
print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")¶
```¶
¶
## Streaming¶
¶
With streaming enabled, fetch events are part of the stream with a pause during content retrieval:¶
¶
```json¶
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](/docs/en/build-with-claude/batch-processing). 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:¶
¶
```json¶
"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 (10KB): ~2,500 tokens¶
- Large documentation page (100KB): ~25,000 tokens ¶
- Research paper PDF (500KB): ~125,000 tokens