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)
Metadata
Release files for openai-usage-report 0.4.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| openai_usage_report-0.4.1.tar.gz | 14.1 kB | Without provenance | Details for openai_usage_report-0.4.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| openai_usage_report-0.4.1-py3-none-any.whl | Python 3 | none | any | Details for openai_usage_report-0.4.1-py3-none-any.whl |
Total release size: 28.0 kB
Release files / openai_usage_report-0.4.1.tar.gz
| Download URL | openai_usage_report-0.4.1.tar.gz |
|---|---|
| Size | 14.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
28919bf67bf34b24c3d37d06727d879eb7142468f9621460dade90e04430cc16
|
|
BLAKE2b-256 checksum How to use checksums |
8e15539cad164595d838632bd540a13ced3ff9c786c0037fcf6de97f4ee674c8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Release files / openai_usage_report-0.4.1-py3-none-any.whl
| Download URL | openai_usage_report-0.4.1-py3-none-any.whl |
|---|---|
| Size | 13.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
53db090017f0ad0ffd986843761a491cf9086c2acd6ac0a4b1ee7578b504549d
|
|
BLAKE2b-256 checksum How to use checksums |
6aca5b834cdce548a1763a28af20c1018df7ae7f3b1c7622ffd1a69e24d01d27
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Security for openai-usage-report 0.4.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.