Implementation:Openai Openai python Batch Usage 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 batch-level token usage statistics provided by the openai-python SDK.

Description

The BatchUsage Pydantic model represents aggregated token usage details for an entire batch job, including input_tokens, output_tokens, and total_tokens. It also includes detailed breakdowns via nested models: InputTokensDetails (with cached_tokens from prompt caching) and OutputTokensDetails (with reasoning_tokens). This field is only populated on batches created after September 7, 2025.

Usage

Import this type when inspecting the usage field on a Batch object to analyze token consumption and costs for batch processing jobs.

Code Reference

Source Location

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

Signature

class InputTokensDetails(BaseModel):
    cached_tokens: int

class OutputTokensDetails(BaseModel):
    reasoning_tokens: int

class BatchUsage(BaseModel):
    input_tokens: int
    input_tokens_details: InputTokensDetails
    output_tokens: int
    output_tokens_details: OutputTokensDetails
    total_tokens: int

Import

from openai.types import BatchUsage

I/O Contract

Fields

Name	Type	Required	Description
input_tokens	int	Yes	Total number of input tokens across all requests
input_tokens_details	InputTokensDetails	Yes	Breakdown of input tokens (cached_tokens)
output_tokens	int	Yes	Total number of output tokens across all requests
output_tokens_details	OutputTokensDetails	Yes	Breakdown of output tokens (reasoning_tokens)
total_tokens	int	Yes	Total tokens used (input + output)

InputTokensDetails Fields

Name	Type	Required	Description
cached_tokens	int	Yes	Number of tokens retrieved from prompt cache

OutputTokensDetails Fields

Name	Type	Required	Description
reasoning_tokens	int	Yes	Number of reasoning tokens generated

Usage Examples

from openai import OpenAI

client = OpenAI()

batch = client.batches.retrieve("batch_abc123")
if batch.usage:
    print(f"Input tokens: {batch.usage.input_tokens}")
    print(f"  Cached: {batch.usage.input_tokens_details.cached_tokens}")
    print(f"Output tokens: {batch.usage.output_tokens}")
    print(f"  Reasoning: {batch.usage.output_tokens_details.reasoning_tokens}")
    print(f"Total tokens: {batch.usage.total_tokens}")

Related Pages

• Environment:Openai_Openai_python_Python_3_9_Plus