Suivi, statuts et annulation

Cours révisé le 2 novembre 2026 d’après la documentation de xAI : la remise batch est de 20 % sur les modèles texte éligibles (et non 50 %), les exemples suivent l’API REST et le SDK officiel xai-sdk (client.batch.* ; l’API Batch de xAI n’a pas le format de celle d’OpenAI, le SDK OpenAI ne s’y applique pas), et l’API Responses passe avant Chat Completions, endpoint hérité chez xAI. Sources : Batch API · Référence REST · Tarifs batch.

Gérer le cycle de vie d’un batch

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

Deux niveaux d’état

xAI suit l’avancement à deux niveaux. Le batch n’a pas de statut global du type « terminé » ou « échoué » : il porte des compteurs, dans son objet state. Chaque requête, elle, a son état propre :

Le batch est entièrement traité quand son compteur num_pending tombe à zéro. Il peut aussi être annulé, ou expirer : après expire_time, ses résultats ne sont plus accessibles.

Consulter les compteurs

L’appel GET /v1/batches/{batch_id} renvoie le batch et ses compteurs :

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

La réponse inclut notamment :

{
  "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
  }
}

Ces compteurs suivent la progression en temps réel, sans attendre la fin du traitement. Avec le SDK, ils se lisent dans client.batch.get(batch_id=...).state.

Lister vos batchs

Pour retrouver un batch ou consulter l’historique :

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

La liste est paginée par limit et pagination_token. Les batchs y restent jusqu’à leur expiration. Avec le SDK, client.batch.list(limit=20) renvoie une liste batches dont chaque élément porte son name, son batch_id et son state. La console xAI offre la même vue, sous forme visuelle.

Récupérer les résultats

Les résultats se récupèrent à tout moment, y compris pendant le traitement :

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

Chaque résultat porte le batch_request_id de sa requête. Les requêtes en erreur y figurent avec leur message ; avec le SDK, les propriétés succeeded et failed de chaque page les séparent.

Consulter les métadonnées des requêtes

Pour suivre l’état de chaque requête :

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

Chaque entrée donne l’identifiant de la requête, son endpoint, son modèle, son état et ses dates de création et de fin. C’est l’outil de diagnostic quand un compteur ne bouge plus, ou pour vérifier ce qui a bien été ajouté.

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 encore en attente ne seront pas traitées, et vous ne pouvez plus ajouter de requêtes au batch. Les requêtes déjà traitées, elles, restent disponibles dans les résultats. Annulez 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é

Avec le SDK : client.batch.cancel(batch_id=...), qui renvoie le batch et ses compteurs au moment de l’annulation.

Stratégie de polling

En production, attendez la fin avec un polling espacé et un délai maximal :

import time


def attendre_batch(client, batch_id, intervalle=300, delai_max=2 * 86400):
    """Attend que toutes les requêtes du batch soient traitées."""
    debut = time.monotonic()
    while time.monotonic() - debut < delai_max:
        batch = client.batch.get(batch_id=batch_id)
        etat = batch.state
        if batch.cancel_by_xai_message:
            raise RuntimeError(f"Annulé par xAI : {batch.cancel_by_xai_message}")
        if etat.num_requests > 0 and etat.num_pending == 0:
            return batch
        print(f"{etat.num_success} réussies, {etat.num_error} en erreur, "
              f"{etat.num_pending} en attente sur {etat.num_requests}")
        time.sleep(intervalle)
    raise TimeoutError(f"Batch non terminé après {delai_max} s")

Un intervalle de quelques minutes convient aux gros lots ; la documentation de xAI interroge toutes les quelques secondes dans ses exemples, qui portent sur de petits lots. Et comme les résultats sont disponibles au fil de l’eau, rien n’empêche de les récupérer pendant l’attente.

Points clés à retenir

• Le batch se lit à ses compteurs (num_pending, num_success, num_error…) ; chaque requête a son état : pending, succeeded, failed, cancelled
• GET /v1/batches/{id} donne la progression, /results les résultats, /requests le détail par requête
• L’annulation (POST /v1/batches/{id}:cancel) est irréversible, mais conserve les résultats déjà produits
• Listes et résultats se paginent avec limit et pagination_token
• Interrogez à intervalle de quelques minutes, avec un délai maximal, et récupérez avant expire_time