Implementation:Openai Openai python Response Usage Model

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

Overview

Concrete type for representing token usage details in a Responses API response, provided by the openai-python SDK.

Description

ResponseUsage is a Pydantic model that captures token usage statistics for a response. It includes input_tokens and output_tokens counts, a total_tokens sum, and two detail objects: InputTokensDetails (with cached_tokens for prompt caching) and OutputTokensDetails (with reasoning_tokens for reasoning model output). This allows callers to track cost and understand token consumption breakdown.

Usage

Import this type when you need to inspect or type-check the usage statistics returned in the usage field of a Responses API response object.

Code Reference

Source Location

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

Signature

class ResponseUsage(BaseModel):
    """Represents token usage details including input tokens, output tokens,
    a breakdown of output tokens, and the total tokens used."""

    input_tokens: int
    input_tokens_details: InputTokensDetails
    output_tokens: int
    output_tokens_details: OutputTokensDetails
    total_tokens: int

Import

from openai.types.responses import ResponseUsage

I/O Contract

Fields

Name	Type	Required	Description
input_tokens	int	Yes	The number of input tokens.
input_tokens_details	InputTokensDetails	Yes	A detailed breakdown of input tokens. Contains cached_tokens (int).
output_tokens	int	Yes	The number of output tokens.
output_tokens_details	OutputTokensDetails	Yes	A detailed breakdown of output tokens. Contains reasoning_tokens (int).
total_tokens	int	Yes	The total number of tokens used (input + output).

Detail Models

Model	Field	Type	Description
InputTokensDetails	cached_tokens	int	The number of tokens retrieved from the cache (prompt caching).
OutputTokensDetails	reasoning_tokens	int	The number of reasoning tokens generated by reasoning models.

Usage Examples

import openai

client = openai.OpenAI()

response = client.responses.create(
    model="gpt-4o",
    input="Explain the Pythagorean theorem.",
)

usage = response.usage
print(f"Input tokens: {usage.input_tokens}")
print(f"  Cached: {usage.input_tokens_details.cached_tokens}")
print(f"Output tokens: {usage.output_tokens}")
print(f"  Reasoning: {usage.output_tokens_details.reasoning_tokens}")
print(f"Total tokens: {usage.total_tokens}")

Related Pages

• Environment:Openai_Openai_python_Python_3_9_Plus