openai-usage-report ๐
A command-line tool to inspect token usage and estimated cost for your OpenAI projects.
โโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ
โ OPENAI_ADMIN_API_KEY โ โ litellm Pricing โ
โโโโโโโโโโโฌโโโโโโโโโโโโ โโโโโโโโโโฌโโโโโโโโโโ
โ โ
โผ โผ
โโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ
โ Fetch Projects & โ โ Local Cache โ
โ Usage Data โ โ (~/.cache/...) โ
โโโโโโโโโโโฌโโโโโโโโโโโโ โโโโโโโโโโฌโโโโโโโโโโ
โ โ
โโโโโโโโโโโโฌโโโโโโโโโโโโโโโโ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโ
โ Calculate Costs โ
โโโโโโโโโโโโฌโโโโโโโโโโโโ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโ
โ Color-coded Terminal โ
โ Table โ
โโโโโโโโโโโโโโโโโโโโโโโโ
๐ Features
| Feature | Description |
|---|---|
| ๐ List Projects | See all projects accessible with your admin API key |
| ๐ Detailed Usage | Usage data broken down by day or month, model, and API key |
| ๐ฐ Auto-Updated Pricing | Pricing fetched from litellm and cached locally |
| ๐ Flexible Grouping | Group and sort by day, month, project, key, or model |
| ๐ Custom Date Ranges | Focus on a specific time period |
| ๐จ Colorful Output | Clear, color-coded table for easy reading |
๐ฆ Installation
From PyPI (recommended)
# With uv (recommended)
uv tool install openai-usage-report
# With pipx
pipx install openai-usage-report
From GitHub
# With uv
uv tool install git+https://github.com/obeone/scripts#subdirectory=openai-usage
# With pipx
git clone https://github.com/obeone/scripts
cd scripts
pipx install ./openai-usage
Docker
docker run --rm -e OPENAI_ADMIN_API_KEY="..." obeoneorg/openai-usage-report
Environment Variable
This tool requires an admin-level OpenAI API key:
export OPENAI_ADMIN_API_KEY="your_admin_api_key_here"
๐ง Usage
List Available Projects
openai-usage --list-projects
View Usage for All Projects
openai-usage
View Usage for Specific Projects and a Date Range
openai-usage --projects proj_xxxxxxxxxxxx --start-date 2024-01-01 --end-date 2024-01-31
Group and Sort Results
openai-usage --group-by project day
Manage Pricing Data
Pricing is automatically fetched from litellm on first run and cached locally (~/.cache/openai-usage/pricing.json). To update manually:
openai-usage --update-pricing
To check cache status:
openai-usage --pricing-info
A warning is displayed if the cache is older than 30 days.
๐ณ Docker Usage
| Command | Description |
|---|---|
docker run --rm -e OPENAI_ADMIN_API_KEY="..." obeoneorg/openai-usage-report |
View all projects usage |
docker run --rm -e OPENAI_ADMIN_API_KEY="..." obeoneorg/openai-usage-report -l |
List projects |
docker run --rm -e OPENAI_ADMIN_API_KEY="..." obeoneorg/openai-usage-report -p proj_xxx |
Specific project |
Build locally:
docker build -t openai-usage-report ./openai-usage
โ๏ธ Options
| Argument | Short | Description | Default |
|---|---|---|---|
--help |
-h |
Show the help message and exit | |
--list-projects |
-l |
List available projects and exit | |
--projects [ID ...] |
-p |
One or more project IDs to analyze | All projects |
--start-date YYYY-MM-DD |
-sd |
Start date for the usage report | Start of current month |
--end-date YYYY-MM-DD |
-ed |
End date for the usage report | End of current month |
--group-by [CRITERIA ...] |
-gb |
Criteria to group and sort results (order matters) | day |
--update-pricing |
Fetch latest pricing from litellm and update local cache | ||
--pricing-info |
Show pricing cache path, last update date, and model count |
Available Grouping Criteria: day, month, project, key, model
๐ License
MIT โ Grรฉgoire Compagnon (@obeone)
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
openai_usage_report-0.4.1.tar.gz
(14.1 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file openai_usage_report-0.4.1.tar.gz.
File metadata
- Download URL: openai_usage_report-0.4.1.tar.gz
- Upload date:
- Size: 14.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.14.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
28919bf67bf34b24c3d37d06727d879eb7142468f9621460dade90e04430cc16
|
|
| MD5 |
48af2e40cc142f26d75c6c21d3bde24c
|
|
| BLAKE2b-256 |
8e15539cad164595d838632bd540a13ced3ff9c786c0037fcf6de97f4ee674c8
|
File details
Details for the file openai_usage_report-0.4.1-py3-none-any.whl.
File metadata
- Download URL: openai_usage_report-0.4.1-py3-none-any.whl
- Upload date:
- Size: 13.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.14.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
53db090017f0ad0ffd986843761a491cf9086c2acd6ac0a4b1ee7578b504549d
|
|
| MD5 |
790b577690094ad625f99b1146990ba5
|
|
| BLAKE2b-256 |
6aca5b834cdce548a1763a28af20c1018df7ae7f3b1c7622ffd1a69e24d01d27
|
