# xAI Batch API — asynchronous discounted processing (/v1/batches)

Status: DOCUMENTED + LIVE_VERIFIED (2026-09-19: create → add 2 requests → poll (11 s) → requests → results → cancel; DELETE → 405). Not in the OpenAPI spec (REST reference + guide only). Machine-readable: parameters/xai-files-collections-batches.json, endpoints/xai-inference.json, objects/xai-inference-objects.json (Batch, BatchRequestMetadata, BatchResult).

Sources: https://docs.x.ai/developers/rest-api-reference/inference/batches · https://docs.x.ai/developers/advanced-api-usage/batch-api · https://docs.x.ai/developers/pricing#batch-api-pricing Last verified: 2026-09-19

# Lifecycle

1. POST /v1/batches {"name"} → Batch (batch_id batch_<uuid>, create_time/expire_time as YYYY-MM-DD, live expiry +30 days, state counters all 0).
2. POST /v1/batches/{id}/requests {"batch_requests":[{"batch_request_id":"r1","batch_request":{"chat_get_completion":{…ChatRequest}}}, …]} → 200 with empty body. Other request kinds: responses (ModelRequest — accepted, result returned as chat_get_completion live), image_generation, image_edit, video_generation, video_extension. Unique batch_request_id recommended (UUID generated otherwise); ≤25 MB per request; ≤1 000 add calls / 30 s / team.
3. Poll GET /v1/batches/{id} until state.num_pending == 0 (live: 2 → 0 in 11 s; docs: typically ≤24 h, best effort). Individual states via GET /v1/batches/{id}/requests (pending | succeeded | failed | cancelled, endpoint xai_api.Chat/GetCompletion, model, times).
4. GET /v1/batches/{id}/results?limit=…&pagination_token=… → {results:[{batch_request_id, batch_result:{response:{chat_get_completion:ChatCompletion}} | {error}}], pagination_token}; available as requests finish; cost per result in usage.cost_in_usd_ticks.
5. POST /v1/batches/{id}:cancel → Batch with cancel_time (pending requests dropped, completed results kept; works after completion too). GET /v1/batches?limit&pagination_token lists. No delete (405).

Alternative: JSONL file — lines {"custom_id","method":"POST","url":"/v1/chat/completions"|"/v1/responses"|"/v1/images/generations"|"/v1/images/edits"|"/v1/videos/generations"|"/v1/videos/edits"|"/v1/videos/extensions","body":{…}}, upload via Files API, then POST /v1/batches {name, input_file_id}. ≤200 MB, ≤50 000 lines, sealed after creation; an invalid line cancels the batch with cancel_by_xai_message.

# Pricing / limits

20 % off all token types (input, cached, output, reasoning) for grok-4.3, grok-4.20-0309-reasoning, grok-4.20-0309-non-reasoning, grok-4.20-multi-agent-0309; other models accept batch at standard price or reject ("not supported for batch processing"). Batch requests do not count towards per-minute rate limits. Not combinable with priority processing. Image/video results are signed URLs valid 1 h. Both server-side tools and client-side function tools work inside batch requests (multi-turn tool calling = new batch request).

# Live result sample

{"batch_request_id":"r1","batch_result":{"response":{"chat_get_completion":{"id":"445efed6-…","object":"chat.completion","model":"grok-4.3",
 "choices":[{"index":0,"message":{"role":"assistant","content":"OK.","reasoning_content":"The user requested a reply of \"OK.\"","refusal":null},"finish_reason":"stop"}],
 "usage":{"prompt_tokens":196,"completion_tokens":2,"total_tokens":373,"prompt_tokens_details":{…"cached_tokens":192},"completion_tokens_details":{"reasoning_tokens":175,…},"num_sources_used":0,"cost_in_usd_ticks":3887200},"system_fingerprint":"fp_eb3c003fc66c14ed","service_tier":"default"}}}}

SDK: xai-sdk client.batch.create(batch_name=…, input_file_id=…), .add(batch_id, batch_requests=[chat, image_req, …]), .get, .list, .list_batch_requests, .list_batch_results (.succeeded / .failed), .cancel; batch.cost_breakdown.total_cost_usd_ticks (SDK/gRPC only — not in the REST body live). Examples: examples/xai/batches/. Test: tests/xai/test_files.py::test_batch_lifecycle (gated by RUN_BATCH_TESTS).