Run a Batch API job

The Batch API queues requests for later. Typical completion is within 24 hours on a best-effort basis. Pricing is reduced versus real-time, and batch requests sit outside per-minute rate limits. You can also manage batches in the xAI Console. Get a key and credits at console.x.ai.

Not every model accepts Batch. Unsupported models reject the request. Check the model page before you queue.

Four steps

1. Create a batch.
2. Add requests.
3. Poll until num_pending is 0.
4. Fetch results.

Create

curl -X POST https://api.x.ai/v1/batches \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{"name": "customer_feedback_analysis"}'

Add chat requests

POST /v1/batches/{batch_id}/requests. Each item needs a unique batch_request_id (or the API mints a UUID). Use your own ids so you can match results later. Chat work goes under batch_request.responses with input and model (use grok-4.6 unless the model page says otherwise).

Poll and results

GET /v1/batches/{batch_id} returns counters: num_requests, num_pending, num_success, num_error, num_cancelled. Results show up as individual requests finish. Page with limit and pagination_token on GET /v1/batches/{batch_id}/results.

Cancel

POST /v1/batches/{batch_id}:cancel. Completed results stay. Pending ones are dropped.

SDK sketch

import os
from xai_sdk import Client

client = Client(api_key=os.getenv("XAI_API_KEY"))
batch = client.batch.create(batch_name="customer_feedback_analysis")
# client.batch.add(...)
# client.batch.get(...)
# client.batch.list_batch_results(...)

JSONL file upload

Upload a JSONL file via the Files API, then create the batch with input_file_id. Caps: 200 MB / 50,000 requests. File-based batches are sealed. You cannot call AddBatchRequests on them.

Pitfalls

• Image and video result URLs expire after 1 hour. Download promptly.
• Completion within 24 hours is best effort only.
• An unsupported model rejects the batch request. Check the model page.
• Console API credits are a separate bill from SuperGrok's weekly pool on grok.com.