NAME
OpenAPI::Client::OpenAI::Path::batches - Documentation for the /batches path.
OPERATIONS
GET /batches
listBatches
$client->list_batches({
body => { ... },
});List your organization's batches.
Path/query parameters
after(in query, optional, string) - A cursor for use in pagination.afteris 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.limit(in query, optional, integer) - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.Default: 20
Responses
200 - Batch listed successfully.
Content-Type: application/json
Example:
{
"data" : [
"{\n \"id\": \"batch_abc123\",\n \"object\": \"batch\",\n \"endpoint\": \"/v1/completions\",\n \"model\": \"gpt-5-2025-08-07\",\n \"errors\": null,\n \"input_file_id\": \"file-abc123\",\n \"completion_window\": \"24h\",\n \"status\": \"completed\",\n \"output_file_id\": \"file-cvaTdG\",\n \"error_file_id\": \"file-HOWS94\",\n \"created_at\": 1711471533,\n \"in_progress_at\": 1711471538,\n \"expires_at\": 1711557933,\n \"finalizing_at\": 1711493133,\n \"completed_at\": 1711493163,\n \"failed_at\": null,\n \"expired_at\": null,\n \"cancelling_at\": null,\n \"cancelled_at\": null,\n \"request_counts\": {\n \"total\": 100,\n \"completed\": 95,\n \"failed\": 5\n },\n \"usage\": {\n \"input_tokens\": 1500,\n \"input_tokens_details\": {\n \"cached_tokens\": 1024\n },\n \"output_tokens\": 500,\n \"output_tokens_details\": {\n \"reasoning_tokens\": 300\n },\n \"total_tokens\": 2000\n },\n \"metadata\": {\n \"customer_id\": \"user_123456789\",\n \"batch_description\": \"Nightly eval job\",\n }\n}\n"
],
"first_id" : "batch_abc123",
"has_more" : false,
"last_id" : "batch_abc456",
"object" : "list"
}POST /batches
createBatch
$client->create_batch({
body => { ... },
});Creates and executes a batch from an uploaded file of requests
Request body
Content-Type: application/json
Properties:
completion_window(string, required) - The time frame within which the batch should be processed. Currently only24his supported.Allowed values: 24h
endpoint(string, required) - 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/videosare supported. Note that/v1/embeddingsbatches are also restricted to a maximum of 50,000 embedding inputs across all requests in the batch.Allowed values: /v1/responses, /v1/chat/completions, /v1/embeddings, /v1/completions, /v1/moderations, /v1/images/generations, /v1/images/edits, /v1/videos
input_file_id(string, 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 200 MB in size.metadata(Metadata)See "Metadata" below for shape.
output_expires_after(BatchFileExpirationAfter)See "BatchFileExpirationAfter" below for shape.
Example:
{
"completion_window" : "24h",
"endpoint" : "/v1/responses",
"input_file_id" : "string",
"metadata" : {},
"output_expires_after" : {
"anchor" : "created_at",
"seconds" : 0
}
}Responses
200 - Batch created successfully.
Content-Type: application/json
Example:
"{\n \"id\": \"batch_abc123\",\n \"object\": \"batch\",\n \"endpoint\": \"/v1/completions\",\n \"model\": \"gpt-5-2025-08-07\",\n \"errors\": null,\n \"input_file_id\": \"file-abc123\",\n \"completion_window\": \"24h\",\n \"status\": \"completed\",\n \"output_file_id\": \"file-cvaTdG\",\n \"error_file_id\": \"file-HOWS94\",\n \"created_at\": 1711471533,\n \"in_progress_at\": 1711471538,\n \"expires_at\": 1711557933,\n \"finalizing_at\": 1711493133,\n \"completed_at\": 1711493163,\n \"failed_at\": null,\n \"expired_at\": null,\n \"cancelling_at\": null,\n \"cancelled_at\": null,\n \"request_counts\": {\n \"total\": 100,\n \"completed\": 95,\n \"failed\": 5\n },\n \"usage\": {\n \"input_tokens\": 1500,\n \"input_tokens_details\": {\n \"cached_tokens\": 1024\n },\n \"output_tokens\": 500,\n \"output_tokens_details\": {\n \"reasoning_tokens\": 300\n },\n \"total_tokens\": 2000\n },\n \"metadata\": {\n \"customer_id\": \"user_123456789\",\n \"batch_description\": \"Nightly eval job\",\n }\n}\n"SCHEMAS
Batch
Properties:
cancelled_at(integer) - The Unix timestamp (in seconds) for when the batch was cancelled.cancelling_at(integer) - The Unix timestamp (in seconds) for when the batch started cancelling.completed_at(integer) - The Unix timestamp (in seconds) for when the batch was completed.completion_window(string, required) - The time frame within which the batch should be processed.created_at(integer, required) - The Unix timestamp (in seconds) for when the batch was created.endpoint(string, required) - The OpenAI API endpoint used by the batch.error_file_id(string) - The ID of the file containing the outputs of requests with errors.errors(object)expired_at(integer) - The Unix timestamp (in seconds) for when the batch expired.expires_at(integer) - The Unix timestamp (in seconds) for when the batch will expire.failed_at(integer) - The Unix timestamp (in seconds) for when the batch failed.finalizing_at(integer) - The Unix timestamp (in seconds) for when the batch started finalizing.id(string, required)in_progress_at(integer) - The Unix timestamp (in seconds) for when the batch started processing.input_file_id(string, required) - The ID of the input file for the batch.metadata(Metadata)See "Metadata" below for shape.
model(string) - Model ID used to process the batch, likegpt-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.object(string, required) - The object type, which is alwaysbatch.Allowed values: batch
output_file_id(string) - The ID of the file containing the outputs of successfully executed requests.request_counts(object) - The request counts for different statuses within the batch.status(string, required) - The current status of the batch.Allowed values: validating, failed, in_progress, finalizing, completed, expired, cancelling, cancelled
usage(object) - 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.
BatchFileExpirationAfter
Properties:
anchor(string, required) - Anchor timestamp after which the expiration policy applies. Supported anchors:created_at. Note that the anchor is the file creation time, not the time the batch is created.Allowed values: created_at
seconds(integer, required) - The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).
ListBatchesResponse
Properties:
data(array of Batch, required)first_id(string)has_more(boolean, required)last_id(string)object(string, required)Allowed values: list
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, 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.
SEE ALSO
COPYRIGHT AND LICENSE
Copyright (C) 2023-2026 by Nelson Ferraz
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.0 or, at your option, any later version of Perl 5 you may have available.