Inspect Batch API request metadata

Check where each line in a Batch API job sits — pending, succeeded, failed, or cancelled — when aggregate counters are not enough and you need to know which batch_request_id stalled or errored. Official Batch API documents GET /v1/batches/{batch_id}/requests and client.batch.list_batch_requests, with the same limit / pagination_token pagination as results. Individual states are separate from batch-level num_pending / num_success / num_error. Create a key at console.x.ai.

What you need

An XAI_API_KEY, a batch_id, and the batch_request_id values you assigned when adding requests (or the UUIDs the API minted). Neighboring jobs include List batches via the xAI API to find the container, Get Batch API results for succeeded payloads, and Cancel a Batch API job when pending rows should stop. More API jobs live on the API hub.

List request metadata

1. Export the key:

export XAI_API_KEY="your_api_key"

2. Page request metadata (example page size 50):

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

3. Or use the SDK:

import os
from xai_sdk import Client

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

metadata = client.batch.list_batch_requests(batch_id="your_batch_id")

for request in metadata.batch_request_metadata:
    print(f"Request {request.batch_request_id}: {request.state}")

4. Map official individual states: pending (queued), succeeded (result available), failed (error during processing), cancelled (batch cancelled before this request ran). Follow pagination_token until it is absent on large batches. Use your own batch_request_id values at add time so this list lines up with rows in your database.

How this differs from results

Metadata tells you lifecycle state and timing details for each request. Results endpoints return the model output (or error message) for finished work. Poll metadata when operators ask “which id is still pending?”; pull results when they ask “what did it say?” Cancelled pending requests never get success payloads, but already-completed rows remain available after a batch cancel.

Pitfalls

Expecting metadata to include full completion text forces a second call to results. Reusing the same batch_request_id across adds breaks idempotency and matching. Ignoring pagination hides failed ids past the first page. Assuming cancel clears completed results is wrong — only pending work stops. Pasting API keys into tickets forces a rotate.