Skip to main content

batches

Creates, updates, deletes, gets or lists a batches resource.

Overview​

Namebatches
TypeResource
Idopenai.batches.batches

Fields​

The following fields are returned by SELECT queries:

Batch retrieved successfully.

NameDatatypeDescription
idstring
error_file_idstringThe ID of the file containing the outputs of requests with errors.
input_file_idstringThe ID of the input file for the batch.
output_file_idstringThe ID of the file containing the outputs of successfully executed requests.
cancelled_atinteger (unixtime)The Unix timestamp (in seconds) for when the batch was cancelled.
cancelling_atinteger (unixtime)The Unix timestamp (in seconds) for when the batch started cancelling.
completed_atinteger (unixtime)The Unix timestamp (in seconds) for when the batch was completed.
completion_windowstringThe time frame within which the batch should be processed.
created_atinteger (unixtime)The Unix timestamp (in seconds) for when the batch was created.
endpointstringThe OpenAI API endpoint used by the batch.
errorsobject
expired_atinteger (unixtime)The Unix timestamp (in seconds) for when the batch expired.
expires_atinteger (unixtime)The Unix timestamp (in seconds) for when the batch will expire.
failed_atinteger (unixtime)The Unix timestamp (in seconds) for when the batch failed.
finalizing_atinteger (unixtime)The Unix timestamp (in seconds) for when the batch started finalizing.
in_progress_atinteger (unixtime)The Unix timestamp (in seconds) for when the batch started processing.
metadataobjectSet 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. (x-oaiTypeLabel: map)
modelstringModel ID used to process the batch, like gpt-5-2025-08-07. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models.
objectstringThe object type, which is always batch. (batch)
request_countsobjectThe request counts for different statuses within the batch.
statusstringThe current status of the batch. (validating, failed, in_progress, finalizing, completed, expired, cancelling, cancelled)
usageobjectRepresents 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.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
getselectbatch_idopenai-organization, openai-project
listselectafter, limit, openai-organization, openai-project
createinsertinput_file_id, endpoint, completion_windowopenai-organization, openai-project
cancelexecbatch_idopenai-organization, openai-project

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
batch_idstringThe ID of the batch to cancel.
afterstringA 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.
limitintegerA limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. Automatically applied from a SQL LIMIT clause - SELECT ... LIMIT 10 sends limit=10 on the wire. Setting it explicitly in a WHERE clause is not required.
openai-organizationstringOptionally scope the request to a specific organization (overrides the default associated with the API key). Addressable in SQL as openai_organization.
openai-projectstringOptionally scope the request to a specific project (overrides the default associated with the API key). Addressable in SQL as openai_project.

SELECT examples​

Batch retrieved successfully.

SELECT
id,
error_file_id,
input_file_id,
output_file_id,
cancelled_at,
cancelling_at,
completed_at,
completion_window,
created_at,
endpoint,
errors,
expired_at,
expires_at,
failed_at,
finalizing_at,
in_progress_at,
metadata,
model,
object,
request_counts,
status,
usage
FROM openai.batches.batches
WHERE batch_id = '{{ batch_id }}' -- required
AND "openai-organization" = '{{ openai-organization }}'
AND "openai-project" = '{{ openai-project }}'
;

INSERT examples​

No description available.

INSERT INTO openai.batches.batches (
input_file_id,
endpoint,
completion_window,
metadata,
output_expires_after,
"openai-organization",
"openai-project"
)
SELECT 
'{{ input_file_id }}' /* required */,
'{{ endpoint }}' /* required */,
'{{ completion_window }}' /* required */,
'{{ metadata }}',
'{{ output_expires_after }}',
'{{ openai-organization }}',
'{{ openai-project }}'
RETURNING
id,
error_file_id,
input_file_id,
output_file_id,
cancelled_at,
cancelling_at,
completed_at,
completion_window,
created_at,
endpoint,
errors,
expired_at,
expires_at,
failed_at,
finalizing_at,
in_progress_at,
metadata,
model,
object,
request_counts,
status,
usage
;

Lifecycle Methods​

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

EXEC openai.batches.batches.cancel 
@batch_id='{{ batch_id }}' --required, 
@openai-organization='{{ openai-organization }}', 
@openai-project='{{ openai-project }}'
;