Inference API
Batches
Create a new batch
/v1/batches
Create a new batch for processing requests.
Request Body
namestringThe name of the batch created.
Response Body
batch_idstringThe ID of the batch.
create_api_key_idstringID of the API key that was used to create the batch.
create_timestringThe time when the batch was created.
namestringThe human-readable name of the batch.
stateobjectHolds aggregate information about the current state of a batch process.
{
"name": "My New Batch"
}{
"batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
"name": "My New Batch",
"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
}
}List batches
/v1/batches
List all batches for the current team.
Query Parameters
limitinteger | nullNumber of elements to return.
pagination_tokenstring | nullOptional page token to retrieve a specific page. Provided by `pagination_token` in `ListBatchesResponse`.
Response Body
batchesarray<object>The information about the batches.
No parameters.{
"batches": [
{
"batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
"name": "My New Batch",
"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
}
},
{
"batch_id": "batch_bac0e657-6bbf-46ba-a671-1d73a67c132a",
"name": "MyNewBatch",
"create_time": "2025-11-09",
"expire_time": "2025-11-10",
"create_api_key_id": "********-****-****-****-************",
"cancel_time": "2025-11-09",
"cancel_by_xai_message": null,
"state": {
"num_requests": 1,
"num_pending": 0,
"num_success": 1,
"num_error": 0,
"num_cancelled": 0
}
}
]
}Get batch
/v1/batches/{batch_id}
Get information about a specific batch.
Path Parameters
batch_idstringThe unique identifier of the batch
Response Body
batch_idstringThe ID of the batch.
create_api_key_idstringID of the API key that was used to create the batch.
create_timestringThe time when the batch was created.
namestringThe human-readable name of the batch.
stateobjectHolds aggregate information about the current state of a batch process.
No parameters.{
"batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
"name": "My New Batch",
"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
}
}List batch requests in a batch
/v1/batches/{batch_id}/requests
List metadata for all requests in a batch.
Path Parameters
batch_idstringThe unique identifier of the batch
Query Parameters
limitinteger | nullMaximum number of items to return in a single page (max 1000)
pagination_tokenstring | nullToken for retrieving the next page of results
Response Body
batch_request_metadataarray<object>The batch request metadata for the given batch.
No parameters.{
"batch_request_metadata": [
{
"batch_request_id": "test_request_0",
"endpoint": "xai_api.Chat/GetCompletion",
"model": "grok-4",
"state": "succeeded",
"create_time": "2025-11-11",
"finish_time": "2025-11-12"
}
],
"pagination_token": null
}Add batch requests to a batch
/v1/batches/{batch_id}/requests
Add multiple requests to an existing batch.
Path Parameters
batch_idstringThe unique identifier of the batch
Request Body
batch_requestsarray<object>List of batch requests to add to the batch
{
"batch_requests": [
{
"batch_request_id": "test_request_0",
"batch_request": {
"chat_get_completion": {
"messages": [
{
"role": "system",
"content": "You are a helpful assistant that can answer questions and help with tasks."
},
{
"role": "user",
"content": "What is 101*3?"
}
],
"model": "grok-4"
}
}
}
]
}No response.Get processing results of a batch
/v1/batches/{batch_id}/results
List the processing results for a batch.
Path Parameters
batch_idstringThe unique identifier of the batch
Query Parameters
limitinteger | nullMaximum number of items to return in a single page (max 1000)
pagination_tokenstring | nullToken for retrieving the next page of results
Response Body
resultsarray<object>The results that has been processed.
No parameters.{
"results": [
{
"batch_request_id": "test_request_0",
"batch_result": {
"response": {
"chat_get_completion": {
"id": "e7c2162b-ca73-c181-2364-1feabef778fe_us-east-1",
"object": "chat.completion",
"created": 1762801725,
"model": "grok-4",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "101 multiplied by 3 is 303. If you have more calculations or questions, feel free to ask!",
"refusal": null
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 706,
"completion_tokens": 22,
"total_tokens": 827,
"prompt_tokens_details": {
"text_tokens": 706,
"audio_tokens": 0,
"image_tokens": 0,
"cached_tokens": 679
},
"completion_tokens_details": {
"reasoning_tokens": 99,
"audio_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
},
"num_sources_used": 0
},
"system_fingerprint": "fp_1944a19e1f"
}
}
}
}
],
"pagination_token": null
}Cancel processing on a batch
/v1/batches/{batch_id}:cancel
Cancel processing of all requests in a batch.
Path Parameters
batch_idstringThe unique identifier of the batch to cancel
Response Body
batch_idstringThe ID of the batch.
create_api_key_idstringID of the API key that was used to create the batch.
create_timestringThe time when the batch was created.
namestringThe human-readable name of the batch.
stateobjectHolds aggregate information about the current state of a batch process.
No parameters.{
"batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
"name": "My New Batch",
"create_time": "2025-11-11",
"expire_time": "2025-11-12",
"create_api_key_id": "********-****-****-****-************",
"cancel_time": "2025-11-11",
"cancel_by_xai_message": null,
"state": {
"num_requests": 1,
"num_pending": 0,
"num_success": 1,
"num_error": 0,
"num_cancelled": 0
}
}Last updated:February 13, 2026