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, usa el encabezado beta web-fetch-2025-09-10 en tus solicitudes de API.

Por favor usa 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 plantea 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 URLs dinámicamente. Claude solo puede obtener URLs que han sido proporcionadas explícitamente por el usuario o que provienen 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 Opus 4.1 (claude-opus-4-1-20250805)
  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
  • Claude Sonnet 3.5 v2 (obsoleto) (claude-3-5-sonnet-latest)
  • Claude Haiku 3.5 (claude-3-5-haiku-latest)

​
Cómo funciona la obtención web

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

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

​
Cómo usar la obtención web

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

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-opus-4-1-20250805",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "Por favor analiza el contenido en https://example.com/article"
            }
        ],
        "tools": [{
            "type": "web_fetch_20250910",
            "name": "web_fetch",
            "max_uses": 5
        }]
    }'

​
Definición de herramienta

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

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

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

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

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

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

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

​
Usos máximos

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

Al usar 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 subpaths (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 homográficos, donde caracteres visualmente similares de diferentes scripts pueden eludir los filtros de dominio. Por ejemplo, аmazon.com (usando ‘а’ cirílica) puede parecer idéntico a amazon.com pero representa un dominio diferente.

Al configurar listas de permitir/bloquear dominios:

  • Usa nombres de dominio solo ASCII cuando sea posible
  • Considera que los analizadores de URL pueden manejar la normalización Unicode de manera diferente
  • Prueba tus filtros de dominio con posibles variaciones homográficas
  • 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 resultados web o información contenida en resultados web a usuarios finales, las citas en línea deben hacerse claramente visibles y clicables en tu interfaz de usuario.

​
Respuesta

Aquí hay un ejemplo de estructura de respuesta:

{
  "role": "assistant",
  "content": [
    // 1. Decisión de Claude de obtener
    {
      "type": "text",
      "text": "Obtendré el contenido del artículo para analizarlo."
    },
    // 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": "Contenido de texto completo del artículo..."
          },
          "title": "Título del Artículo",
          "citations": {"enabled": true}
        },
        "retrieved_at": "2025-08-25T10:30:00Z"
      }
    },
    // 4. Análisis de Claude con citas (si están habilitadas)
    {
      "text": "Basándose en el artículo, ",
      "type": "text"
    },
    {
      "text": "el argumento principal presentado es que la inteligencia artificial transformará la atención médica",
      "type": "text",
      "citations": [
        {
          "type": "char_location",
          "document_index": 0,
          "document_title": "Título del Artículo",
          "start_char_index": 1234,
          "end_char_index": 1456,
          "cited_text": "La inteligencia artificial está preparada para revolucionar la prestación de atención médica..."
        }
      ]
    }
  ],
  "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 cuando el contenido fue recuperado

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 de 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 Anthropic 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 posibles códigos de error:

  • invalid_input: Formato de URL inválido
  • url_too_long: 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: Falló al obtener contenido (error HTTP)
  • too_many_requests: Límite de velocidad excedido
  • unsupported_content_type: Tipo de contenido no compatible (solo texto y PDF)
  • max_uses_exceeded: Usos máximos de herramienta de obtención web excedidos
  • unavailable: Ocurrió un error interno

​
Validación de URL

Por razones de seguridad, la herramienta de obtención web solo puede obtener URLs que han 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 integral de información:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Encuentra artículos recientes sobre computación cuántica y analiza el más relevante en detalle"
        }
    ],
    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:

  1. Usará búsqueda web para encontrar artículos relevantes
  2. Seleccionará los resultados más prometedores
  3. Usará obtención web para recuperar contenido completo
  4. 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, agrega puntos de interrupción cache_control en tu solicitud. Los resultados de obtención almacenados en caché pueden reutilizarse a través de turnos de conversación.

import anthropic

client = anthropic.Anthropic()

# Primera solicitud con obtención web
messages = [
    {
        "role": "user",
        "content": "Analiza este artículo de investigación: https://arxiv.org/abs/2024.12345"
    }
]

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

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

# Segunda solicitud con punto de interrupción de caché
messages.append({
    "role": "user",
    "content": "¿Qué metodología usa el artículo?",
    "cache_control": {"type": "ephemeral"}
})

response2 = client.messages.create(
    model="claude-opus-4-1-20250805",
    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 resultados de obtención almacenados en caché
print(f"Tokens de lectura de caché: {response2.usage.get('cache_read_input_tokens', 0)}")

​
Transmisión

Con la transmisión habilitada, los eventos de obtención son parte del flujo 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 de obtención 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": "Contenido del artículo..."}}}}}

// 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 tienen el mismo precio que las de las solicitudes regulares de la API de Mensajes.

​
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 Anthropic 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