Search
K
OpenAI API

Batch

Create large batches of API requests to run asynchronously.

Creates and executes a batch from an uploaded file of requests

post
https://api.openai.com/v1/batches

Body

application/json
input_file_idstringrequired

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 200 MB in size.

endpointstringrequired

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.

Allowed values:/v1/chat/completions/v1/embeddings/v1/completions

completion_windowstringrequired

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

Allowed values:24h

metadataobject | null

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.

Response

200 application/json

Batch created successfully.

Batch

idstringrequired
objectstringrequired

The object type, which is always batch.

Allowed values:batch

endpointstringrequired

The OpenAI API endpoint used by the batch.

errorsobject
Show Child Parameters
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 values:validatingfailedin_progressfinalizingcompletedexpiredcancellingcancelled

output_file_idstring

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

error_file_idstring

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_atinteger

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

expires_atinteger

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

finalizing_atinteger

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

completed_atinteger

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

failed_atinteger

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

expired_atinteger

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

cancelling_atinteger

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

cancelled_atinteger

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

request_countsobject

The request counts for different statuses within the batch.

Show Child Parameters
metadataobject | null

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.

post/batches

Body

{ "input_file_id": "input_file_id", "endpoint": "/v1/chat/completions", "completion_window": "24h" }
 
200 application/json

List your organization's batches.

get
https://api.openai.com/v1/batches

Query Parameters

afterstring

A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.

limitinteger

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

Default:20

Response

200 application/json

Batch listed successfully.

ListBatchesResponse

dataarray[object]required
Show Child Parameters
first_idstring

Example:batch_abc123

last_idstring

Example:batch_abc456

has_morebooleanrequired
objectstringrequired

Allowed values:list

get/batches
 
200 application/json

Retrieves a batch.

get
https://api.openai.com/v1/batches/{batch_id}

Path Parameters

batch_idstringrequired

The ID of the batch to retrieve.

Response

200 application/json

Batch retrieved successfully.

Batch

idstringrequired
objectstringrequired

The object type, which is always batch.

Allowed values:batch

endpointstringrequired

The OpenAI API endpoint used by the batch.

errorsobject
Show Child Parameters
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 values:validatingfailedin_progressfinalizingcompletedexpiredcancellingcancelled

output_file_idstring

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

error_file_idstring

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_atinteger

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

expires_atinteger

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

finalizing_atinteger

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

completed_atinteger

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

failed_atinteger

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

expired_atinteger

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

cancelling_atinteger

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

cancelled_atinteger

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

request_countsobject

The request counts for different statuses within the batch.

Show Child Parameters
metadataobject | null

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.

get/batches/{batch_id}
 
200 application/json

Cancels an in-progress batch. The batch will be in status `cancelling` for up to 10 minutes, before changing to `cancelled`, where it will have partial results (if any) available in the output file.

post
https://api.openai.com/v1/batches/{batch_id}/cancel

Path Parameters

batch_idstringrequired

The ID of the batch to cancel.

Response

200 application/json

Batch is cancelling. Returns the cancelling batch’s details.

Batch

idstringrequired
objectstringrequired

The object type, which is always batch.

Allowed values:batch

endpointstringrequired

The OpenAI API endpoint used by the batch.

errorsobject
Show Child Parameters
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 values:validatingfailedin_progressfinalizingcompletedexpiredcancellingcancelled

output_file_idstring

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

error_file_idstring

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_atinteger

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

expires_atinteger

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

finalizing_atinteger

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

completed_atinteger

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

failed_atinteger

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

expired_atinteger

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

cancelling_atinteger

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

cancelled_atinteger

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

request_countsobject

The request counts for different statuses within the batch.

Show Child Parameters
metadataobject | null

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.

post/batches/{batch_id}/cancel
 
200 application/json