Sample - OpenAI API
POST/batches

Create and execute a batch

Creates and executes a batch from an uploaded JSONL request file. Supply input_file_id, a supported endpoint, and the 24h completion_window; optionally configure metadata and output-file expiration.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

5 body fields

Batch creation configuration referencing an uploaded JSONL request file and specifying the endpoint, processing window, optional metadata, and optional output-file expiration policy.

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 string key-value metadata attached to the batch.
output_expires_afterobjectoptional
The expiration policy for the output and/or error file that are generated for a batch.

1 status code
200Returns the created batch with its identifier, input file, endpoint, completion window, status, timestamps, and output or error file references when available.
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.

Error handling

input_file_id, endpoint, and completion_window are required. endpoint must be one of /v1/responses, /v1/chat/completions, /v1/embeddings, /v1/completions, /v1/moderations, /v1/images/generations, /v1/images/edits, or /v1/videos, and completion_window must be 24h; if supplied, output_expires_after.seconds must be between 3600 and 2592000.