openai-usage

One usage model for every OpenAI API.

The OpenAI Python SDK reports usage in a different shape for almost every endpoint — Chat Completions, Responses, Agents SDK, Realtime, Batch, Embeddings, Images, Transcription. openai-usage collapses them all into a single, additive Usage object and estimates what it costs against live model pricing. Gemini and LiteLLM usage are supported too, behind optional extras.

📖 Full documentation: https://allen2c.github.io/openai-usage/

Installation

pip install openai-usage

Requires Python 3.11+.

Quickstart

from openai_usage import Usage

# Normalize usage from any OpenAI API into one shape
total = Usage()
total.add(Usage.from_openai(chat_completion.usage))          # Chat Completions
total.add(Usage.from_openai(response.usage))                 # Responses API
total.add(Usage.from_openai(realtime_event.response.usage))  # Realtime

print(total.input_tokens, total.output_tokens, total.total_tokens)

# Estimate the cost against any model
print(f"${total.estimate_cost('gpt-4o'):.6f}")

What it does

Unify — Usage.from_openai(...) accepts Chat Completions, Responses, Agents SDK, Realtime, Batch, Embeddings, Images, Transcription, and Assistants run usage — plus Gemini and LiteLLM usage via optional extras.
Aggregate — Usage.add() accumulates requests, tokens, and per-modality detail (cached, cache-write, reasoning, audio, image, video, text) across calls.
Estimate — Usage.estimate_cost() prices usage against any model using LiteLLM and OpenRouter pricing, with separate rates for cached, cache-write, reasoning, audio, image, and duration-billed usage.
Serialize — Usage is a Pydantic model with full backward compatibility for older payloads.

See the Supported Usage Types table for the full compatibility matrix, and Estimating Costs for pricing details and limitations.

Documentation

The docs are built with Material for MkDocs and deployed to GitHub Pages on every push to main.

make mkdocs        # serve locally at http://localhost:8000

License

MIT — see LICENSE.

Metadata

Release files for openai-usage 0.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for openai-usage 0.10.0
File	Size	Uploaded
openai_usage-0.10.0.tar.gz	86.3 kB	Aug 5, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for openai-usage 0.10.0
File	Interpreter	ABI	Platform	Reset
openai_usage-0.10.0-py3-none-any.whl 92.9 kB Aug 5, 2026	Python 3	none	any	Details

Total release size: 179.2 kB

Release files / openai_usage-0.10.0.tar.gz

Download URL	openai_usage-0.10.0.tar.gz
Size	86.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`089be5527f9e78a9c4783f1a021c57526c91bd51af2173eabe2a767b17d1171c`
BLAKE2b-256 checksum How to use checksums	`c4856d1a3eb41cc3ed373b3dd7202d6bc9f0c7160d2b2d167bfaee935b3484c2`
Upload date	Aug 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.4.1 CPython/3.12.13 Darwin/25.5.0`

Release files / openai_usage-0.10.0-py3-none-any.whl

Download URL	openai_usage-0.10.0-py3-none-any.whl
Size	92.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`7b3b717e275b8b8026c3ba393eedc73040af8798b33fb627af7127816f2068e9`
BLAKE2b-256 checksum How to use checksums	`42f51122e82c0a01227db8cccb6deed2cb2990eb0801cda36b6ef5479df1308e`
Upload date	Aug 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.4.1 CPython/3.12.13 Darwin/25.5.0`