Suivi, statuts et annulation

Gerer le cycle de vie d’un batch

Une fois vos requetes soumises, vous devez surveiller l’avancement du traitement, interpreter les etats, et savoir quand et comment annuler un batch. Cette lecon couvre toutes les operations de gestion disponibles.

Les quatre etats d’un batch

Chaque batch passe par un ensemble d’etats previsibles :

L’etat pending couvre toute la duree du traitement, de la soumission a la fin. Il n’y a pas d’etat intermediaire “in_progress” : le batch reste pending jusqu’a ce qu’il bascule vers succeeded, failed, ou cancelled.

Consulter le statut

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

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

La reponse 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 reel 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 parametre page_size controle le nombre de resultats par page. Cette requete est utile pour un tableau de bord de suivi ou pour retrouver un batch dont vous avez perdu l’identifiant.

Recuperer les resultats

Lorsque le statut est succeeded, recuperez les resultats pagines :

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

Chaque resultat est associe a son custom_id. Si certaines requetes ont echoue individuellement, elles apparaissent dans les resultats avec un statut d’erreur, mais le batch global reste succeeded.

Consulter les metadonnees des requetes

Pour obtenir des details sur les requetes 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 verifier quelles requetes ont ete correctement ajoutees au batch, ou pour diagnostiquer des problemes de soumission.

Annuler un batch

Si vous devez arreter 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 definitive. Les requetes deja traitees au moment de l’annulation peuvent etre disponibles dans les resultats partiels, mais ce n’est pas garanti. Utilisez l’annulation si :

• Vous avez detecte une erreur dans vos requetes apres soumission
• Le batch n’est plus necessaire (changement de priorite)
• Vous voulez resoumettre un lot corrige

Strategie de polling

En production, implementez 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 frequent pour detecter rapidement la fin du traitement, assez espace pour ne pas surcharger l’API.

Points cles a retenir

• Quatre etats 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 irreversible
• Les resultats sont pagines et accessibles via page_size
• Implementez un polling avec intervalle de 5 minutes et un timeout de 24-48 heures