Seguimiento, estado y cancelación
En esta página
Actualizado el 2 de noviembre de 2026 según la documentación de xAI: el descuento por lotes es del 20 % en modelos de texto elegibles (no del 50 %), los ejemplos siguen la API REST y el
xai-sdkoficial (client.batch.*; la API de lotes de xAI no coincide con el formato de OpenAI, por lo que el SDK de OpenAI no aplica), y la API de Responses tiene prioridad sobre Chat Completions, un punto final heredado en xAI. Fuentes: Batch API · REST Reference · Batch Pricing.
Gestión del ciclo de vida del lote
Una vez enviadas las solicitudes, debes hacer un seguimiento del progreso del procesamiento, consultar los estados y saber cuándo y cómo cancelar un lote. Esta lección cubre todas las operaciones de gestión disponibles.
Dos niveles de estado
xAI realiza el seguimiento del progreso en dos niveles. El lote en sí no tiene un estado global como «completado» o «fallido»: contiene contadores en su objeto state. Cada solicitud, sin embargo, tiene su propio estado:
| Estado de la solicitud | Significado | Acción |
|---|---|---|
pending | En cola | Esperar |
succeeded | Procesada, resultado disponible | Recuperar resultado |
failed | Error durante el procesamiento | Leer mensaje, reintentar si procede |
cancelled | Cancelada, por ejemplo con su lote | Reenviar si es necesario |
El lote se procesa por completo cuando su contador num_pending baja a cero. También puede cancelarse o caducar: tras el expire_time, sus resultados dejan de ser accesibles.
Consulta de contadores
La llamada GET /v1/batches/{batch_id} devuelve el lote y sus contadores:
curl "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY"
La respuesta incluye:
{
"batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
"name": "analyse_avis_clients",
"state": {
"num_requests": 500,
"num_pending": 155,
"num_success": 342,
"num_error": 3,
"num_cancelled": 0
}
}
Estos contadores rastrean el progreso en tiempo real, sin esperar a que finalice el procesamiento. Con el SDK, léelos en client.batch.get(batch_id=...).state.
Listado de lotes
Para encontrar un lote o consultar el historial:
curl "https://api.x.ai/v1/batches?limit=20" \
-H "Authorization: Bearer $XAI_API_KEY"
La lista se pagina mediante limit y pagination_token. Los lotes permanecen ahí hasta su caducidad. Con el SDK, client.batch.list(limit=20) devuelve una lista batches donde cada elemento contiene su name, batch_id y state. La consola de xAI ofrece la misma vista, pero en formato visual.
Recuperación de resultados
Puedes recuperar los resultados en cualquier momento, incluso durante el procesamiento:
curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY"
Cada resultado incluye el batch_request_id de su solicitud. Las solicitudes fallidas aparecen aquí con su mensaje; con el SDK, las propiedades succeeded y failed de cada página las separan.
Consulta de metadatos de la solicitud
Para rastrear el estado de cada solicitud:
curl "https://api.x.ai/v1/batches/$BATCH_ID/requests?limit=50" \
-H "Authorization: Bearer $XAI_API_KEY"
Cada entrada proporciona el identificador de la solicitud, su punto final, modelo, estado, y fechas de creación y finalización. Esta es la herramienta de diagnóstico cuando un contador se estanca, o para verificar qué se añadió correctamente.
Cancelación de un lote
Si necesitas detener un procesamiento en curso:
curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID:cancel" \
-H "Authorization: Bearer $XAI_API_KEY"
La cancelación es definitiva: las solicitudes pendientes no se procesarán y ya no podrás añadir solicitudes al lote. Las solicitudes ya procesadas, sin embargo, siguen disponibles en los resultados. Cancela si:
- Detectas un error en tus solicitudes tras el envío
- El lote ya no es necesario (cambio de prioridad)
- Quieres reenviar un lote corregido
Con el SDK: client.batch.cancel(batch_id=...), que devuelve el lote y sus contadores en el momento de la cancelación.
Estrategia de sondeo (polling)
En producción, espera a la finalización con un sondeo espaciado y un retraso máximo:
import time
def esperar_lote(client, batch_id, intervalo=300, retraso_max=2 * 86400):
"""Espera hasta que se procesen todas las solicitudes del lote."""
inicio = time.monotonic()
while time.monotonic() - inicio < retraso_max:
lote = client.batch.get(batch_id=batch_id)
estado = lote.state
if lote.cancel_by_xai_message:
raise RuntimeError(f"Cancelado por xAI: {lote.cancel_by_xai_message}")
if estado.num_requests > 0 and estado.num_pending == 0:
return lote
print(f"{estado.num_success} correctas, {estado.num_error} fallidas, "
f"{estado.num_pending} pendientes de {estado.num_requests}")
time.sleep(intervalo)
raise TimeoutError(f"Lote no finalizado tras {retraso_max} s")
Un intervalo de unos pocos minutos es adecuado para lotes grandes; la documentación de xAI sondea cada pocos segundos en sus ejemplos, que cubren lotes pequeños. Y dado que los resultados están disponibles a medida que llegan, nada impide recuperarlos durante la espera.
Puntos clave
- Lee el lote por sus contadores (
num_pending,num_success,num_error…); cada solicitud tiene su estado:pending,succeeded,failed,cancelled GET /v1/batches/{id}ofrece el progreso,/resultslos resultados,/requestsel detalle de la solicitud- La cancelación (
POST /v1/batches/{id}:cancel) es irreversible, pero conserva los resultados ya producidos - Las listas y resultados se pagan con
limitypagination_token - Realiza sondeos a intervalos de unos pocos minutos, con un retraso máximo, y recupera los datos antes de
expire_time