El “batch processing” (procesamiento por lotes) es un enfoque poderoso para gestionar grandes volúmenes de solicitudes de manera eficiente. En lugar de procesar las solicitudes una a la vez con respuestas inmediatas, el procesamiento por lotes te permite enviar varias solicitudes juntas para su procesamiento asíncrono. Este patrón es especialmente útil cuando:

• Necesitas procesar grandes volúmenes de datos
• No se requieren respuestas inmediatas
• Quieres optimizar la eficiencia de costos
• Estás ejecutando evaluaciones o análisis a gran escala

La Message Batches API implementa este patrón.

Message Batches API

La Message Batches API es una forma poderosa y rentable de procesar de forma asíncrona grandes volúmenes de solicitudes de MessagesVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver.. Este enfoque es muy adecuado para tareas que no requieren respuestas inmediatas; la mayoría de los lotes terminan en menos de 1 hora, a la vez que se reducen los costos en un 50 por ciento y aumenta el “throughput” (rendimiento).

Además de esta guía, puedes explorar directamente la referencia de la APIVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver..

Cómo funciona la Message Batches API

Cuando envías una solicitud a la Message Batches API:

1. El sistema crea un nuevo lote de mensajes con las solicitudes de Messages proporcionadas.
2. Luego, el lote se procesa de forma asíncrona, y cada solicitud se gestiona de forma independiente.
3. Puedes consultar el estado del lote y recuperar los resultados cuando el procesamiento haya terminado para todas las solicitudes.

Esto es especialmente útil para operaciones masivas que no requieren resultados inmediatos, como:

• Evaluaciones a gran escala: procesa miles de casos de prueba de manera eficiente.
• Moderación de contenido: analiza grandes volúmenes de contenido generado por usuarios de forma asíncrona.
• Análisis de datos: genera información o resúmenes para grandes conjuntos de datos.
• Generación masiva de contenido: crea grandes cantidades de texto para diversos fines (por ejemplo, descripciones de productos, resúmenes de artículos).

Limitaciones de los lotes

• Un lote de mensajes está limitado a 100,000 solicitudes de Message o a 256 MB de tamaño, lo que se alcance primero.
• El sistema procesa cada lote lo más rápido posible, y la mayoría de los lotes se completan en 1 hora. Puedes acceder a los resultados del lote cuando todos los mensajes se hayan completado o después de 24 horas, lo que ocurra primero. Los lotes expiran si el procesamiento no se completa en 24 horas.
• Los resultados de los lotes están disponibles durante 29 días después de su creación. Después de eso, aún puedes ver el lote, pero sus resultados ya no están disponibles para descargar.
• Los lotes están limitados a un Workspace en la Claude Console. Puedes ver todos los lotes (y sus resultados) que se crearon dentro del Workspace en el que se ejecuta tu solicitud.
• Los límites de velocidad se aplican tanto a las solicitudes HTTP de la Batches API como a la cantidad de solicitudes dentro de un lote que esperan ser procesadas. Consulta Límites de velocidad de la Message Batches API. Además, el procesamiento podría ralentizarse según la demanda actual y tu volumen de solicitudes. En ese caso, es posible que veas más solicitudes que expiran después de 24 horas.
• Debido al alto rendimiento y al procesamiento concurrente, los lotes pueden exceder ligeramente el límite de gasto configurado en la Claude Console para tu Workspace.
• Cada solicitud en un lote debe tener un max_tokensVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver. de al menos 1. max_tokens: 0 (precalentamiento de caché) no es compatible dentro de un lote, porque una entrada de caché efímera escrita durante el procesamiento por lotes probablemente expiraría antes de que se ejecute la solicitud posterior.

Modelos compatibles

Todos los modelos activos son compatibles con la Message Batches API.

Qué se puede procesar por lotes

Casi cualquier solicitud que puedas hacer a la Messages API puede incluirse en un lote. Esto incluye:

• Visión
• Uso de herramientas, incluidas todas las herramientas de servidor (búsqueda web, obtención web, ejecución de código, conectores MCP, asesor y búsqueda de herramientas)
• Mensajes del sistema
• Conversaciones de varios turnos
• Pensamiento extendido
• La mayoría de las funciones beta

Como cada solicitud del lote se procesa de forma independiente, puedes combinar distintos tipos de solicitudes dentro de un mismo lote.

Un pequeño número de parámetros de la Messages API no son compatibles en las solicitudes por lotes. Incluir cualquiera de ellos devuelve un error de validación:

Precios

La Batches API ofrece ahorros de costos significativos. Todo el uso se cobra al 50 por ciento de los precios estándar de la API.

Modelo	Tokens por lotes
Nombre	Entrada	Salida
Claude Fable 5.2For demanding reasoning and long-horizon agentic work	USD 4 / MTok	USD 20 / MTok
Claude Opus 5.5For long-running agentic coding and knowledge work	USD 2 / MTok	USD 10 / MTok
Claude Sonnet 5.5The best combination of speed and intelligence	USD 1 / MTok	USD 5 / MTok
Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing	USD 0.05 / MTokpara prompts de hasta 100,000 tokens	USD 0.25 / MTok
	USD 0.25 / MTokpara prompts de más de 100,000 tokens	USD 1.25 / MTok
Modelos adicionales
Claude Mythos 5.2	USD 4 / MTok	USD 20 / MTok
Claude Fable 5.1	USD 5 / MTok	USD 25 / MTok
Claude Mythos 5.1	USD 5 / MTok	USD 25 / MTok
Claude Fable 5	USD 5 / MTok	USD 25 / MTok
Claude Mythos 5	USD 5 / MTok	USD 25 / MTok
Claude Opus 5	USD 2.50 / MTok	USD 12.50 / MTok
Claude Opus 4.8	USD 2.50 / MTok	USD 12.50 / MTok
Claude Opus 4.7	USD 2.50 / MTok	USD 12.50 / MTok
Claude Opus 4.6	USD 2.50 / MTok	USD 12.50 / MTok
Claude Opus 4.5	USD 2.50 / MTok	USD 12.50 / MTok
Claude Opus 4.1	USD 7.50 / MTok	USD 37.50 / MTok
Claude Opus 4	USD 7.50 / MTok	USD 37.50 / MTok
Claude Sonnet 5	USD 1 / MTok	USD 5 / MTok
Claude Sonnet 4.6	USD 1.50 / MTok	USD 7.50 / MTok
Claude Sonnet 4.5	USD 1.50 / MTok	USD 7.50 / MTok
Claude Sonnet 4	USD 1.50 / MTok	USD 7.50 / MTok
Claude Haiku 4.5	USD 0.50 / MTok	USD 2.50 / MTok

Cómo usar la Message Batches API

Prepara y crea tu lote

Un lote de mensajes se compone de una lista de solicitudes para crear un Message. La estructura de una solicitud individual comprende:

• Un custom_idVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver. único para identificar la solicitud de Messages. Debe tener entre 1 y 64 caracteres y contener solo caracteres alfanuméricos, guiones y guiones bajos (que coincidan con ^[a-zA-Z0-9_-]{1,64}$).
• Un objeto paramsVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver. con los parámetros estándar de la Messages APIVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver.

Puedes crear un loteVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver. pasando esta lista en el parámetro requests:

from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id="my-first-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5-5",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hello, world",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5-5",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hi again, friend",
                    }
                ],
            ),
        ),
    ]
)

print(message_batch)

En este ejemplo, dos solicitudes separadas se agrupan en un lote para su procesamiento asíncrono. Cada solicitud tiene un custom_id único y contiene los parámetros estándar que usarías para una llamada a la Messages API.

Cuando se crea un lote por primera vez, la respuesta tiene un estado de procesamiento in_progress.

{
  "id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": null,
  "results_url": null
}

Seguimiento de tu lote

El campo processing_statusVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver. del lote de mensajes indica la etapa de procesamiento en la que se encuentra el lote. Comienza como in_progress y luego se actualiza a ended una vez que todas las solicitudes del lote han terminado de procesarse y los resultados están listos. Puedes supervisar el estado de tu lote visitando la Console o usando el endpoint de recuperación.

Sondeo para verificar la finalización del lote de mensajes

Para sondear un lote de mensajes, necesitarás su id, que se proporciona en la respuesta al crear un lote o al listar los lotes. Puedes implementar un bucle de sondeo que verifique el estado del lote periódicamente hasta que el procesamiento haya terminado:

import time

client = anthropic.Anthropic()

MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

message_batch = None
while True:
    message_batch = client.messages.batches.retrieve(MESSAGE_BATCH_ID)
    if message_batch.processing_status == "ended":
        break

    print(f"Batch {MESSAGE_BATCH_ID} is still processing...")
    time.sleep(60)
print(message_batch)

Listar todos los lotes de mensajes

Puedes listar todos los lotes de mensajes de tu Workspace usando el endpoint de listadoVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver.. Los resultados están paginados. El SDK obtiene páginas adicionales según sea necesario:

client = anthropic.Anthropic()

# Obtiene automáticamente más páginas según sea necesario.
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)

Recuperar los resultados del lote

Una vez que ha terminado el procesamiento del lote, cada solicitud de Messages del lote tiene un resultado. Hay cuatro tipos de resultado:

El objeto request_counts del lote cuenta las solicitudes que aún se están procesando y las solicitudes con cada tipo de resultado.

Los resultados del lote están disponibles para descargar en la propiedad results_urlVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver. del lote de mensajes y, si los permisos de tu organización lo permiten, en la Console. Como los resultados pueden ser grandes, recibe los resultados mediante streamingVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver. en lugar de descargarlos todos a la vez.

client = anthropic.Anthropic()

# Haz streaming del archivo de resultados en fragmentos eficientes en memoria, procesando uno a la vez
for result in client.messages.batches.results(
    "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
):
    outcome = result.result
    match outcome.type:
        case "succeeded":
            print(f"Success! {result.custom_id}")
        case "errored":
            if outcome.error.error.type == "invalid_request_error":
                # El cuerpo de la solicitud debe corregirse antes de reenviar la solicitud
                print(f"Validation error {result.custom_id}")
            else:
                # La solicitud se puede reintentar directamente
                print(f"Server error {result.custom_id}")
        case "expired":
            print(f"Request expired {result.custom_id}")

Los resultados están en formato .jsonl, donde cada línea es un objeto JSON válido que representa el resultado de una única solicitud del lote de mensajes. Para cada resultado recibido por streaming, puedes hacer algo diferente según su custom_id y su tipo de resultado. Este es un conjunto de resultados de ejemplo:

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-5-5","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}
{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-opus-5-5","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}

Si tu resultado tiene un error, su result.error se establecerá en la estructura de error estándar.

Los resultados del lote usan la versión de la API de la solicitud que creó el lote.

Cancelar un lote de mensajes

Puedes cancelar un lote de mensajes que se esté procesando actualmente usando el endpoint de cancelaciónVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver.. Inmediatamente después de la cancelación, el processing_status de un lote es canceling. Puedes usar la misma técnica de sondeo descrita anteriormente para esperar hasta que la cancelación finalice. Los lotes cancelados terminan con un estado ended y podrían contener resultados parciales de las solicitudes que se procesaron antes de la cancelación.

client = anthropic.Anthropic()

MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

message_batch = client.messages.batches.cancel(
    MESSAGE_BATCH_ID,
)
print(message_batch)

La respuesta muestra el lote en estado canceling:

{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message_batch",
  "processing_status": "canceling",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": "2024-09-24T18:39:03.114875Z",
  "results_url": null
}

Usar el almacenamiento en caché de prompts con Message Batches

La Message Batches API admite el “prompt caching” (almacenamiento en caché de prompts), lo que te permite reducir potencialmente los costos y el tiempo de procesamiento de las solicitudes por lotes. Los descuentos de precios del almacenamiento en caché de prompts y de Message Batches pueden acumularse, lo que proporciona un ahorro de costos aún mayor cuando ambas funciones se usan juntas. Sin embargo, como las solicitudes por lotes se procesan de forma asíncrona y concurrente, los aciertos de caché se proporcionan en la medida de lo posible. Los usuarios suelen experimentar tasas de aciertos de caché que van del 30 por ciento al 98 por ciento, según sus patrones de tráfico.

Para maximizar la probabilidad de aciertos de caché en tus solicitudes por lotes:

1. Incluye bloques cache_control idénticos en cada solicitud de Message dentro de tu lote.
2. Mantén un flujo constante de solicitudes para evitar que las entradas de caché expiren después de su vida útil de 5 minutos.
3. Estructura tus solicitudes para compartir la mayor cantidad posible de contenido almacenado en caché.

Ejemplo de implementación del almacenamiento en caché de prompts en un lote:

from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id="my-first-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5-5",
                max_tokens=1024,
                system=[
                    {
                        "type": "text",
                        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
                    },
                    {
                        "type": "text",
                        "text": "<the entire contents of Pride and Prejudice>",
                        "cache_control": {"type": "ephemeral"},
                    },
                ],
                messages=[
                    {
                        "role": "user",
                        "content": "Analyze the major themes in Pride and Prejudice.",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5-5",
                max_tokens=1024,
                system=[
                    {
                        "type": "text",
                        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
                    },
                    {
                        "type": "text",
                        "text": "<the entire contents of Pride and Prejudice>",
                        "cache_control": {"type": "ephemeral"},
                    },
                ],
                messages=[
                    {
                        "role": "user",
                        "content": "Write a summary of Pride and Prejudice.",
                    }
                ],
            ),
        ),
    ]
)

En este ejemplo, ambas solicitudes del lote incluyen mensajes del sistema idénticos y el texto completo de Orgullo y prejuicio marcado con cache_control para aumentar la probabilidad de aciertos de caché.

Herramientas de servidor y el bucle agéntico

Todas las herramientas de servidor (búsqueda web, obtención web, ejecución de código, conectores MCP, asesor y búsqueda de herramientas) funcionan en solicitudes por lotes. El worker de lotes ejecuta el mismo bucle agéntico del lado del servidor que la Messages API síncrona.

Como no hay una conexión abierta que mantener, el bucle por lotes puede ejecutar más iteraciones en un turno que una solicitud síncrona antes de devolver stop_reason: "pause_turn". Si un resultado del lote vuelve con pause_turn, el turno no se completó; puedes continuarlo enviando el contenido pausado del asistente en una solicitud posterior (por lotes o síncrona) exactamente como se muestra en el patrón de continuación de pause_turn.

Además, el worker de lotes limita web_search para cada organización, de modo que el procesamiento por lotes altamente concurrente no agote el límite de velocidad de búsqueda web de tu organización. El lote reintenta automáticamente las solicitudes limitadas; no necesitas gestionar esto tú mismo, pero los lotes de búsqueda web muy grandes podrían tardar más en completarse.

Salida extendida (beta)

El encabezado beta output-300k-2026-03-24 eleva el límite de max_tokens a 300,000 para las solicitudes por lotes que usan Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5.5, Claude Sonnet 5, Claude Sonnet 4.6 o Claude Haiku 5.5. Incluye el encabezado para generar salidas mucho más largas que el límite estándar de 128k de max_tokens en un solo turno.

Usa la salida extendida para la generación de contenido extenso, como borradores del tamaño de un libro y documentación técnica, extracción exhaustiva de datos estructurados, grandes estructuras de generación de código y largas cadenas de razonamiento.

Una sola generación de 300k tokens puede tardar más de una hora en completarse, así que planifica tus envíos de lotes teniendo en cuenta la ventana de procesamiento de 24 horas. Se aplican los precios estándar de lotes (50 por ciento de los precios estándar de la API).

from anthropic.types.beta.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.beta.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.beta.messages.batches.create(
    betas=["output-300k-2026-03-24"],
    requests=[
        Request(
            custom_id="long-form-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5-5",
                max_tokens=300_000,
                messages=[
                    {
                        "role": "user",
                        "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.",
                    }
                ],
            ),
        ),
    ],
)

print(message_batch)

Mejores prácticas para un procesamiento por lotes eficaz

Para usar la Batches API de forma eficaz:

• Supervisa regularmente el estado del procesamiento de los lotes e implementa una lógica de reintentos adecuada para las solicitudes fallidas.
• Usa valores de custom_id significativos para hacer coincidir fácilmente los resultados con las solicitudes, ya que el orden no está garantizado.
• Considera dividir conjuntos de datos muy grandes en varios lotes para facilitar su gestión.
• Haz una prueba de una sola estructura de solicitud con la Messages API para evitar errores de validación.

Solución de problemas comunes

Si experimentas un comportamiento inesperado:

• Verifica que el tamaño total de la solicitud por lotes no supere los 256 MB. Si el tamaño de la solicitud es demasiado grande, es posible que recibas un error 413 request_too_large.
• Comprueba que estás usando modelos compatibles para todas las solicitudes del lote.
• Asegúrate de que cada solicitud del lote tenga un custom_id único.
• Asegúrate de que hayan pasado menos de 29 días desde el momento created_at del lote (no desde el ended_at del procesamiento). Después de 29 días, los resultados ya no están disponibles para descargar.
• Confirma que el lote no se haya cancelado.

Ten en cuenta que el fallo de una solicitud en un lote no afecta el procesamiento de las demás solicitudes.

Almacenamiento y privacidad de los lotes

• Aislamiento del Workspace: los lotes están aislados dentro del Workspace en el que se crean. Solo pueden acceder a ellos las solicitudes de API de ese mismo Workspace o los usuarios con permiso para ver los lotes del Workspace en la Console.

• Disponibilidad de los resultados: los resultados de los lotes están disponibles durante 29 días después de crear el lote, lo que da tiempo suficiente para su recuperación y procesamiento.

Preguntas frecuentes

Próximos pasos