obeoneorg/openai-usage-report repository overview
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)
Tag summary
Content type
Image
Digest
sha256:ea1f9b32e…
Size
44 MB
Last updated
about 1 month ago
docker pull obeoneorg/openai-usage-report