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)