Implement budget controls and cost limits for OpenRouter. Use when managing spending or preventing overruns. Trigger with phrases like 'openrouter budget', 'openrouter spending limit', 'cost control', 'openrouter billing alert'.
npxskills add jeremylongshore/claude-code-plugins-plus-skills--skill openrouter-cost-controlsLoading…
OpenRouter provides per-key credit limits, a credit balance API, and per-generation cost queries. Combined with client-side budget middleware, you can enforce hard spending caps at the key level and soft caps in your application. This skill covers key-level limits, per-request cost tracking, budget enforcement middleware, and alert systems.
sk-or-v1-...) exported as OPENROUTER_API_KEY — see the openrouter-install-auth skill for setuprequests; Node.js 18+ for the TypeScript per-request cost logger in the referencescurl, jq, and bc for the balance check and the Budget Alert ScriptOPENROUTER_MGMT_KEY if you provision per-key credit limits via POST /api/v1/keysGET /api/v1/auth/key per Check Credit Balance to see credits used, the key's limit, remaining balance, free-tier status, and rate limit.POST /api/v1/keys with a dollar limit (e.g. $50 for backend-prod) using the management key, then list keys to review usage against limits per service.BudgetEnforcer from Budget Enforcement Middleware: check_budget() rejects any request whose pre-flight estimate exceeds the per-request or daily cap, and record_cost() books the exact spend from GET /api/v1/generation?id=.:floor picks the cheapest provider, :free costs nothing where available, and the task-based ROUTING table sends classification to gpt-4o-mini and simple Q&A to Llama 3.1 8B.max_tokens on every request and enable auto-topup per Enterprise Considerations to cap completion cost without risking an outage.# Current balance and limits
curl -s https://openrouter.ai/api/v1/auth/key \
-H "Authorization: Bearer $OPENROUTER_API_KEY" | jq '{
credits_used: .data.usage,
credit_limit: .data.limit,
remaining: ((.data.limit // 0) - .data.usage),
is_free_tier: .data.is_free_tier,
rate_limit: .data.rate_limit
}'
import os, requests
MGMT_KEY = os.environ["OPENROUTER_MGMT_KEY"] # Management key
# Create a key with a $50 credit limit
resp = requests.post(
"https://openrouter.ai/api/v1/keys",
headers={"Authorization": f"Bearer {MGMT_KEY}"},
json={"name": "backend-prod", "limit": 50.0},
)
new_key = resp.json()["data"]["key"] # sk-or-v1-...
# List all keys with their limits and usage
keys = requests.get(
"https://openrouter.ai/api/v1/keys",
headers={"Authorization": f"Bearer {MGMT_KEY}"},
).json()
for k in keys.get("data", []):
print(f"{k['name']}: ${k.get('usage', 0):.4f} / ${k.get('limit', 'unlimited')}")
import os, time, requests
from openai import OpenAI
client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=os.environ["OPENROUTER_API_KEY"],
default_headers={"HTTP-Referer": "https://my-app.com", "X-Title": "my-app"},
)
class BudgetEnforcer:
"""Client-side budget enforcement with server-side cost verification."""
def __init__(self, daily_limit: float = 10.0, per_request_limit: float = 0.50):
self.daily_limit = daily_limit
self.per_request_limit = per_request_limit
self._daily_spend = 0.0
self._day = time.strftime("%Y-%m-%d")
def _reset_if_new_day(self):
today = time.strftime("%Y-%m-%d")
if today != self._day:
self._daily_spend = 0.0
self._day = today
def estimate_cost(self, model: str, prompt_tokens: int, max_tokens: int) -> float:
"""Pre-flight cost estimate using cached pricing."""
# Representative rates (fetch from /models in production)
RATES = {
"anthropic/claude-3.5-sonnet": (3.0, 15.0), # per 1M tokens
"openai/gpt-4o": (2.50, 10.0),
"openai/gpt-4o-mini": (0.15, 0.60),
"meta-llama/llama-3.1-8b-instruct": (0.06, 0.06),
}
prompt_rate, comp_rate = RATES.get(model, (3.0, 15.0))
return (prompt_tokens * prompt_rate / 1_000_000) + (max_tokens * comp_rate / 1_000_000)
def check_budget(self, model: str, prompt_tokens: int, max_tokens: int):
"""Raise if request would exceed budget."""
self._reset_if_new_day()
estimated = self.estimate_cost(model, prompt_tokens, max_tokens)
if estimated > self.per_request_limit:
raise ValueError(
f"Request estimated at ${estimated:.4f} exceeds per-request limit ${self.per_request_limit}"
)
if self._daily_spend + estimated > self.daily_limit:
raise ValueError(
f"Daily spend ${self._daily_spend:.4f} + request ${estimated:.4f} "
f"exceeds daily limit ${self.daily_limit}"
)
def record_cost(self, generation_id: str):
"""Record actual cost from generation endpoint."""
try:
gen = requests.get(
f"https://openrouter.ai/api/v1/generation?id={generation_id}",
headers={"Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}"},
timeout=5,
).json()
cost = float(gen.get("data", {}).get("total_cost", 0))
self._daily_spend += cost
return cost
except Exception:
return 0.0
budget = BudgetEnforcer(daily_limit=25.0, per_request_limit=1.0)
# :floor variant -- cheapest provider for a model
response = client.chat.completions.create(
model="anthropic/claude-3.5-sonnet:floor", # Cheapest provider
messages=[{"role": "user", "content": "Summarize this..."}],
max_tokens=500,
)
# :free variant -- free providers (where available)
response = client.chat.completions.create(
model="google/gemma-2-9b-it:free",
messages=[{"role": "user", "content": "Hello"}],
max_tokens=100,
)
# Route simple tasks to cheap models
ROUTING = {
"classification": "openai/gpt-4o-mini", # $0.15/$0.60 per 1M
"summarization": "anthropic/claude-3-haiku", # $0.25/$1.25 per 1M
"code_generation": "anthropic/claude-3.5-sonnet", # $3/$15 per 1M
"simple_qa": "meta-llama/llama-3.1-8b-instruct", # $0.06/$0.06 per 1M
}
#!/bin/bash
# Alert when credits drop below threshold
THRESHOLD=5.0
REMAINING=$(curl -s https://openrouter.ai/api/v1/auth/key \
-H "Authorization: Bearer $OPENROUTER_API_KEY" | \
jq '((.data.limit // 0) - .data.usage)')
if (( $(echo "$REMAINING < $THRESHOLD" | bc -l) )); then
echo "ALERT: OpenRouter credits low: \$$REMAINING remaining"
# Send to Slack, PagerDuty, etc.
fi
credits_used, credit_limit, remaining, is_free_tier, and rate_limit for the active keyusage / limit listing from the management APIValueError rejections from the middleware when a request would exceed the per-request or daily budget, and a running daily-spend total booked from actual generation costsALERT: OpenRouter credits low: $4.87 remaining whenever the balance crosses the configured thresholdCheck what's left on a key before turning on traffic:
curl -s https://openrouter.ai/api/v1/auth/key \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
| jq '{used: .data.usage, limit: .data.limit, remaining: (.data.limit - .data.usage)}'
Expected output:
{"used": 3.42, "limit": 50, "remaining": 46.58}
More worked examples, including thread-safe budget middleware and a TypeScript cost logger: references/examples.md.
| Error | Cause | Fix |
|---|---|---|
| 402 Payment Required | Credits exhausted | Top up at openrouter.ai/credits or use :free model |
| 402 Key limit reached | Per-key credit limit hit | Increase key limit or create new key |
| Budget middleware rejects | Client-side limit exceeded | Increase limit or optimize prompt tokens |
| Stale pricing data | Cached rates outdated | Refresh from /api/v1/models daily |
/api/v1/generation?id= after each request for exact cost auditing:floor variant to automatically pick the cheapest provider for a modelmax_tokens on every request to cap completion cost
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).