OpenRouter Usage

Query OpenRouter API costs and generate usage reports via the command line.

When to Use

• Checking OpenRouter spend over the last 30 days

• Breaking down costs by model, provider, or date

• Exporting usage data as CSV or JSON for accounting

• Auditing which models and API keys consume the most credits

Prerequisites

• OPENROUTER_API_KEY environment variable (or in a project .env file)

• The key must be a Management key — create one at https://openrouter.ai/settings/management-keys

• Regular provisioning keys return 401/403 on analytics endpoints

Usage

Full 30-day summary with credits balance

python3 ~/.claude/skills/openrouter-usage/scripts/openrouter_usage.py

Filter to a single date

python3 ~/.claude/skills/openrouter-usage/scripts/openrouter_usage.py --date 2026-02-01

Export as CSV (for spreadsheets)

python3 ~/.claude/skills/openrouter-usage/scripts/openrouter_usage.py --csv

Raw JSON output (for piping to jq)

python3 ~/.claude/skills/openrouter-usage/scripts/openrouter_usage.py --json

Skip credits lookup (activity only)

python3 ~/.claude/skills/openrouter-usage/scripts/openrouter_usage.py --no-credits

Output

The default report includes:

• Credits balance: total purchased, used, remaining

• Spend by model: per-model cost with token counts (prompt, completion, reasoning)

• Spend by provider: aggregated by provider (OpenAI, Anthropic, Google, etc.)

• Spend by date: daily spend with visual bar chart

API Endpoints

Both endpoints are read-only GETs authenticated via Bearer token:

Endpoint Purpose

GET /api/v1/credits

Total credits purchased and used

GET /api/v1/activity

Last 30 days of usage grouped by model/endpoint/provider

The activity endpoint returns per-row: date , model , provider_name , usage , byok_usage_inference , requests , prompt_tokens , completion_tokens , reasoning_tokens .