Herramienta de obtención web

La herramienta de obtención web permite a Claude recuperar contenido completo de páginas web y documentos PDF especificados.

La herramienta de obtención web está actualmente en beta. Para habilitarla, utiliza el encabezado beta web-fetch-2025-09-10 en tus solicitudes de API.

Por favor, utiliza este formulario para proporcionar comentarios sobre la calidad de las respuestas del modelo, la API en sí, o la calidad de la documentación.

Habilitar la herramienta de obtención web en entornos donde Claude procesa entrada no confiable junto con datos sensibles presenta riesgos de exfiltración de datos. Recomendamos usar esta herramienta solo en entornos confiables o cuando se manejan datos no sensibles.

Para minimizar los riesgos de exfiltración, Claude no puede construir dinámicamente URLs. Claude solo puede obtener URLs que hayan sido proporcionadas explícitamente por el usuario o que provengan de resultados previos de búsqueda web u obtención web. Sin embargo, aún existe un riesgo residual que debe considerarse cuidadosamente al usar esta herramienta.

Si la exfiltración de datos es una preocupación, considera:

Deshabilitar completamente la herramienta de obtención web
Usar el parámetro max_uses para limitar el número de solicitudes
Usar el parámetro allowed_domains para restringir a dominios seguros conocidos

Modelos compatibles

La obtención web está disponible en:

Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
Claude Sonnet 4 (claude-sonnet-4-20250514)
Claude Sonnet 3.7 (deprecated) (claude-3-7-sonnet-20250219)
Claude Haiku 4.5 (claude-haiku-4-5-20251001)
Claude Haiku 3.5 (deprecated) (claude-3-5-haiku-latest)
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)

Cómo funciona la obtención web

Cuando añades la herramienta de obtención web a tu solicitud de API:

Claude decide cuándo obtener contenido basándose en el prompt y las URLs disponibles.
La API recupera el contenido de texto completo de la URL especificada.
Para PDFs, se realiza extracción automática de texto.
Claude analiza el contenido obtenido y proporciona una respuesta con citas opcionales.

La herramienta de obtención web actualmente no admite sitios web renderizados dinámicamente a través de Javascript.

Cómo usar la obtención web

Proporciona la herramienta de obtención web en tu solicitud de API:

Definición de herramienta

La herramienta de obtención web admite los siguientes parámetros:

JSON

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

  // Opcional: Limita el número de obtenciones por solicitud
  "max_uses": 10,

  // Opcional: Solo obtiene de estos dominios
  "allowed_domains": ["example.com", "docs.example.com"],

  // Opcional: Nunca obtiene de estos dominios
  "blocked_domains": ["private.example.com"],

  // Opcional: Habilita citas para contenido obtenido
  "citations": {
    "enabled": true
  },

  // Opcional: Longitud máxima de contenido en tokens
  "max_content_tokens": 100000
}

Máximo de usos

El parámetro max_uses limita el número de obtenciones web realizadas. Si Claude intenta más obtenciones de las permitidas, el web_fetch_tool_result será un error con el código de error max_uses_exceeded. Actualmente no hay límite predeterminado.

Filtrado de dominios

Cuando uses filtros de dominio:

Los dominios no deben incluir el esquema HTTP/HTTPS (usa example.com en lugar de https://example.com)
Los subdominios se incluyen automáticamente (example.com cubre docs.example.com)
Se admiten subrrutas (example.com/blog)
Puedes usar allowed_domains o blocked_domains, pero no ambos en la misma solicitud.

Ten en cuenta que los caracteres Unicode en nombres de dominio pueden crear vulnerabilidades de seguridad a través de ataques de homografía, donde caracteres visualmente similares de diferentes scripts pueden eludir filtros de dominio. Por ejemplo, аmazon.com (usando la 'а' cirílica) puede parecer idéntico a amazon.com pero representa un dominio diferente.

Al configurar listas de permitidos/bloqueados de dominios:

Usa nombres de dominio solo ASCII cuando sea posible
Ten en cuenta que los analizadores de URL pueden manejar la normalización Unicode de manera diferente
Prueba tus filtros de dominio con variaciones potenciales de homografía
Audita regularmente tus configuraciones de dominio para caracteres Unicode sospechosos

Límites de contenido

El parámetro max_content_tokens limita la cantidad de contenido que se incluirá en el contexto. Si el contenido obtenido excede este límite, se truncará. Esto ayuda a controlar el uso de tokens al obtener documentos grandes.

El límite del parámetro max_content_tokens es aproximado. El número real de tokens de entrada utilizados puede variar en una pequeña cantidad.

Citas

A diferencia de la búsqueda web donde las citas siempre están habilitadas, las citas son opcionales para la obtención web. Establece "citations": {"enabled": true} para permitir que Claude cite pasajes específicos de documentos obtenidos.

Al mostrar salidas de API directamente a usuarios finales, las citas deben incluirse a la fuente original. Si realizas modificaciones en las salidas de API, incluyendo reprocesamiento y/o combinación con tu propio material antes de mostrarlas a usuarios finales, muestra citas según corresponda basándote en consulta con tu equipo legal.

Respuesta

Aquí hay una estructura de respuesta de ejemplo:

{
  "role": "assistant",
  "content": [
    // 1. Decisión de Claude de obtener
    {
      "type": "text",
      "text": "I'll fetch the content from the article to analyze it."
    },
    // 2. La solicitud de obtención
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01234567890abcdef",
      "name": "web_fetch",
      "input": {
        "url": "https://example.com/article"
      }
    },
    // 3. Resultados de obtención
    {
      "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. Análisis de Claude con citas (si está habilitado)
    {
      "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"
}

Resultados de obtención

Los resultados de obtención incluyen:

url: La URL que fue obtenida
content: Un bloque de documento que contiene el contenido obtenido
retrieved_at: Marca de tiempo de cuándo se recuperó el contenido

La herramienta de obtención web almacena en caché los resultados para mejorar el rendimiento y reducir solicitudes redundantes. Esto significa que el contenido devuelto puede no ser siempre la versión más reciente disponible en la URL. El comportamiento del caché se gestiona automáticamente y puede cambiar con el tiempo para optimizar diferentes tipos de contenido y patrones de uso.

Para documentos PDF, el contenido se devolverá como datos codificados en base64:

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

Errores

Cuando la herramienta de obtención web encuentra un error, la API de Claude devuelve una respuesta 200 (éxito) con el error representado en el cuerpo de la respuesta:

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

Estos son los códigos de error posibles:

invalid_input: Formato de URL inválido
url_too_long: La URL excede la longitud máxima (250 caracteres)
url_not_allowed: URL bloqueada por reglas de filtrado de dominio y restricciones del modelo
url_not_accessible: Error al obtener contenido (error HTTP)
too_many_requests: Límite de velocidad excedido
unsupported_content_type: Tipo de contenido no admitido (solo texto y PDF)
max_uses_exceeded: Máximo de usos de herramienta de obtención web excedido
unavailable: Ocurrió un error interno

Validación de URL

Por razones de seguridad, la herramienta de obtención web solo puede obtener URLs que hayan aparecido previamente en el contexto de la conversación. Esto incluye:

URLs en mensajes de usuario
URLs en resultados de herramientas del lado del cliente
URLs de resultados previos de búsqueda web u obtención web

La herramienta no puede obtener URLs arbitrarias que Claude genere o URLs de herramientas de servidor basadas en contenedor (Ejecución de Código, Bash, etc.).

Búsqueda y obtención combinadas

La obtención web funciona sin problemas con la búsqueda web para recopilación de información integral:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5",
    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}
        }
    ],
    extra_headers={
        "anthropic-beta": "web-fetch-2025-09-10"
    }
)

En este flujo de trabajo, Claude:

Usará búsqueda web para encontrar artículos relevantes
Seleccionará los resultados más prometedores
Usará obtención web para recuperar contenido completo
Proporcionará análisis detallado con citas

Almacenamiento en caché de prompts

La obtención web funciona con almacenamiento en caché de prompts. Para habilitar el almacenamiento en caché de prompts, añade puntos de ruptura cache_control en tu solicitud. Los resultados de obtención en caché pueden reutilizarse en turnos de conversación.

import anthropic

client = anthropic.Anthropic()

# Primera solicitud con obtención web
messages = [
    {
        "role": "user",
        "content": "Analyze this research paper: https://arxiv.org/abs/2024.12345"
    }
]

response1 = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_fetch_20250910",
        "name": "web_fetch"
    }],
    extra_headers={
        "anthropic-beta": "web-fetch-2025-09-10"
    }
)

# Añade la respuesta de Claude a la conversación
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Segunda solicitud con punto de ruptura de caché
messages.append({
    "role": "user",
    "content": "What methodology does the paper use?",
    "cache_control": {"type": "ephemeral"}
})

response2 = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_fetch_20250910",
        "name": "web_fetch"
    }],
    extra_headers={
        "anthropic-beta": "web-fetch-2025-09-10"
    }
)

# La segunda respuesta se beneficia de los resultados de obtención en caché
print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

Transmisión

Con la transmisión habilitada, los eventos de obtención son parte de la transmisión con una pausa durante la recuperación de contenido:

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

// Decisión de Claude de obtener

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

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

// Pausa mientras se ejecuta la obtención

// Resultados de obtención transmitidos
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..."}}}}}

// La respuesta de Claude continúa...

Solicitudes por lotes

Puedes incluir la herramienta de obtención web en la API de Lotes de Mensajes. Las llamadas de herramienta de obtención web a través de la API de Lotes de Mensajes se cotizan igual que las solicitudes de API de Mensajes regulares.

Uso y precios

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 (10KB): ~2,500 tokens
Large documentation page (100KB): ~25,000 tokens
Research paper PDF (500KB): ~125,000 tokens

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: web-fetch-2025-09-10" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5",
        "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
        }]
    }'