List batches via the xAI API

See every Batch API job on your team so you can find an old batch_id, check which jobs are still processing, and avoid creating duplicates when a overnight pipeline already queued the same work. Official Batch API documents GET /v1/batches (and client.batch.list) with the same limit and pagination_token pagination used for results. Batches stay listed until they expire — check expires_at on each row. Create a key and load credits at console.x.ai.

What you need

An XAI_API_KEY with Batch access, at least one batch created earlier (or a fresh one from Run a Batch API job), and a reason to inventory rather than poll a single known id. Neighboring jobs include Get Batch API results when you already have the id, Cancel a Batch API job when a listed batch should stop, and Add Batch API requests from a JSONL file when the next job is file-sealed. More API jobs live on the API hub.

List recent batches

1. Export the key outside of source control:

export XAI_API_KEY="your_api_key"

2. Call the list endpoint with a page size (example 20):

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

3. Or use the xAI Python SDK and print name, id, and whether anything is still pending:

import os
from xai_sdk import Client

client = Client(api_key=os.getenv("XAI_API_KEY"))

response = client.batch.list(limit=20)

for batch in response.batches:
    status = "complete" if batch.state.num_pending == 0 else "processing"
    print(f"{batch.name} ({batch.batch_id}): {status}")

4. When the response includes a pagination_token, request the next page with the same limit and that token until the token is absent. Treat num_pending == 0 with num_requests > 0 as finished processing (success, error, or cancel counts may still be non-zero). Open the xAI Console Batch UI when you prefer a visual list of the same team inventory.

After you have the list

Copy the batch_id you need into a results poll or a cancel call. Match names you assigned at create time (customer_feedback_analysis, nightly eval labels) so operators can find the right container without scanning every id. If a batch is near expires_at, download results before the retention window closes — listing alone does not extend retention.

Pitfalls

Calling list with no key or a key from the wrong team returns an empty or unauthorized surface and looks like “no batches.” Assuming num_pending == 0 means every request succeeded ignores num_error and num_cancelled. Skipping pagination on large teams only shows the first page. Mixing Console API credits with SuperGrok weekly pools on grok.com confuses two different meters the docs keep separate.