/ 
OpenAPI-Client-OpenAI-0.28
⭐ Starred 7 / OpenAPI::Client::OpenAI::Path::batches-batch_id

NAME

OpenAPI::Client::OpenAI::Path::batches-batch_id - Documentation for the /batches/{batch_id} path.

OPERATIONS

GET /batches/{batch_id}

retrieveBatch

$client->retrieve_batch({
    body => { ... },
});

Retrieves a batch.

Path/query parameters

  • batch_id (in path, required, string) - The ID of the batch to retrieve.

Responses

200 - Batch retrieved 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, 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.

  • object (string, required) - The object type, which is always batch .

    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.

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

OpenAPI::Client::OpenAI::Path

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.