Create an empty batch

Updated November 2, 2026 based on xAI documentation: the batch discount is 20% on eligible text models (not 50%), the examples use the REST API and the official xai-sdk SDK (client.batch.*; xAI’s Batch API does not use OpenAI’s format, so the OpenAI SDK does not apply), and the Responses API takes precedence over Chat Completions, a legacy endpoint at xAI. Sources: Batch API · REST reference · Batch pricing.

First step: initialization

Creating a batch is the first concrete action in your workflow. A POST /v1/batches call initializes an empty container that will then receive your requests. This step is deliberately minimal: it creates the identifier and prepares the batch on the server side.

The create call

The request body contains only one required field, name:

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

The response contains the batch_id, the creation and expiration dates, and the batch counters, still at zero (example from the API reference):

{
  "batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
  "name": "customer_review_analysis",
  "create_time": "2025-11-11",
  "expire_time": "2025-11-12",
  "create_api_key_id": "********-****-****-****-************",
  "cancel_time": null,
  "cancel_by_xai_message": null,
  "state": {
    "num_requests": 0,
    "num_pending": 0,
    "num_success": 0,
    "num_error": 0,
    "num_cancelled": 0
  }
}

Python implementation

The official SDK installs with pip install xai-sdk (version 1.21.0 as of November 2, 2026; Python 3.10 minimum). It reads the key from the XAI_API_KEY environment variable:

from xai_sdk import Client

client = Client()

batch = client.batch.create(batch_name="customer_review_analysis")
batch_id = batch.batch_id
print(f"Batch created: {batch_id}")

The returned batch_id is the unique reference for your batch. Keep it in a variable, a file, or a database, depending on your architecture.

JavaScript implementation

Without an SDK, a simple fetch to the REST API is enough:

const response = await fetch("https://api.x.ai/v1/batches", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.XAI_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ name: "customer_review_analysis" })
});

const batch = await response.json();
console.log(`Batch created: ${batch.batch_id}`);

Creation rate limits

Batch creation is limited to 2 per second per team; the number of batches itself is not capped. In practice, you will rarely hit this limit: you generally create one batch per operation, then add all your requests to it. If you create several in a loop, space the calls at least 500 milliseconds apart.

Best practices

Name your batches carefully: the name is required, so make it useful. A name that states the dataset and date (customer_reviews_2026_11_02) is easy to find in the batch list and in the xAI console, which also lets you track batches visually.

Note the expiration: expire_time indicates when the batch and its results stop being accessible. Your retrieval process must run before then.

Handle creation errors: an authentication error, a rate limit overrun, or a network issue can prevent creation. Retry transient errors with an increasing delay (exponential backoff), but never retry authentication errors.

Key takeaways

• Creating a batch is a POST /v1/batches whose only required field is name
• The response contains a unique batch_id to keep for the rest of the workflow
• In Python, the official xai-sdk SDK exposes client.batch.create(batch_name=...)
• The limit is 2 creations per second per team, with no cap on the number of batches
• Watch expire_time and retry only transient errors