Skip to content

Creates and executes a batch from an uploaded file of requests

POST
/batches

Authorizations

Request Body required

object
input_file_id
required

The ID of an uploaded file that contains requests for the new batch.

See upload file for how to upload a file.

Your input file must be formatted as a JSONL file, and must be uploaded with the purpose batch. The file can contain up to 50,000 requests, and can be up to 100 MB in size.

string
endpoint
required

The endpoint to be used for all requests in the batch. Currently /v1/chat/completions, /v1/embeddings, and /v1/completions are supported. Note that /v1/embeddings batches are also restricted to a maximum of 50,000 embedding inputs across all requests in the batch.

string
Allowed values: /v1/chat/completions /v1/embeddings /v1/completions
completion_window
required

The time frame within which the batch should be processed. Currently only 24h is supported.

string
Allowed values: 24h
metadata

Optional custom metadata for the batch.

object
key
additional properties
string

Responses

200

Batch created successfully.

object
id
required
string
object
required

The object type, which is always batch.

string
Allowed values: batch
endpoint
required

The OpenAI API endpoint used by the batch.

string
errors
object
object

The object type, which is always list.

string
data
Array<object>
object
code

An error code identifying the error type.

string
message

A human-readable message providing more details about the error.

string
param

The name of the parameter that caused the error, if applicable.

string
nullable
line

The line number of the input file where the error occurred, if applicable.

integer
nullable
input_file_id
required

The ID of the input file for the batch.

string
completion_window
required

The time frame within which the batch should be processed.

string
status
required

The current status of the batch.

string
Allowed values: validating failed in_progress finalizing completed expired cancelling cancelled
output_file_id

The ID of the file containing the outputs of successfully executed requests.

string
error_file_id

The ID of the file containing the outputs of requests with errors.

string
created_at
required

The Unix timestamp (in seconds) for when the batch was created.

integer
in_progress_at

The Unix timestamp (in seconds) for when the batch started processing.

integer
expires_at

The Unix timestamp (in seconds) for when the batch will expire.

integer
finalizing_at

The Unix timestamp (in seconds) for when the batch started finalizing.

integer
completed_at

The Unix timestamp (in seconds) for when the batch was completed.

integer
failed_at

The Unix timestamp (in seconds) for when the batch failed.

integer
expired_at

The Unix timestamp (in seconds) for when the batch expired.

integer
cancelling_at

The Unix timestamp (in seconds) for when the batch started cancelling.

integer
cancelled_at

The Unix timestamp (in seconds) for when the batch was cancelled.

integer
request_counts

The request counts for different statuses within the batch.

object
total
required

Total number of requests in the batch.

integer
completed
required

Number of requests that have been completed successfully.

integer
failed
required

Number of requests that have failed.

integer
metadata

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. Keys can be a maximum of 64 characters long and values can be a maximum of 512 characters long.

object