Implementation:Openai Openai python Batch Model

Knowledge Sources	Openai_Openai_python OpenAI API Reference
Domains	API_Types, Python
Last Updated	2026-02-15 00:00 GMT

Overview

Concrete type for the Batch object returned by the OpenAI Batch API, provided by the openai-python SDK.

Description

The Batch Pydantic model represents a batch processing job submitted to the OpenAI API. It contains the full lifecycle state of a batch request, including its status (validating, in_progress, completed, failed, expired, cancelling, cancelled), input/output file IDs, timestamps for each state transition, request counts, token usage, and optional metadata. A nested Errors model holds a list of BatchError objects when errors occur during processing.

Usage

Import this type when you need to type-hint or inspect the response from batch creation, retrieval, or listing operations via client.batches.create(), client.batches.retrieve(), or client.batches.list().

Code Reference

Source Location

• Repository: openai-python
• File: src/openai/types/batch.py

Signature

class Errors(BaseModel):
    data: Optional[List[BatchError]] = None
    object: Optional[str] = None

class Batch(BaseModel):
    id: str
    completion_window: str
    created_at: int
    endpoint: str
    input_file_id: str
    object: Literal["batch"]
    status: Literal[
        "validating", "failed", "in_progress", "finalizing",
        "completed", "expired", "cancelling", "cancelled"
    ]
    cancelled_at: Optional[int] = None
    cancelling_at: Optional[int] = None
    completed_at: Optional[int] = None
    error_file_id: Optional[str] = None
    errors: Optional[Errors] = None
    expired_at: Optional[int] = None
    expires_at: Optional[int] = None
    failed_at: Optional[int] = None
    finalizing_at: Optional[int] = None
    in_progress_at: Optional[int] = None
    metadata: Optional[Metadata] = None
    model: Optional[str] = None
    output_file_id: Optional[str] = None
    request_counts: Optional[BatchRequestCounts] = None
    usage: Optional[BatchUsage] = None

Import

from openai.types import Batch

I/O Contract

Fields

Name	Type	Required	Description
id	str	Yes	Unique identifier for the batch
completion_window	str	Yes	Time frame within which the batch should be processed
created_at	int	Yes	Unix timestamp (seconds) when the batch was created
endpoint	str	Yes	The OpenAI API endpoint used by the batch
input_file_id	str	Yes	ID of the input file for the batch
object	Literal["batch"]	Yes	Object type, always "batch"
status	Literal[...]	Yes	Current status: validating, failed, in_progress, finalizing, completed, expired, cancelling, or cancelled
cancelled_at	Optional[int]	No	Unix timestamp when the batch was cancelled
cancelling_at	Optional[int]	No	Unix timestamp when the batch started cancelling
completed_at	Optional[int]	No	Unix timestamp when the batch was completed
error_file_id	Optional[str]	No	ID of the file containing error outputs
errors	Optional[Errors]	No	Nested error list with BatchError objects
expired_at	Optional[int]	No	Unix timestamp when the batch expired
expires_at	Optional[int]	No	Unix timestamp when the batch will expire
failed_at	Optional[int]	No	Unix timestamp when the batch failed
finalizing_at	Optional[int]	No	Unix timestamp when the batch started finalizing
in_progress_at	Optional[int]	No	Unix timestamp when the batch started processing
metadata	Optional[Metadata]	No	Up to 16 key-value pairs of additional information
model	Optional[str]	No	Model ID used to process the batch
output_file_id	Optional[str]	No	ID of the file containing successful outputs
request_counts	Optional[BatchRequestCounts]	No	Request counts for different statuses
usage	Optional[BatchUsage]	No	Token usage details (batches created after Sep 7 2025)

Usage Examples

from openai import OpenAI

client = OpenAI()

# Retrieve a batch and inspect its status
batch = client.batches.retrieve("batch_abc123")
print(batch.status)          # e.g. "completed"
print(batch.request_counts)  # BatchRequestCounts with completed/failed/total
print(batch.output_file_id)  # file ID for successful results

# Check for errors
if batch.errors and batch.errors.data:
    for err in batch.errors.data:
        print(f"Line {err.line}: {err.message}")

Related Pages

• Environment:Openai_Openai_python_Python_3_9_Plus