Implementation:Openai Openai python Completion 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 token usage statistics on completion requests, provided by the openai-python SDK.

Description

The CompletionUsage Pydantic model reports token consumption for a completion request: completion_tokens, prompt_tokens, and total_tokens. It also provides optional detailed breakdowns via CompletionTokensDetails (covering accepted_prediction_tokens, audio_tokens, reasoning_tokens, and rejected_prediction_tokens) and PromptTokensDetails (covering audio_tokens and cached_tokens). This model is shared across both legacy completions and chat completions.

Usage

Import this type when analyzing token usage from any completion response. It appears as the usage field on both Completion and ChatCompletion objects.

Code Reference

Source Location

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

Signature

class CompletionTokensDetails(BaseModel):
    accepted_prediction_tokens: Optional[int] = None
    audio_tokens: Optional[int] = None
    reasoning_tokens: Optional[int] = None
    rejected_prediction_tokens: Optional[int] = None

class PromptTokensDetails(BaseModel):
    audio_tokens: Optional[int] = None
    cached_tokens: Optional[int] = None

class CompletionUsage(BaseModel):
    completion_tokens: int
    prompt_tokens: int
    total_tokens: int
    completion_tokens_details: Optional[CompletionTokensDetails] = None
    prompt_tokens_details: Optional[PromptTokensDetails] = None

Import

from openai.types import CompletionUsage

I/O Contract

Fields

Name	Type	Required	Description
completion_tokens	int	Yes	Number of tokens in the generated completion
prompt_tokens	int	Yes	Number of tokens in the prompt
total_tokens	int	Yes	Total tokens used (prompt + completion)
completion_tokens_details	Optional[CompletionTokensDetails]	No	Detailed breakdown of completion tokens
prompt_tokens_details	Optional[PromptTokensDetails]	No	Detailed breakdown of prompt tokens

CompletionTokensDetails Fields

Name	Type	Required	Description
accepted_prediction_tokens	Optional[int]	No	Predicted Output tokens that appeared in the completion
audio_tokens	Optional[int]	No	Audio output tokens generated by the model
reasoning_tokens	Optional[int]	No	Tokens used for model reasoning
rejected_prediction_tokens	Optional[int]	No	Predicted Output tokens that did not appear in the completion

PromptTokensDetails Fields

Name	Type	Required	Description
audio_tokens	Optional[int]	No	Audio input tokens in the prompt
cached_tokens	Optional[int]	No	Cached tokens present in the prompt

Usage Examples

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)

usage = response.usage
if usage:
    print(f"Prompt tokens: {usage.prompt_tokens}")
    print(f"Completion tokens: {usage.completion_tokens}")
    print(f"Total tokens: {usage.total_tokens}")
    if usage.completion_tokens_details:
        print(f"  Reasoning: {usage.completion_tokens_details.reasoning_tokens}")
    if usage.prompt_tokens_details:
        print(f"  Cached: {usage.prompt_tokens_details.cached_tokens}")

Related Pages

• Environment:Openai_Openai_python_Python_3_9_Plus