---
title: Herramienta de búsqueda web
url: https://platform.claude.com/docs/es/agents-and-tools/tool-use/web-search-tool
description: Dale a Claude acceso a contenido web actual con fuentes citadas, filtrado dinámico opcional y controles de dominio.
featureMetadata:
status: stable
zdr:
eligibility: eligible
note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). Resultados de búsqueda web en tiempo real devueltos en la respuesta de la API. El filtrado dinámico de la búsqueda web no es elegible para ZDR ni HIPAA.
supportedModels:
- claude-fable-5-2
- claude-mythos-5-2
- claude-fable-5-1
- claude-mythos-5-1
- claude-fable-5
- claude-mythos-5
- claude-mythos-preview
- claude-opus-5-5
- claude-opus-5
- claude-sonnet-5-5
- claude-sonnet-5
- claude-haiku-5-5
- claude-haiku-4-5-20251001
- claude-opus-4-8
- claude-opus-4-7
- claude-opus-4-6
- claude-sonnet-4-6
- claude-opus-4-5-20251101
- claude-sonnet-4-5-20250929
supportedPlatforms:
Claude API: stable
Claude Platform on AWS: stable
Claude Models on Google Cloud (Anthropic managed): stable
Claude Models on Google Cloud (Google managed):
availability: stable
note: Solo la herramienta básica de búsqueda web (`web_search_20250305`), sin filtrado dinámico.
Microsoft Foundry:
availability: stable
note: Solo la herramienta básica de búsqueda web (`web_search_20250305`), sin filtrado dinámico.
---
**Compatibilidad con la API**: El uso varía según el producto.
* **Messages API**: Añade una herramienta `web_search` a las `tools` de la solicitud. Configuraciones como `max_uses`, las listas de dominios y `user_location` se establecen en esa herramienta.
* **Managed Agents**: Activada de forma predeterminada en el conjunto de herramientas del agente, sin `max_uses`, `citations` ni `cache_control`.
La herramienta de búsqueda web le da a Claude acceso directo a contenido web en tiempo real, lo que le permite responder preguntas con información actualizada más allá de su fecha límite de conocimiento. La respuesta incluye citas de las fuentes obtenidas de los resultados de búsqueda.
Con `web_search_20260209` y versiones posteriores, Claude puede escribir y ejecutar código que filtra los resultados de búsqueda antes de que lleguen a la “context window” (ventana de contexto) (**filtrado dinámico**), conservando solo la información relevante. El filtrado dinámico está disponible con Claude 4.6 y modelos posteriores y con [Claude Mythos Preview](https://anthropic.com/glasswing).
Hay tres versiones disponibles de la herramienta de búsqueda web:
* `web_search_20250305`: búsqueda web básica
* `web_search_20260209`: agrega [filtrado dinámico](https://platform.claude.com/docs/es/agents-and-tools/tool-use/web-search-tool#dynamic-filtering)
* `web_search_20260318`: agrega control de [inclusión en la respuesta](https://platform.claude.com/docs/es/agents-and-tools/tool-use/web-search-tool#response-inclusion) para flujos de trabajo agénticos
Los ejemplos de esta página usan `web_search_20250305` para la búsqueda básica y `web_search_20260318` para el filtrado dinámico.
Para [Claude Mythos Preview](https://anthropic.com/glasswing), la búsqueda web es compatible con la Claude API, Claude Models on Google Cloud (Google managed) y Microsoft Foundry.
Para conocer la elegibilidad de la búsqueda web para la retención cero de datos y la configuración relacionada de `allowed_callers`, consulta [Herramientas de servidor](https://platform.claude.com/docs/es/agents-and-tools/tool-use/server-tools#zdr-and-allowed-callers).
Para conocer la compatibilidad de modelos, consulta la [Referencia de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-reference).
Para comprobar si un modelo acepta la búsqueda web antes de enviar una solicitud, lee su valor `capabilities.server_tools.web_search.supported` desde la Models API. [Uso de la Models API](https://platform.claude.com/docs/es/models/overview#using-the-models-api) describe el campo.
## Cómo funciona la búsqueda web
Cuando agregas la herramienta de búsqueda web a tu solicitud de API:
1. Claude determina cuándo buscar según el prompt.
2. La API ejecuta las búsquedas y le proporciona los resultados a Claude. Este proceso puede repetirse varias veces a lo largo de una sola solicitud.
3. Al final de su turno, Claude proporciona una respuesta final con fuentes citadas.
### Cuándo busca Claude
Claude busca cuando la solicitud depende de información actual, cambiante o fuera de sus datos de entrenamiento:
* Eventos, noticias o anuncios recientes
* Precios, tasas, puntuaciones o estadísticas actuales
* Información sobre organizaciones, personas o productos específicos que podría haber cambiado
* Solicitudes explícitas de buscar o consultar algo
Claude responde directamente sin buscar cuando la solicitud se basa en conocimiento estable:
* Hechos establecidos, matemáticas, fundamentos de ciencias o conceptos de programación
* Escritura creativa o lluvia de ideas
* Análisis de contenido ya proporcionado en la conversación
* Turnos conversacionales y saludos
Puedes orientar cuándo se activa la búsqueda mediante tu “system prompt” (indicación del sistema): puedes animar a Claude a buscar con más facilidad o a preferir responder directamente. Para imponer un límite, usa [`max_uses`](https://platform.claude.com/docs/es/agents-and-tools/tool-use/web-search-tool#max-uses) para limitar el número de búsquedas en un turno.
### Filtrado dinámico
Con la búsqueda web básica, cada resultado de búsqueda se carga en la ventana de contexto de Claude, y gran parte de ese contenido puede ser irrelevante para la solicitud. Con `web_search_20260209` o posterior, Claude en cambio escribe y ejecuta código que primero filtra los resultados, de modo que solo el contenido relevante llega a la ventana de contexto. Esto reduce el uso de tokens en solicitudes con muchas búsquedas.
El filtrado dinámico ejecuta la búsqueda web desde dentro de la [ejecución de código](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool): en `web_search_20260209` y posteriores, el campo `allowed_callers` de la herramienta tiene como valor predeterminado `["code_execution_20260120"]`, y cuando se ejecuta el filtrado dinámico, la API aprovisiona automáticamente la ejecución de código que necesita para la solicitud. No necesitas agregar tú mismo la herramienta de ejecución de código a `tools`. No hay cargos adicionales por las llamadas de ejecución de código realizadas de esta manera más allá de los costos estándar de tokens.
Para llamar a la búsqueda web directamente, sin filtrado dinámico, establece `allowed_callers: ["direct"]`. Los modelos que no admiten la llamada programática de herramientas requieren esta configuración. Sin ella, la API devuelve un error 400 que te indica que la establezcas.
La herramienta de búsqueda web (con y sin filtrado dinámico) está disponible en la Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/es/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/es/build-with-claude/claude-models-on-google-cloud/anthropic-managed) y [Microsoft Foundry](https://platform.claude.com/docs/es/build-with-claude/claude-in-microsoft-foundry). En Microsoft Foundry, las implementaciones [alojadas en Azure](https://platform.claude.com/docs/es/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure) solo admiten la herramienta de búsqueda web básica (`web_search_20250305`, sin filtrado dinámico). Las implementaciones alojadas en Anthropic admiten todas las versiones. En Claude Models on Google Cloud (Google managed), solo está disponible la herramienta de búsqueda web básica (sin filtrado dinámico).
Los siguientes ejemplos usan `web_search_20260318`:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"messages": [
{
"role": "user",
"content": "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio."
}
],
"tools": [{
"type": "web_search_20260318",
"name": "web_search"
}]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 4096
messages:
- role: user
content: >-
Search for the current prices of AAPL and GOOGL, then calculate
which has a better P/E ratio.
tools:
- type: web_search_20260318
name: web_search
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.",
}
],
tools=[{"type": "web_search_20260318", "name": "web_search"}],
)
print(response)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
messages: [
{
role: "user",
content:
"Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio."
}
],
tools: [{ type: "web_search_20260318", name: "web_search" }]
});
console.log(response);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Messages = [new UserMessageParam { Content = "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio." }],
Tools = [new ToolUnion(new WebSearchTool20260318())]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.")),
},
Tools: []anthropic.ToolUnionParam{
{OfWebSearchTool20260318: &anthropic.WebSearchTool20260318Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.messages.WebSearchTool20260318;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.addUserMessage("Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.")
.addTool(WebSearchTool20260318.builder().build())
.build();
Message response = client.messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.'],
],
model: Model::CLAUDE_OPUS_5_5,
tools: [
[
'type' => 'web_search_20260318',
'name' => 'web_search',
],
],
);
echo $message;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 4096,
messages: [
{ role: "user", content: "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio." }
],
tools: [{
type: "web_search_20260318",
name: "web_search"
}]
)
puts message
```
## Cómo usar la búsqueda web
La búsqueda web está habilitada para tu organización a menos que un administrador la haya deshabilitado en la [Claude Console](https://platform.claude.com/settings/capabilities), donde también puede restringir en qué dominios busca. Si está deshabilitada, una solicitud a la Messages API que incluya la herramienta falla con un error 400 `invalid_request_error` que indica que la búsqueda web no está habilitada, en lugar de un [código de error](https://platform.claude.com/docs/es/agents-and-tools/tool-use/web-search-tool#errors) dentro de un resultado de búsqueda.
Para saber cómo se aplica la configuración de búsqueda web de tu organización en las sesiones de Claude Managed Agents, consulta [Restringir los dominios de búsqueda web y obtención web](https://platform.claude.com/docs/es/managed-agents/tools-web-restrictions).
Proporciona la herramienta de búsqueda web en tu solicitud de API:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"messages": [
{
"role": "user",
"content": "What is the weather in NYC?"
}
],
"tools": [{
"type": "web_search_20250305",
"name": "web_search",
"max_uses": 5
}]
}'
```
```bash CLI
ant messages create \
--model claude-opus-5-5 \
--max-tokens 4096 \
--message '{role: user, content: What is the weather in NYC?}' \
--tool '{type: web_search_20250305, name: web_search, max_uses: 5}'
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[{"role": "user", "content": "What's the weather in NYC?"}],
tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}],
)
print(response)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
messages: [
{
role: "user",
content: "What's the weather in NYC?"
}
],
tools: [
{
type: "web_search_20250305",
name: "web_search",
max_uses: 5
}
]
});
console.log(response);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Messages = [new UserMessageParam { Content = "What's the weather in NYC?" }],
Tools = [new ToolUnion(new WebSearchTool20250305() { MaxUses = 5 })]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather in NYC?")),
},
Tools: []anthropic.ToolUnionParam{
{OfWebSearchTool20250305: &anthropic.WebSearchTool20250305Param{
MaxUses: anthropic.Int(5),
}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.messages.WebSearchTool20250305;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.addUserMessage("What's the weather in NYC?")
.addTool(WebSearchTool20250305.builder()
.maxUses(5L)
.build())
.build();
Message response = client.messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => "What's the weather in NYC?"],
],
model: Model::CLAUDE_OPUS_5_5,
tools: [
[
'type' => 'web_search_20250305',
'name' => 'web_search',
'max_uses' => 5,
],
],
);
echo $message;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 4096,
messages: [
{ role: "user", content: "What's the weather in NYC?" }
],
tools: [{
type: "web_search_20250305",
name: "web_search",
max_uses: 5
}]
)
puts message
```
## Definición de la herramienta
La herramienta de búsqueda web admite los siguientes parámetros:
```json JSON
{
"type": "web_search_20250305",
"name": "web_search",
// Optional: Limit the number of searches
"max_uses": 5,
// Optional: Only include results from these domains.
// Use allowed_domains or blocked_domains, not both.
"allowed_domains": ["example.com", "trusteddomain.org"],
// Optional: Never include results from these domains
"blocked_domains": ["untrustedsource.com"],
// Optional: Localize search results
"user_location": {
"type": "approximate",
"city": "San Francisco",
"region": "California",
"country": "US",
"timezone": "America/Los_Angeles"
}
}
```
Todas las versiones de la herramienta de búsqueda web aceptan `allowed_callers`, que controla si Claude llama a la búsqueda web directamente o desde la ejecución de código mediante el [filtrado dinámico](https://platform.claude.com/docs/es/agents-and-tools/tool-use/web-search-tool#dynamic-filtering). En `web_search_20260209` y posteriores, su valor predeterminado es `["code_execution_20260120"]` en lugar de `["direct"]`. Consulta [ZDR y allowed\_callers](https://platform.claude.com/docs/es/agents-and-tools/tool-use/server-tools#zdr-and-allowed-callers) para saber cómo configurarlo. `web_search_20260318` y posteriores también aceptan [`response_inclusion`](https://platform.claude.com/docs/es/agents-and-tools/tool-use/web-search-tool#response-inclusion).
### Usos máximos
El parámetro `max_uses` limita el número de búsquedas en un solo turno. Las consultas sobre un solo hecho suelen usar de 1 a 3 búsquedas; la investigación comparativa o sobre varias entidades puede usar 10 o más.
Las búsquedas fallidas cuentan para el límite. Si Claude llama a la búsqueda web directamente más veces de las permitidas, el `web_search_tool_result` es un error con el código de error `max_uses_exceeded`. Si Claude llama a la búsqueda web desde la ejecución de código más veces de las permitidas, la ejecución de código termina con un error.
Un turno puede abarcar varias solicitudes. Una solicitud continúa un turno cuando se reanuda después de [`pause_turn`](https://platform.claude.com/docs/es/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn) o cuando su último mensaje contiene solo bloques `tool_result`. Las búsquedas de solicitudes anteriores en ese turno cuentan para el límite, a menos que Claude las haya ejecutado desde la ejecución de código mediante el [filtrado dinámico](https://platform.claude.com/docs/es/agents-and-tools/tool-use/web-search-tool#dynamic-filtering).
### Filtrado de dominios
Proporciona `allowed_domains` o `blocked_domains`, no ambos. Si una solicitud incluye ambos, la API devuelve un error 400. Las entradas son dominios simples con una ruta opcional, por ejemplo `example.com` o `example.com/blog`, sin esquema.
Para conocer todas las reglas de filtrado de dominios, consulta [Filtrado de dominios](https://platform.claude.com/docs/es/agents-and-tools/tool-use/server-tools#domain-filtering) en la guía de Herramientas de servidor.
En [Claude Managed Agents](https://platform.claude.com/docs/es/managed-agents/overview), establece estos campos en la entrada `web_search` del conjunto de herramientas del agente; consulta [Restringir los dominios de búsqueda web y obtención web](https://platform.claude.com/docs/es/managed-agents/tools-web-restrictions).
### Localización
El parámetro `user_location` te permite localizar los resultados de búsqueda según la ubicación de un usuario. Proporciona al menos uno de `city`, `region`, `country` o `timezone`.
* `type`: El tipo de ubicación (debe ser `approximate`)
* `city`: El nombre de la ciudad
* `region`: La región o estado
* `country`: El código de país de dos letras [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) (la API rechaza un código no admitido con un error 400)
* `timezone`: El [ID de zona horaria de IANA](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
En Claude Managed Agents, la entrada `web_search` del conjunto de herramientas del agente también acepta `user_location`; consulta la [configuración de las herramientas web](https://platform.claude.com/docs/es/managed-agents/tools-web-restrictions#settings).
### Inclusión en la respuesta
Requiere `web_search_20260318` o posterior.
El parámetro `response_inclusion` controla cómo aparecen los bloques de resultados de búsqueda en la respuesta de la API cuando el resultado fue consumido por una llamada completada de [ejecución de código](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool) en la misma respuesta. Establece `"response_inclusion": "excluded"` para eliminar por completo de la respuesta esos pares anidados de bloques `server_tool_use` y de resultado, para los flujos de trabajo agénticos que no necesitan el contenido de búsqueda sin procesar. El uso de tokens no se ve afectado, porque Claude lee la salida del código en lugar de estos bloques. El valor predeterminado es `"full"`. La API siempre devuelve completos los resultados de llamadas directas, o de llamadas de ejecución de código que se pausaron antes de completarse, para que puedas enviarlos de vuelta en la siguiente solicitud.
```json JSON
{
"tools": [
{
"type": "web_search_20260318",
"name": "web_search",
"response_inclusion": "excluded"
}
]
}
```
## Respuesta
Este es un ejemplo de la estructura de respuesta:
```json Output
{
"role": "assistant",
"content": [
// 1. Claude's decision to search
{
"type": "text",
"text": "I'll search for when Claude Shannon was born."
},
// 2. The search query used
{
"type": "server_tool_use",
"id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
"name": "web_search",
"input": {
"query": "claude shannon birth date"
}
},
// 3. Search results
{
"type": "web_search_tool_result",
"tool_use_id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
"content": [
{
"type": "web_search_result",
"url": "https://en.wikipedia.org/wiki/Claude_Shannon",
"title": "Claude Shannon - Wikipedia",
"encrypted_content": "EqgfCioIARgBIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
"page_age": "April 30, 2025"
}
]
},
{
"text": "Based on the search results, ",
"type": "text"
},
// 4. Claude's response with citations
{
"text": "Claude Shannon was born on April 30, 1916, in Petoskey, Michigan",
"type": "text",
"citations": [
{
"type": "web_search_result_location",
"url": "https://en.wikipedia.org/wiki/Claude_Shannon",
"title": "Claude Shannon - Wikipedia",
"encrypted_index": "Eo8BCioIAhgBIiQyYjQ0OWJmZi1lNm..",
"cited_text": "Claude Elwood Shannon (April 30, 1916 – February 24, 2001) was an American mathematician, electrical engineer, computer scientist, cryptographer and i..."
}
]
}
],
"id": "msg_a930390d3a",
"usage": {
"input_tokens": 6039,
"output_tokens": 931,
"server_tool_use": {
"web_search_requests": 1
}
},
"stop_reason": "end_turn"
}
```
Este ejemplo muestra una búsqueda directa. Cuando una búsqueda se ejecuta mediante el [filtrado dinámico](https://platform.claude.com/docs/es/agents-and-tools/tool-use/web-search-tool#dynamic-filtering), la respuesta también contiene los bloques de resultados de la [herramienta de ejecución de código](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool), y cada par anidado de `server_tool_use` y `web_search_tool_result` lleva un campo `caller` que identifica la llamada de ejecución de código que lo realizó.
### Resultados de búsqueda
Los resultados de búsqueda incluyen:
* `url`: La URL de la página de origen
* `title`: El título de la página de origen
* `page_age`: Cuándo se actualizó el sitio por última vez
* `encrypted_content`: Contenido cifrado que debes devolver en conversaciones de varios turnos
Para continuar una conversación que contiene resultados de búsqueda, envía de vuelta los bloques de contenido del asistente exactamente como los recibiste, incluido el `encrypted_content` de cada resultado. La API descifra ese contenido en solicitudes posteriores para restaurar los resultados de búsqueda en el contexto de Claude. Si `encrypted_content` falta o se modifica, la solicitud falla con un error de validación 400.
### Citas
Las citas siempre están habilitadas para la búsqueda web, y cada `web_search_result_location` incluye:
* `url`: La URL de la fuente citada
* `title`: El título de la fuente citada
* `encrypted_index`: Una referencia que debe devolverse en conversaciones de varios turnos
* `cited_text`: Hasta 150 caracteres del contenido citado
Los campos de citas de búsqueda web `cited_text`, `title` y `url` no cuentan para el uso de tokens de entrada ni de salida.
Cuando muestres las salidas de la API directamente a los usuarios finales, se deben incluir las citas a la fuente original. Si realizas modificaciones a las salidas de la API, incluso al reprocesarlas o combinarlas con tu propio material antes de mostrarlas a los usuarios finales, muestra las citas según corresponda, con base en la consulta con tu equipo legal.
### Errores
Cuando la herramienta de búsqueda web encuentra un error (como alcanzar los límites de velocidad), la Claude API aun así devuelve una respuesta 200 (éxito). El error se representa dentro del cuerpo de la respuesta con la siguiente estructura:
```json Output
{
"type": "web_search_tool_result",
"tool_use_id": "srvtoolu_a93jad",
"content": {
"type": "web_search_tool_result_error",
"error_code": "max_uses_exceeded"
}
}
```
En caso de error, `content` es un único objeto de error en lugar de una lista de bloques de resultados. Una búsqueda que se realiza correctamente pero no obtiene resultados devuelve una lista `content` vacía, no un error.
Estos son los posibles códigos de error:
* `too_many_requests`: Se superó el límite de velocidad
* `invalid_tool_input`: Parámetro de consulta de búsqueda no válido
* `max_uses_exceeded`: Se superó el número máximo de usos de la herramienta de búsqueda web
* `query_too_long`: La consulta supera la longitud máxima
* `request_too_large`: La solicitud de búsqueda es demasiado grande, normalmente debido a una lista larga de filtros de dominio
* `unavailable`: Ocurrió un error interno
### Motivo de detención `pause_turn`
La API puede pausar un turno de búsqueda de larga duración y devolver `stop_reason: "pause_turn"`. Para continuar, envía de vuelta el mensaje pausado del asistente sin cambios en una nueva solicitud.
Si Claude llama a la búsqueda web y a una de tus herramientas de cliente en el mismo grupo de llamadas paralelas a herramientas, la API devuelve `stop_reason: "tool_use"` en su lugar y aún no ejecuta la búsqueda. Para continuar, devuelve los resultados de las herramientas de cliente, y la API ejecuta la búsqueda en la siguiente solicitud. Consulta [Combinar herramientas de servidor y herramientas de cliente en un turno](https://platform.claude.com/docs/es/agents-and-tools/tool-use/server-tools#mixing-server-tools-and-client-tools-in-one-turn).
Para el bucle del lado del servidor y el manejo de `pause_turn`, consulta [El bucle del lado del servidor y pause\_turn](https://platform.claude.com/docs/es/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn) en la guía de Herramientas de servidor.
## Almacenamiento en caché de prompts
Para almacenar en caché las definiciones de herramientas entre turnos, consulta [Uso de herramientas con almacenamiento en caché de prompts](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-use-with-prompt-caching).
## Streaming
Con el streaming habilitado, recibes eventos de búsqueda como parte del stream. Hay una pausa mientras se ejecuta la búsqueda:
```sse 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 search
event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_search"}}
// Search query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}}
// Pause while search runs
// Search results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "web_search_result", "title": "Quantum Computing Breakthroughs in 2025", "url": "https://example.com"}]}}
// Claude's response with citations (omitted in this example)
```
## Solicitudes por lotes
Puedes incluir la herramienta de búsqueda web en la [Message Batches API](https://platform.claude.com/docs/es/build-with-claude/batch-processing). Las llamadas a la herramienta de búsqueda web a través de la Message Batches API tienen el mismo precio que las de las solicitudes normales a la Messages API.
Para proteger la capacidad compartida, la Batches API limita las solicitudes de búsqueda web de cada organización, por lo que los lotes grandes con muchas búsquedas pueden tardar más en completarse. Puedes ver el límite de velocidad de búsqueda web de tu organización en la página [Límites de frecuencia](https://platform.claude.com/usage/limits) de la Claude Console. Para solicitar un límite más alto, contacta al equipo de ventas desde esa página.
## Uso y precios
El uso de la búsqueda web se cobra además del uso de tokens:
```json
{
"usage": {
"input_tokens": 105,
"output_tokens": 6039,
"cache_read_input_tokens": 7123,
"cache_creation_input_tokens": 7345,
"server_tool_use": {
"web_search_requests": 1
}
}
}
```
La búsqueda web está disponible en la API de Claude por **$10 USD por cada 1,000 búsquedas**, más los costos estándar de tokens por el contenido generado por la búsqueda. Los resultados de búsqueda web obtenidos a lo largo de una conversación se cuentan como tokens de entrada, tanto en las iteraciones de búsqueda ejecutadas durante un solo turno como en los turnos posteriores de la conversación.
Cada búsqueda web cuenta como un uso, independientemente del número de resultados devueltos. Una búsqueda web que falla con un error no se factura.
## Próximos pasos
Obtén y lee contenido de URLs específicas para ampliar el contexto de Claude con contenido web en vivo.
Trabaja con herramientas que ejecuta Anthropic: bloques `server_tool_use`, continuación con `pause_turn` y filtrado de dominios.
Directorio de herramientas proporcionadas por Anthropic y referencia de las propiedades opcionales de definición de herramientas.
## Disponibilidad
Herramienta de búsqueda web está disponible en todos los modelos y es elegible para retención de datos cero y preparación para HIPAA.
### Compatibilidad con la API
#### [Messages API](https://platform.claude.com/docs/es/build-with-claude/working-with-messages)
* Disponibilidad: Disponible
* Uso: Añade una herramienta `web_search` a las `tools` de la solicitud. Configuraciones como `max_uses`, las listas de dominios y `user_location` se establecen en esa herramienta.
| Estado | Plataformas en la nube |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Disponible | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/es/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/es/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Microsoft Foundry (hosted on Anthropic)](https://platform.claude.com/docs/es/build-with-claude/claude-in-microsoft-foundry) |
| Disponible1 | [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/es/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry (hosted on Azure)](https://platform.claude.com/docs/es/build-with-claude/claude-in-microsoft-foundry) |
1. Solo la herramienta básica de búsqueda web (`web_search_20250305`), sin filtrado dinámico.
#### [Managed Agents](https://platform.claude.com/docs/es/managed-agents/overview)
* Disponibilidad: Disponible
* Uso: Forma parte del conjunto de herramientas del agente y está activada de forma predeterminada una vez que se añade el conjunto de herramientas. Las listas de dominios y `user_location` se establecen en la entrada `web_search` del conjunto de herramientas; `max_uses`, `citations` y `cache_control` no están disponibles.
| Estado | Plataformas en la nube |
| ---------- | ------------------------------------------------------------------------------------------------------------------ |
| Disponible | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/es/build-with-claude/claude-platform-on-aws) |
### Manejo de datos
[Descripción general del manejo de datos](https://platform.claude.com/docs/es/manage-claude/api-and-data-retention#feature-eligibility)
| Elemento | Retención de datos cero | HIPAA |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Estado | Elegible (excluye [Modelos cubiertos](https://platform.claude.com/docs/es/manage-claude/api-and-data-retention#model-specific-data-retention-requirements)) | Elegible |
| Detalles | Resultados de búsqueda web en tiempo real devueltos en la respuesta de la API. El filtrado dinámico de la búsqueda web no es elegible para ZDR ni HIPAA. | El filtrado dinámico de la búsqueda web no es elegible para ZDR ni HIPAA. |
Endpoints aplicables:
* `/v1/messages` con la herramienta `web_search`