OpenAI API (unofficial showcase)
POST/batches

Create and execute a batch

Creates and executes a batch from an uploaded file of requests. Supply the required input_file_id, endpoint, and completion_window; the batch endpoint must be one of the supported API paths, and the only supported completion window is 24h. The response includes the batch status so you can track processing.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

5 body fields

Batch configuration containing an uploaded request file, the endpoint to run, and the processing window.

input_file_idstringrequired
The ID of an uploaded file that contains requests for the new batch. See [upload file](https://developers.openai.com/api/reference/resources/files/methods/create) for how to upload a file. Your input file must be formatted as a [JSONL file](https://developers.openai.com/api/docs/guides/batch#1-prepare-your-batch-file), and must be uploaded with the purpose `batch`. The file can contain up to 50,000 requests, and can be up to 200 MB in size.
endpointstringrequired
The endpoint to be used for all requests in the batch. Currently `/v1/responses`, `/v1/chat/completions`, `/v1/embeddings`, `/v1/completions`, `/v1/moderations`, `/v1/images/generations`, `/v1/images/edits`, and `/v1/videos` are supported. Note that `/v1/embeddings` batches are also restricted to a maximum of 50,000 embedding inputs across all requests in the batch.
Allowed:/v1/responses/v1/chat/completions/v1/embeddings/v1/completions/v1/moderations/v1/images/generations/v1/images/edits/v1/videos
completion_windowstringrequired
The time frame within which the batch should be processed. Currently only `24h` is supported.
Allowed:24h
metadataobjectoptional
Optional key-value metadata to attach to the batch. Keys can be up to 64 characters.
output_expires_afterobjectoptional
The expiration policy for the output and/or error file that are generated for a batch.

5 status codes
200Returns the created batch object, including its identifier, endpoint, input file, completion window, current status, and timestamps.
idstringrequired
objectstringrequired
The object type, which is always `batch`.
Allowed:batch
endpointstringrequired
The OpenAI API endpoint used by the batch.
modelstringoptional
Model ID used to process the batch, like `gpt-6-astra`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://developers.openai.com/api/docs/models) to browse and compare available models.
errorsobjectoptional
input_file_idstringrequired
The ID of the input file for the batch.
completion_windowstringrequired
The time frame within which the batch should be processed.
statusstringrequired
The current status of the batch.
Allowed:validatingfailedin_progressfinalizingcompletedexpiredcancellingcancelled
output_file_idstringoptional
The ID of the file containing the outputs of successfully executed requests.
error_file_idstringoptional
The ID of the file containing the outputs of requests with errors.
created_atintegerrequired
The Unix timestamp (in seconds) for when the batch was created.
in_progress_atintegeroptional
The Unix timestamp (in seconds) for when the batch started processing.
expires_atintegeroptional
The Unix timestamp (in seconds) for when the batch will expire.
finalizing_atintegeroptional
The Unix timestamp (in seconds) for when the batch started finalizing.
completed_atintegeroptional
The Unix timestamp (in seconds) for when the batch was completed.
failed_atintegeroptional
The Unix timestamp (in seconds) for when the batch failed.
expired_atintegeroptional
The Unix timestamp (in seconds) for when the batch expired.
cancelling_atintegeroptional
The Unix timestamp (in seconds) for when the batch started cancelling.
cancelled_atintegeroptional
The Unix timestamp (in seconds) for when the batch was cancelled.
request_countsobjectoptional
The request counts for different statuses within the batch.
usageobjectoptional
Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. Only populated on batches created after September 7, 2025.
metadataobjectoptional
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
400Returned when the request is invalid or the account cannot create a batch.
errorobjectrequired
429Returned when the request is rejected because a rate limit was exceeded.
errorobjectrequired
500Returned when an internal error prevents the batch from being created.
errorobjectrequired
503Returned when the service is temporarily unavailable and the batch cannot be created.
errorobjectrequired

Error handling

A 400 is returned when the request is invalid or the account cannot create a batch; a 429 is returned when a rate limit is exceeded. A 500 is returned when an internal error prevents creation, and a 503 is returned when the service is temporarily unavailable. input_file_id, endpoint, and completion_window are required; completion_window must be 24h, and output_expires_after.seconds must be between 3600 and 2592000 when provided.