Swagger Petstore - OpenAPI 3.0
GET/batches/{batch_id}

Retrieve a batch

Retrieves the current status and metadata of a specific batch. Returns the batch's processing status, input and output file IDs, endpoint, and timestamps. Use this to monitor batch progress or retrieve results after completion.

1 parameter
batch_idstringrequired
The unique identifier of the batch to retrieve.

1 status code
200Returns the batch object with its current status, endpoint, file IDs, and all associated 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

batch_id must identify an existing batch belonging to the authenticated user.