El procesamiento por lotes es un enfoque potente para manejar 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 múltiples solicitudes juntas para su procesamiento asíncrono. Este patrón es particularmente ú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 es la primera implementación de Anthropic de este patrón.



Message Batches API

La Message Batches API es una forma potente y rentable de procesar de manera asíncrona grandes volúmenes de solicitudes de Messages. Este enfoque es adecuado para tareas que no requieren respuestas inmediatas, ya que la mayoría de los lotes terminan en menos de 1 hora, reduciendo los costos en un 50% y aumentando el rendimiento.

Puedes explorar la referencia de la API directamente, además de esta guía.



Cómo funciona la Message Batches API

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

1. El sistema crea un nuevo Message Batch con las solicitudes de Messages proporcionadas.
2. El lote se procesa de forma asíncrona, y cada solicitud se maneja de forma independiente.
3. Puedes consultar el estado del lote y recuperar los resultados cuando el procesamiento haya finalizado 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 insights o resúmenes para grandes conjuntos de datos.
• Generación masiva de contenido: crea grandes cantidades de texto para diversos propósitos (por ejemplo, descripciones de productos, resúmenes de artículos).



Limitaciones de los lotes

• Un Message Batch está limitado a 100,000 solicitudes de Message o 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 dentro de 24 horas.
• Los resultados del lote 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 estarán disponibles para descargar.
• Los lotes están limitados a un Workspace. Puedes ver todos los lotes (y sus resultados) que se crearon dentro del Workspace al que pertenece tu clave de API.
• Los límites de velocidad se aplican tanto a las solicitudes HTTP de la Batches API como al número de solicitudes dentro de un lote que esperan ser procesadas. Consulta Límites de velocidad de la Message Batches API. Además, el procesamiento puede 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 de tu Workspace.
• Cada solicitud en lote debe tener max_tokens de al menos 1. max_tokens: 0 (precalentamiento de caché) no es compatible dentro de un lote, ya que una entrada de caché efímera escrita durante el procesamiento del lote probablemente expiraría antes de que se ejecute la solicitud de seguimiento.



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, advisor y búsqueda de herramientas)
• Mensajes del sistema
• Conversaciones de múltiples turnos
• Pensamiento extendido
• La mayoría de las funciones beta

Dado que cada solicitud en el lote se procesa de forma independiente, puedes mezclar diferentes tipos de solicitudes dentro de un solo lote.

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



Precios

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



Cómo usar la Message Batches API



Prepara y crea tu lote

Un Message Batch está compuesto por una lista de solicitudes para crear un Message. La estructura de una solicitud individual consta de:

• Un custom_id único para identificar la solicitud de Messages. Debe tener de 1 a 64 caracteres y contener solo caracteres alfanuméricos, guiones y guiones bajos (coincidiendo con ^[a-zA-Z0-9_-]{1,64}$).
• Un objeto params con los parámetros estándar de la Messages API

Puedes crear un lote pasando esta lista al 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-4-8",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hello, world",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-8",
                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 tendrá un estado de procesamiento de 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_status del Message Batch indica la etapa de procesamiento en la que se encuentra el lote. Comienza como in_progress, luego se actualiza a ended una vez que todas las solicitudes del lote han terminado de procesarse y los resultados están listos. Puedes monitorear el estado de tu lote visitando la Consola o usando el endpoint de recuperación.



Sondeo para la finalización del Message Batch

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

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 Message Batches

Puedes listar todos los Message Batches en tu Workspace usando el endpoint de listado. La API admite paginación, obteniendo automáticamente 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 el procesamiento del lote ha finalizado, cada solicitud de Messages en el lote tiene un resultado. Hay 4 tipos de resultados:

Verás un resumen de tus resultados con el request_counts del lote, que muestra cuántas solicitudes alcanzaron cada uno de estos cuatro estados.

Los resultados del lote están disponibles para descargar en la propiedad results_url del Message Batch y, si el permiso de la organización lo permite, en la Consola. Debido al tamaño potencialmente grande de los resultados, se recomienda transmitir los resultados en lugar de descargarlos todos a la vez.

client = anthropic.Anthropic()

# Transmite el archivo de resultados en fragmentos eficientes en memoria, procesando uno a la vez
for result in client.messages.batches.results(
    "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
):
    match result.result.type:
        case "succeeded":
            print(f"Success! {result.custom_id}")
        case "errored":
            if result.result.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 puede reintentarse 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 sola solicitud en el Message Batch. Para cada resultado transmitido, puedes hacer algo diferente dependiendo de su custom_id y tipo de resultado. Aquí hay 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-4-8","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-4-8","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á con la estructura de error estándar.



Cancelar un Message Batch

Puedes cancelar un Message Batch que se está procesando actualmente usando el endpoint de cancelación. Inmediatamente después de la cancelación, el processing_status de un lote será canceling. Puedes usar la misma técnica de sondeo descrita anteriormente para esperar hasta que la cancelación se finalice. Los lotes cancelados terminan con un estado de ended y pueden contener resultados parciales para 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 mostrará el lote en un estado de 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 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, proporcionando ahorros de costos aún mayores cuando ambas funciones se usan juntas. Sin embargo, dado que las solicitudes por lotes se procesan de forma asíncrona y concurrente, los aciertos de caché se proporcionan según el mejor esfuerzo posible. Los usuarios generalmente experimentan tasas de aciertos de caché que van del 30% al 98%, dependiendo de 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 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-4-8",
                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-4-8",
                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, advisor y búsqueda de herramientas) funcionan en solicitudes por lotes. El worker del lote ejecuta el mismo bucle agéntico del lado del servidor que la Messages API síncrona.

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

El worker del lote además limita web_search por organización para 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 manejar 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 solicitudes por lotes que usan Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 o Claude Sonnet 4.6. Incluye el encabezado para generar salidas mucho más largas que el límite estándar (de 64k a 128k dependiendo del modelo) en un solo turno.

Usa la salida extendida para generación de formato largo como borradores de la extensión de un libro y documentación técnica, extracción exhaustiva de datos estructurados, grandes andamiajes 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% 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-4-8",
                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 efectivo

Para aprovechar al máximo la Batches API:

• Monitorea el estado del procesamiento del lote regularmente e implementa lógica de reintento apropiada 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 múltiples lotes para una mejor 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 del lote no exceda los 256 MB. Si el tamaño de la solicitud es demasiado grande, es posible que obtengas 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 la hora de created_at del lote (no la hora de ended_at del procesamiento). Si han pasado más de 29 días, los resultados ya no serán visibles.
• Confirma que el lote no haya sido cancelado.

Ten en cuenta que el fallo de una solicitud en un lote no afecta el procesamiento de otras solicitudes.



Almacenamiento de lotes y privacidad

• Aislamiento de Workspace: los lotes están aislados dentro del Workspace en el que se crean. Solo pueden ser accedidos por claves de API asociadas con ese Workspace, o por usuarios con permiso para ver los lotes del Workspace en la Consola.

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



Retención de datos

El procesamiento por lotes almacena datos de solicitudes y respuestas hasta 29 días después de la creación del lote. Puedes eliminar un lote de mensajes en cualquier momento después del procesamiento usando el endpoint DELETE /v1/messages/batches/{batch_id}. Para eliminar un lote en progreso, cancélalo primero. El procesamiento asíncrono requiere almacenamiento del lado del servidor tanto de las entradas como de las salidas hasta la finalización del lote y la recuperación de resultados.

Para la elegibilidad de ZDR en todas las funciones, consulta API y retención de datos.



Preguntas frecuentes



Próximos pasos