Swagger Petstore - OpenAPI 3.0
POST/batches

Create and execute a batch

Creates and immediately executes a batch from an uploaded JSONL file of API requests. Supply the file ID of an uploaded batch input file, the API endpoint to target, and a completion window. The batch processes asynchronously and returns immediately with status validating.

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

5 body fields

Batch creation configuration. input_file_id, endpoint, and completion_window are required.

input_file_idstringrequired
The ID of an uploaded file that contains requests for the new batch. See [upload file](/docs/api-reference/files/create) for how to upload a file. Your input file must be formatted as a [JSONL file](/docs/api-reference/batch/request-input), 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 set of key-value pairs for storing additional information about the batch. Keys are strings up to 64 characters; values are strings up to 512 characters.
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 object with its unique identifier, status (initially `validating`), endpoint, file IDs, 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-5.6-sol`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](/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 all 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. completion_window must be 24h. If output_expires_after is provided, anchor must be created_at and seconds must be between 3600 and 2592000.