openrouter-usage

# 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 ```bash # 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`.