Suivi, statuts et annulation

Gérer le cycle de vie d’un batch

Une fois vos requêtes soumises, vous devez surveiller l’avancement du traitement, interpréter les états, et savoir quand et comment annuler un batch. Cette leçon couvre toutes les opérations de gestion disponibles.

Les quatre états d’un batch

Chaque batch passe par un ensemble d’états prévisibles :

L’état pending couvre toute la durée du traitement, de la soumission à la fin. Il n’y a pas d’état intermédiaire “in_progress” : le batch reste pending jusqu’à ce qu’il bascule vers succeeded, failed, ou cancelled.

Consulter le statut

L’appel GET /v1/batches/{batch_id} retourne l’état actuel et des informations de progression :

curl "https://api.x.ai/v1/batches/${BATCH_ID}" \
  -H "Authorization: Bearer $XAI_API_KEY"

La réponse inclut :

{
  "id": "batch_abc123",
  "status": "pending",
  "created_at": "2026-04-03T10:00:00Z",
  "request_counts": {
    "total": 500,
    "completed": 342,
    "failed": 3
  }
}

Les compteurs request_counts permettent de suivre la progression en temps réel sans attendre la fin du traitement.

Lister vos batchs

Pour retrouver un batch ou consulter l’historique :

curl "https://api.x.ai/v1/batches?page_size=20" \
  -H "Authorization: Bearer $XAI_API_KEY"

Le paramètre page_size contrôle le nombre de résultats par page. Cette requête est utile pour un tableau de bord de suivi ou pour retrouver un batch dont vous avez perdu l’identifiant.

Récupérer les résultats

Lorsque le statut est succeeded, récupérez les résultats paginés :

curl "https://api.x.ai/v1/batches/${BATCH_ID}/results?page_size=100" \
  -H "Authorization: Bearer $XAI_API_KEY"

Chaque résultat est associé à son custom_id. Si certaines requêtes ont échoué individuellement, elles apparaissent dans les résultats avec un statut d’erreur, mais le batch global reste succeeded.

Consulter les métadonnées des requêtes

Pour obtenir des détails sur les requêtes soumises :

curl "https://api.x.ai/v1/batches/${BATCH_ID}/requests?page_size=50" \
  -H "Authorization: Bearer $XAI_API_KEY"

Cet endpoint est utile pour vérifier quelles requêtes ont été correctement ajoutées au batch, ou pour diagnostiquer des problèmes de soumission.

Annuler un batch

Si vous devez arrêter un traitement en cours :

curl -X POST "https://api.x.ai/v1/batches/${BATCH_ID}:cancel" \
  -H "Authorization: Bearer $XAI_API_KEY"

L’annulation est définitive. Les requêtes déjà traitées au moment de l’annulation peuvent être disponibles dans les résultats partiels, mais ce n’est pas garanti. Utilisez l’annulation si :

• Vous avez détecté une erreur dans vos requêtes après soumission
• Le batch n’est plus nécessaire (changement de priorité)
• Vous voulez resoumettre un lot corrigé

Stratégie de polling

En production, implémentez un polling intelligent :

import time

def wait_for_batch(client, batch_id, interval=300, max_wait=86400):
    """Attend la fin d'un batch avec timeout."""
    elapsed = 0

    while elapsed < max_wait:
        status = client.batches.retrieve(batch_id)

        if status.status == "succeeded":
            return status
        elif status.status in ("failed", "cancelled"):
            raise Exception(f"Batch {status.status}")

        completed = status.request_counts.completed
        total = status.request_counts.total
        print(f"Progression : {completed}/{total}")

        time.sleep(interval)
        elapsed += interval

    raise TimeoutError(f"Batch non termine apres {max_wait}s")

Un intervalle de 5 minutes est un bon compromis : assez fréquent pour détecter rapidement la fin du traitement, assez espacé pour ne pas surcharger l’API.

Points clés à retenir

• Quatre états possibles : pending, succeeded, failed, cancelled
• Le polling via GET /v1/batches/{id} fournit les compteurs de progression
• L’annulation via POST /v1/batches/{id}:cancel est irréversible
• Les résultats sont paginés et accessibles via page_size
• Implémentez un polling avec intervalle de 5 minutes et un timeout de 24-48 heures