Monitoring OpenRouter Spend and Usage in Real Time

You cannot control agent cost you do not measure. OpenRouter exposes inline usage on every completion, key balance endpoints, generation lookup, and (with a management key) analytics queries.

Summary

Log usage from each chat response into your metrics backend, poll GET /api/v1/key for remaining budget, and use Activity UI or the Analytics API for model/key rollups when investigating spikes.

Recipe

1. Emit structured logs on every OpenRouter call: generation_id, model, provider (if present), tokens, usage.cost, route tier, agent name, tenant id.
2. Treat inline usage as the real-time source of truth (always included; legacy usage.include flags are deprecated/no-ops).
3. On streaming, read usage from the final chunk.
4. Poll GET /api/v1/key every N minutes (or before batches) for limit_remaining, usage_daily, and friends.
5. For spike analysis, create a management key and query Analytics (/api/v1/analytics/meta then /api/v1/analytics/query) or use the Activity dashboard.
6. Optionally fetch /api/v1/generation?id=... (path verify at build) for historical cost audit by generation id.
7. Alert on: daily spend velocity, 402 rate, cost per successful task, and sudden model-mix shifts toward frontier slugs.

Working Example

import os
import time
import requests
from openai import OpenAI
 
client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
)
 
def chat_and_meter(messages, model="openai/gpt-4o-mini", **provider):
    t0 = time.perf_counter()
    resp = client.chat.completions.create(
        model=model,
        messages=messages,
        extra_body={"provider": provider} if provider else None,
    )
    latency_ms = (time.perf_counter() - t0) * 1000
    usage = resp.usage
    # OpenAI SDK may expose usage as object; normalize
    cost = getattr(usage, "cost", None)
    if cost is None and isinstance(usage, dict):
        cost = usage.get("cost")
    record = {
        "id": resp.id,
        "model": resp.model,
        "latency_ms": latency_ms,
        "prompt_tokens": getattr(usage, "prompt_tokens", None),
        "completion_tokens": getattr(usage, "completion_tokens", None),
        "cost": cost,
    }
    print("meter", record)  # replace with metrics.export
    return resp.choices[0].message.content, record
 
chat_and_meter([{"role": "user", "content": "hello"}], sort="price")
 
# Key-level remaining budget
key = requests.get(
    "https://openrouter.ai/api/v1/key",
    headers={"Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}"},
)
key.raise_for_status()
print("key_budget", key.json()["data"])

Analytics rollup (management key; API is beta - verify schema at build):

import os
import requests
from datetime import datetime, timedelta, timezone
 
mgmt = os.environ["OPENROUTER_MANAGEMENT_KEY"]
headers = {
    "Authorization": f"Bearer {mgmt}",
    "Content-Type": "application/json",
}
 
meta = requests.get("https://openrouter.ai/api/v1/analytics/meta", headers=headers)
meta.raise_for_status()  # discover metrics/dimensions; do not hardcode forever
 
end = datetime.now(timezone.utc)
start = end - timedelta(days=7)
query = {
    "metrics": ["total_usage", "request_count", "tokens_total", "cache_hit_rate"],
    "dimensions": ["model"],
    "order_by": {"field": "total_usage", "direction": "desc"},
    "time_range": {
        "start": start.strftime("%Y-%m-%dT%H:%M:%SZ"),
        "end": end.strftime("%Y-%m-%dT%H:%M:%SZ"),
    },
    "limit": 20,
}
resp = requests.post(
    "https://openrouter.ai/api/v1/analytics/query",
    headers=headers,
    json=query,
)
resp.raise_for_status()
print(resp.json())

Deep Dive

Three horizons of observability

Cost fields

Inline usage commonly includes:

• prompt_tokens / completion_tokens / total_tokens
• cost - charged amount
• cost_details.upstream_inference_cost - upstream charge (especially meaningful for BYOK contexts; generation lookup notes differ - verify)
• Cache and reasoning token details when applicable

For streaming, ignore intermediate chunks without usage; meter the final usage payload.

Credits endpoint

OpenRouter also exposes credit balance APIs for account-level remaining credits (see credits API reference at build). Use that for org dashboards; use /key for the specific runtime credential.

Generation id follow-up

Store resp.id from completions. Later, generation metadata endpoints let you re-read cost for disputes and audits without trusting only local logs.

Agent-specific metrics

Track more than tokens:

1. Cost per successful task (not per call)
2. Calls per task (loop amplification)
3. Fallback rate (provider or model changes)
4. 402 / 429 counts
5. Share of spend on hard-tier models

A stable token rate with rising calls/task means the agent, not the price sheet, regressed.

Gotchas

1. Analytics need a management key. Inference keys get 403 on admin analytics.
2. Truncated analytics pages. Check metadata.truncated before summing.
3. Dimension limits. Analytics may allow at most two dimensions per query (beta behavior - verify).
4. SDK shape drift. usage.cost may need model_extra or raw JSON depending on SDK version.
5. Clock skew on daily usage. OpenRouter daily windows are UTC.
6. Logging prompts by default is a privacy incident. Meter tokens/cost/ids; sample raw prompts only in secure stores with policy approval.
7. Real-time is not infinite cardinality. Bound labels (agent, tier, model) to avoid metrics explosions.

Alternatives

FAQs

Related

Related: Setting Spend Limits and Usage Caps per API Key

Related: Cost-Based Routing: Sending Cheap Tasks to Cheap Models

Related: Comparing OpenRouter's Per-Model Pricing Against Direct Provider Rates

Related: OpenRouter Cost & Fallback Best Practices

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.