---
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.
---
Para saber cómo se aplica la "zero data retention" (retención cero de datos), o ZDR, a esta función, consulta [API y retención de datos](https://platform.claude.com/docs/es/manage-claude/api-and-data-retention).
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 de corte de conocimiento. La respuesta incluye citas de las fuentes extraídas 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 los modelos Claude 4.6 y 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, Google Cloud y Microsoft Foundry. La búsqueda web no está disponible para Mythos Preview en Amazon Bedrock ni en [Claude Platform on AWS](https://platform.claude.com/docs/es/build-with-claude/claude-platform-on-aws).
Para conocer la elegibilidad de la búsqueda web para Zero Data Retention 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 API de Models](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 a Claude los resultados. 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 que es actual, cambiante o que está 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 científicos 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
La activación se puede orientar mediante tu indicación del sistema: puedes animar a Claude a buscar con más facilidad o a preferir responder directamente. Para una restricción estricta, usa `max_uses` para limitar la cantidad de búsquedas por cada solicitud.
### 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 filtra primero 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) 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 Google Cloud, solo está disponible la herramienta de búsqueda web básica (sin filtrado dinámico). La búsqueda web no está disponible en Amazon Bedrock.
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: 2023-06-01" \
-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() { Role = Role.User, 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: '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: "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 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.
Estas configuraciones a nivel de organización en la Claude Console se aplican solo a las solicitudes de la Messages API. Las sesiones de [Claude Managed Agents](https://platform.claude.com/docs/es/managed-agents/overview) usan en su lugar las listas `allowed_domains` y `blocked_domains` por herramienta en el 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). Para una sesión en un entorno en la nube con redes `limited`, el `allowed_hosts` del entorno también se aplica a `web_search` y `web_fetch`; consulta [Redes](https://platform.claude.com/docs/es/managed-agents/environments#networking). Las listas por herramienta restringen aún más estas herramientas, dentro de los hosts que `allowed_hosts` permite.
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: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"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 1024 \
--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=1024,
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: 1024,
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 = 1024,
Messages = [new() { Role = Role.User, 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: 1024,
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(1024L)
.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: 1024,
messages: [
['role' => 'user', 'content' => "What's the weather in NYC?"],
],
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: "claude-opus-5-5",
max_tokens: 1024,
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 per request
"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 [Herramientas de servidor](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 la cantidad de búsquedas realizadas. Si Claude intenta más búsquedas de las permitidas, el `web_search_tool_result` es un error con el código de error `max_uses_exceeded`.
Las consultas factuales simples suelen usar de 1 a 3 búsquedas; la investigación comparativa o de múltiples entidades puede usar 10 o más. Para obtener orientación sobre cómo elegir un valor, consulta [Herramientas de servidor](https://platform.claude.com/docs/es/agents-and-tools/tool-use/server-tools).
### 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 las reglas completas 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 el 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 los códigos de país no admitidos 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 acepta un objeto `user_location` con los mismos campos. La API rechaza un código `country` no admitido con un error 400 cuando creas o actualizas el agente, o cuando creas o actualizas una sesión que proporciona la configuración. 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 de [ejecución de código](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool) completada en el mismo turno. Establece `"response_inclusion": "excluded"` para eliminar por completo de la respuesta esos pares anidados de `server_tool_use` y bloques de resultado, lo que reduce los costos de tokens de salida para flujos de trabajo agénticos que no necesitan devolver el contenido de búsqueda sin procesar al cliente. El valor predeterminado es `"full"`. Los resultados de llamadas directas, o de llamadas de ejecución de código que se pausaron antes de completarse, siempre se devuelven completos para que puedan enviarse de vuelta en el siguiente turno.
```json JSON
{
"tools": [
{
"type": "web_search_20260318",
"name": "web_search",
"response_inclusion": "excluded"
}
]
}
```
## Respuesta
Este es un ejemplo de la estructura de la 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 resultado 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 enviar de vuelta 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 turnos posteriores para restaurar los resultados de búsqueda en el contexto de Claude. Si `encrypted_content` falta o se modificó, 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 enviarse de vuelta en conversaciones de varios turnos
* `cited_text`: Hasta 150 caracteres del contenido citado
Los campos de cita de la búsqueda web `cited_text`, `title` y `url` no cuentan para el uso de tokens de entrada ni de salida.
Al mostrar las salidas de la API directamente a los usuarios finales, se deben incluir 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 igualmente 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 resultado. Una búsqueda que tiene éxito pero no encuentra resultados devuelve una lista `content` vacía, no un error.
Estos son los posibles códigos de error:
* `too_many_requests`: Se excedió el "rate limit" (límite de velocidad)
* `invalid_tool_input`: Parámetro de consulta de búsqueda no válido
* `max_uses_exceeded`: Se excedió el máximo de usos de la herramienta de búsqueda web
* `query_too_long`: La consulta excede 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 del asistente pausado 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 de herramientas paralelas, la API devuelve en su lugar `stop_reason: "tool_use"` y aún no ejecuta la búsqueda. Para continuar, devuelve los resultados de la herramienta 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 conocer 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, recibirás eventos de búsqueda como parte del stream. Habrá 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 executes
// 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 [Messages 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 Messages Batches API tienen el mismo precio que las de las solicitudes normales de la Messages API.
Para proteger la capacidad compartida, la Batches API limita las solicitudes de búsqueda web por organización, por lo que los lotes grandes con muchas búsquedas podrían 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 velocidad](https://platform.claude.com/usage/limits) de la Claude Console. Para solicitar un límite más alto, contacta a 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 Claude API por **$10 por cada 1,000 búsquedas**, más los costos estándar de tokens por el contenido generado por las búsquedas. Los resultados de búsqueda web recuperados 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. Si ocurre un error durante la búsqueda web, esta no se facturará.
## Próximos pasos
Obtén y lee contenido de URL específicas para ampliar el contexto de Claude con contenido web en vivo.
Trabaja con herramientas ejecutadas por Anthropic: bloques server\_tool\_use, continuación de pause\_turn y filtrado de dominios.
Directorio de herramientas proporcionadas por Anthropic y referencia de las propiedades opcionales de definición de herramientas.