openrouter-usage

name	openrouter-usage
description	Fetch real-time OpenRouter usage totals and historical per-model spend. Use when the user asks for usage, spend, cost breakdown, or OpenRouter stats. Not for system health or non-LLM metrics.
license	Apache-2.0
compatibility	Requires internet access. Primary path uses python3. Optional fallback uses curl (+ jq if available).
required-env-vars	["OPENROUTER_API_KEY"]
optional-env-vars	["OPENROUTER_MGMT_KEY"]
primary-credential	OPENROUTER_API_KEY
credential-description	OpenRouter API key
metadata	{"author":"Arkology Studio","version":"1.1"}
allowed-tools	Bash(python3:*) Bash(curl:*) Bash(jq:*) Read

OpenRouter 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:

1. Environment variables (recommended for security)
2. credentials.env file 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

• /activity only returns completed UTC days.
• Today’s spend may appear in totals but not per-model data until next UTC rollover.
• Invalid keys → 401/403.