OpenRouter Usage
Verified@rosseyre
npx machina-cli add skill @rosseyre/openrouter-usage --openclawOpenRouter Usage Monitor
What this skill does
Retrieves OpenRouter usage and cost data via:
- Live totals (Today / Week / Month) from
/auth/key - Historical per-model breakdown from
/activity(completed UTC days only)
How to run (recommended)
Set environment variables (recommended) or create a credentials.env file:
export OPENROUTER_API_KEY=your_key_here
export OPENROUTER_MGMT_KEY=your_mgmt_key_here # optional, enables model breakdown
Then execute: python3 scripts/stats.py
Alternatively, create credentials.env in the skill directory:
OPENROUTER_API_KEY=your_key_here
OPENROUTER_MGMT_KEY=your_mgmt_key_here
Fallback method (no Python)
If Python is unavailable, query endpoints directly:
Live totals curl -sS -H "Authorization: Bearer $OPENROUTER_API_KEY" https://openrouter.ai/api/v1/auth/key
Per-model activity (7d) curl -sS -H "Authorization: Bearer $OPENROUTER_MGMT_KEY" https://openrouter.ai/api/v1/activity
Configuration
Required:
OPENROUTER_API_KEY- Required for real-time usage totals and balance
Optional:
OPENROUTER_MGMT_KEY- Enables per-model spend breakdown from activity endpoint
Credentials can be provided via:
- Environment variables (recommended for security)
credentials.envfile in skill directory (fallback)
Output format
💰 OpenRouter Usage Today: $X.XX* | Week: $X.XX | Month: $X.XX Balance: $X.XX / $X.XX
Recent Models (7d):
• model-name: $X.XX (N)
...
* indicates live totals that may not yet appear in model breakdowns.
Edge cases
/activityonly returns completed UTC days.- Today’s spend may appear in totals but not per-model data until next UTC rollover.
- Invalid keys → 401/403.
- Rate limiting → 429.
- Network failures should be retried or surfaced.
Overview
OpenRouter Usage Monitor fetches real-time usage totals (Today/Week/Month) from OpenRouter /auth/key and a historical per-model spend breakdown from /activity. This lets you quantify current costs, monitor usage trends, and identify spend hotspots by model. Use this skill for usage, spend, cost breakdown, or OpenRouter stats, not for system health or non-LLM metrics.
How This Skill Works
Configure OPENROUTER_API_KEY (required) and optionally OPENROUTER_MGMT_KEY for per-model breakdown. The recommended path runs python3 scripts/stats.py to pull data from /auth/key and /activity. If Python is unavailable, you can fall back to curl calls to the same endpoints using your keys to obtain live totals and per-model activity.
When to Use It
- User asks for today’s OpenRouter usage totals.
- User asks for weekly or monthly OpenRouter usage totals.
- User requests a per-model spend breakdown (requires OPENROUTER_MGMT_KEY).
- User wants a cost overview or general OpenRouter statistics.
- User needs a quick balance snapshot and recent model spend.
Quick Start
- Step 1: Set OPENROUTER_API_KEY (and optionally OPENROUTER_MGMT_KEY) in your environment or credentials.env.
- Step 2: Run python3 scripts/stats.py (or use curl fallback to fetch /auth/key and /activity).
- Step 3: Read the output under '💰 OpenRouter Usage' for Today/Week/Month and per-model spend.
Best Practices
- Store API keys securely (prefer environment variables over credentials files).
- Only provide OPENROUTER_MGMT_KEY when per-model breakdown is required.
- Remember that /activity shows completed UTC days; today’s spend may lag until the next UTC rollover.
- Anticipate rate limits (429) and implement retries with backoff.
- Validate 401/403 responses and rotate keys if credentials are compromised.
Example Use Cases
- Show me today’s usage totals, plus weekly and monthly totals.
- Provide per-model spend for the last 7 days.
- List the top spend by model for the current month.
- Display the current balance and how much is left on the plan.
- Explain any discrepancy between live totals and 7-day activity data.
