Volgen, status en annulering
Op deze pagina
Bijgewerkt op 2 november 2026 op basis van de xAI-documentatie: de batch-korting bedraagt 20% op in aanmerking komende tekstmodellen (niet 50%), de voorbeelden volgen de REST API en de officiële
xai-sdk(client.batch.*; de Batch API van xAI komt niet overeen met het formaat van OpenAI, dus de OpenAI SDK is niet van toepassing), en de Responses API heeft voorrang boven Chat Completions, een verouderd eindpunt bij xAI. Bronnen: Batch API · REST Reference · Batch Pricing.
De levenscyclus van een batch beheren
Zodra u uw verzoeken heeft ingediend, moet u de voortgang volgen, statussen lezen en weten wanneer en hoe u een batch kunt annuleren. Deze les behandelt alle beschikbare beheerbewerkingen.
Twee niveaus van status
xAI volgt de voortgang op twee niveaus. De batch zelf heeft geen globale status zoals “voltooid” of “mislukt”: deze bevat tellers in het state-object. Elk verzoek heeft echter zijn eigen status:
| Status verzoek | Betekenis | Actie |
|---|---|---|
pending | In wachtrij | Wachten |
succeeded | Verwerkt, resultaat beschikbaar | Resultaat ophalen |
failed | Fout tijdens verwerking | Bericht lezen, opnieuw proberen indien nuttig |
cancelled | Geannuleerd, bijvoorbeeld met de batch | Indien nodig opnieuw indienen |
De batch is volledig verwerkt wanneer de teller num_pending op nul staat. Een batch kan ook worden geannuleerd of verlopen: na expire_time zijn de resultaten niet meer toegankelijk.
Tellers controleren
De aanroep GET /v1/batches/{batch_id} geeft de batch en zijn tellers terug:
curl "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY"
Het antwoord bevat:
{
"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
}
}
Deze tellers volgen de voortgang in realtime, zonder te wachten tot de verwerking is voltooid. Met de SDK leest u ze in client.batch.get(batch_id=...).state.
Uw batches opsommen
Om een batch te vinden of de geschiedenis te controleren:
curl "https://api.x.ai/v1/batches?limit=20" \
-H "Authorization: Bearer $XAI_API_KEY"
De lijst wordt gepagineerd via limit en pagination_token. Batches blijven hier staan tot ze verlopen. Met de SDK geeft client.batch.list(limit=20) een lijst batches terug waarbij elk element zijn name, batch_id en state bevat. De xAI-console biedt hetzelfde overzicht, maar dan visueel.
Resultaten ophalen
U kunt op elk moment resultaten ophalen, zelfs tijdens de verwerking:
curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY"
Elk resultaat bevat de batch_request_id van het bijbehorende verzoek. Mislukte verzoeken verschijnen hier met hun bericht; met de SDK scheiden de eigenschappen succeeded en failed van elke pagina deze van elkaar.
Metagegevens van verzoeken controleren
Om de status van elk verzoek te volgen:
curl "https://api.x.ai/v1/batches/$BATCH_ID/requests?limit=50" \
-H "Authorization: Bearer $XAI_API_KEY"
Elke vermelding geeft de identificatie van het verzoek, het eindpunt, het model, de status, evenals de aanmaak- en einddatum. Dit is het diagnostische hulpmiddel wanneer een teller stagneert, of om te verifiëren wat succesvol is toegevoegd.
Een batch annuleren
Als u de lopende verwerking moet stoppen:
curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID:cancel" \
-H "Authorization: Bearer $XAI_API_KEY"
Annulering is definitief: openstaande verzoeken worden niet verwerkt en u kunt geen verzoeken meer aan de batch toevoegen. Reeds verwerkte verzoeken blijven echter beschikbaar in de resultaten. Annuleer als:
- U na indiening een fout in uw verzoeken heeft ontdekt
- De batch niet langer nodig is (wijziging in prioriteit)
- U een gecorrigeerde batch opnieuw wilt indienen
Met de SDK: client.batch.cancel(batch_id=...), wat de batch en zijn tellers op het moment van annulering teruggeeft.
Polling-strategie
Wacht in productie op voltooiing met gefaseerde polling en een maximale vertraging:
import time
def attendre_batch(client, batch_id, intervalle=300, delai_max=2 * 86400):
"""Wait until all requests in the batch are processed."""
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"Canceled by xAI: {batch.cancel_by_xai_message}")
if etat.num_requests > 0 and etat.num_pending == 0:
return batch
print(f"{etat.num_success} succeeded, {etat.num_error} failed, "
f"{etat.num_pending} pending out of {etat.num_requests}")
time.sleep(intervalle)
raise TimeoutError(f"Batch not finished after {delai_max} s")
Een interval van enkele minuten is geschikt voor grote batches; de documentatie van xAI pollt in zijn voorbeelden om de paar seconden, wat betrekking heeft op kleine batches. En aangezien resultaten beschikbaar komen naarmate ze binnenkomen, staat niets u in de weg om ze tijdens het wachten op te halen.
Belangrijkste punten
- Lees de batch via zijn tellers (
num_pending,num_success,num_error…); elk verzoek heeft zijn status:pending,succeeded,failed,cancelled GET /v1/batches/{id}geeft de voortgang,/resultsde resultaten,/requestsde details van de verzoeken- Annulering (
POST /v1/batches/{id}:cancel) is onomkeerbaar, maar behoudt reeds geproduceerde resultaten - Lijsten en resultaten worden gepagineerd met
limitenpagination_token - Poll met intervallen van enkele minuten, met een maximale vertraging, en haal de gegevens op vóór
expire_time