PlatformDocumentation

Cost & usage API

Read each request's cost, daily usage, your balance, and key limits with your API key.

On this page

Read what your requests cost from code, with the same API key and base URL you use for inference. Every figure is the exact amount billed to your balance, in USD.

Endpoint	Returns
`GET /v1/generation?id=…`	Cost, token counts, and latency for one request
`GET /v1/usage`	Daily spend, requests, and tokens per model
`GET /v1/credits`	Account balance: credited, spent, remaining
`GET /v1/key`	The calling key's spend, limit, and rate limits

All four use the base URL https://api.routerplex.com and accept the key as Authorization: Bearer or x-api-key. Responses wrap their payload in data, the same shape OpenRouter uses for its credits, key, and generation endpoints, so code written for those keeps working after you change the base URL.

Cost of each request #

Every inference response carries an x-routerplex-request-id header. Non-streaming Chat Completions responses also carry x-routerplex-cost, the billed cost in USD:

text

x-routerplex-request-id: rpx-1791118696.591-9a58bc8710bf50dc18af295cad8e63e2
x-routerplex-cost: 0.00009924

A stream sends its headers before the cost exists, and Anthropic Messages responses do not include it. For those, look the request up afterwards.

Look up one request #

Pass either the x-routerplex-request-id header or the id field of a Chat Completions response. For Anthropic Messages (including Claude Code), use the header: the id in a Messages response cannot be looked up.

bash

curl "https://api.routerplex.com/v1/generation?id=rpx-1791118696.591-9a58bc8710bf50dc18af295cad8e63e2" \
  -H "Authorization: Bearer $ROUTERPLEX_API_KEY"

json

{
  "data": {
    "id": "chatcmpl-686b85f0-7cfd-4df6-8298-bc0046ae819d",
    "routerplex_request_id": "rpx-1791118696.591-9a58bc8710bf50dc18af295cad8e63e2",
    "model": "claude-haiku-4-5",
    "status": "success",
    "created_at": "2026-10-04T12:58:16.591+00:00",
    "latency_ms": 2410,
    "time_to_first_token_ms": 2398,
    "made_with_this_key": true,
    "usage": {
      "prompt_tokens": 177,
      "completion_tokens": 8,
      "total_tokens": 185,
      "cached_tokens": 128,
      "cache_write_tokens": 0,
      "reasoning_tokens": 0
    },
    "total_cost": 0.00009924,
    "cost_breakdown": {
      "input": 0.00005924,
      "cache_read": 0.00001024,
      "cache_write": 0.0,
      "output": 0.00004
    },
    "currency": "USD"
  }
}

cost_breakdown.input includes cache_read and cache_write, so total_cost equals input plus output. A request appears a few seconds after it finishes, and always within a minute; until then the endpoint returns 404 with code not_found. Any key on your account can look up any of the account's requests.

Usage over time #

bash

curl "https://api.routerplex.com/v1/usage?start_date=2026-10-01&end_date=2026-10-04" \
  -H "Authorization: Bearer $ROUTERPLEX_API_KEY"

Parameter	Default	Meaning
`start_date`	29 days before `end_date`	First UTC day, `YYYY-MM-DD`
`end_date`	Today	Last UTC day, inclusive
`scope`	`account`	`account` for every key, or `key` for only the key making the call

The window is at most 92 days. The response has a total and one entry per day with activity, each split by model:

json

{
  "data": {
    "scope": "account",
    "start_date": "2026-10-01",
    "end_date": "2026-10-04",
    "currency": "USD",
    "total": {
      "cost": 0.4821,
      "requests": 212,
      "successful_requests": 209,
      "failed_requests": 3,
      "prompt_tokens": 1830411,
      "completion_tokens": 40210,
      "cached_tokens": 1402880,
      "cache_write_tokens": 61200
    },
    "days": [
      {
        "date": "2026-10-04",
        "cost": 0.1203,
        "requests": 58,
        "successful_requests": 58,
        "failed_requests": 0,
        "prompt_tokens": 455120,
        "completion_tokens": 9870,
        "cached_tokens": 351744,
        "cache_write_tokens": 15300,
        "models": {
          "claude-sonnet-5": {
            "cost": 0.1203,
            "requests": 58,
            "successful_requests": 58,
            "failed_requests": 0,
            "prompt_tokens": 455120,
            "completion_tokens": 9870,
            "cached_tokens": 351744,
            "cache_write_tokens": 15300
          }
        }
      }
    ]
  }
}

Balance #

bash

curl https://api.routerplex.com/v1/credits -H "Authorization: Bearer $ROUTERPLEX_API_KEY"

json

{
  "data": {
    "total_credits": 25.0,
    "total_usage": 3.21,
    "balance": 21.79,
    "currency": "USD"
  }
}

total_credits is everything ever added to the account, including bonus credit; balance is what remains to spend.

The calling key #

bash

curl https://api.routerplex.com/v1/key -H "Authorization: Bearer $ROUTERPLEX_API_KEY"

json

{
  "data": {
    "name": "claude-code",
    "label": "sk-...ucqw",
    "usage": 1.25,
    "limit": 5.0,
    "limit_remaining": 3.75,
    "rate_limit": {
      "requests_per_minute": null,
      "tokens_per_minute": null
    },
    "models": null,
    "blocked": false,
    "created_at": "2026-10-04T12:56:07.382000+00:00",
    "expires_at": null
  }
}

limit is the key's own budget, or null when it has none. models is null when the key can call every model. The account balance still applies to every key.

Track spend in your code #

This Python example sends a request, then records what it cost:

python

import os
import time
 
import httpx
 
BASE = "https://api.routerplex.com"
HEADERS = {"Authorization": f"Bearer {os.environ['ROUTERPLEX_API_KEY']}"}
 
reply = httpx.post(
    f"{BASE}/v1/chat/completions",
    headers=HEADERS,
    json={"model": "claude-sonnet-4-6", "messages": [{"role": "user", "content": "Hello"}]},
    timeout=120,
)
reply.raise_for_status()
print("cost from header:", reply.headers.get("x-routerplex-cost"))
 
request_id = reply.headers["x-routerplex-request-id"]
for _ in range(12):
    lookup = httpx.get(f"{BASE}/v1/generation", params={"id": request_id}, headers=HEADERS)
    if lookup.status_code == 200:
        data = lookup.json()["data"]
        print(data["model"], data["total_cost"], data["usage"])
        break
    time.sleep(5)
 
balance = httpx.get(f"{BASE}/v1/credits", headers=HEADERS).json()["data"]["balance"]
print(f"balance left: ${balance:.2f}")

Errors and limits #

Errors use the same shape as the inference API:

json

{
  "error": {
    "message": "This API key is not valid.",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Status	Code	Meaning
`401`	`invalid_api_key`	Missing, unknown, or expired key
`400`	`invalid_request`	Malformed id, bad dates, or a window over 92 days
`404`	`not_found`	No such request on your account yet
`503`	`unavailable`	Account data is briefly unavailable; retry

These endpoints are rate limited separately from inference, at about 30 requests per second per client. Poll /v1/credits every few minutes at most; it changes only when you spend or top up.