Balance & spend API

Four read-only endpoints answer "how much do I have left?" and "how much have I spent?" without opening the console. They authenticate with the same API key you use for model calls, are not billed, and are answered by RouteMux itself.

Send the key the same way as for model calls — see Authentication. All amounts are in USD.

Account balance and spend

curl https://api.routemux.com/v1/account/info \
  -H "Authorization: Bearer $ROUTEMUX_API_KEY"

{
  "data": {
    "wallet": {
      "available_credit_usd": "42.180000",
      "total_credit_usd": "42.180000",
      "negative_credit_limit_usd": "0.000000",
      "month_spend_usd": "57.820000",
      "day_spend_usd": "3.410000"
    },
    "burn_rate": {
      "avg_daily_usd": "1.927333",
      "days_remaining": 21
    },
    "alerts": { "balance_low_threshold_usd": "5.000000" },
    "auto_topup": null,
    "campaign_credits": []
  },
  "requestId": "…"
}

Spend covers every key on the account. It counts what you were actually charged, including charges paid from bonus credit; failed requests count as 0. A request shows up in spend once it settles — while it is still running, it only lowers available_credit_usd through its reservation.

Per-key spend and limits

curl https://api.routemux.com/v1/key/info \
  -H "Authorization: Bearer $ROUTEMUX_API_KEY"

{
  "data": {
    "key": {
      "id": "…",
      "name": "prod-backend",
      "tags": [],
      "status": "active",
      "expires_at": null
    },
    "wallet": {
      "available_credit_usd": "42.180000",
      "today_spend_usd": "3.410000",
      "month_spend_usd": "57.820000"
    },
    "limits": {
      "monthly_credit_limit_usd": "50.000000",
      "monthly_used_usd": "12.500000",
      "monthly_remaining_usd": "37.500000",
      "daily_credit_limit_usd": null,
      "daily_used_usd": "0.830000",
      "daily_remaining_usd": null,
      "allowed_models": [],
      "rate_windows": []
    }
  },
  "requestId": "…"
}

Simple balance

For scripts and tools that just want one number:

curl https://api.routemux.com/v1/user/balance \
  -H "Authorization: Bearer $ROUTEMUX_API_KEY"

{ "balance": 37.5, "is_active": true, "currency": "USD" }

balance is what this key can still spend: the smallest of your available wallet balance, the key's remaining monthly cap and its remaining daily cap. A key with a small cap therefore shows less than your wallet holds.

Unlike the other endpoints, this one returns a bare object (no data wrapper) and balance is a number, not a string. It is also served at /user/balance for tools whose base URL is the host root.

OpenAI-style billing endpoints

Some tools read a provider's balance from OpenAI's billing endpoints. Both are supported, with or without the /v1 prefix:

curl https://api.routemux.com/v1/dashboard/billing/subscription \
  -H "Authorization: Bearer $ROUTEMUX_API_KEY"

{
  "object": "billing_subscription",
  "has_payment_method": true,
  "soft_limit_usd": 37.5,
  "hard_limit_usd": 37.5,
  "system_hard_limit_usd": 37.5,
  "access_until": 0
}

hard_limit_usd carries the same number as balance above. GET /v1/dashboard/billing/usage always returns total_usage: 0, so a tool that computes "limit minus usage" lands on your real balance. It does not report what you spent — use /v1/account/info for that.

The cost of a single request

These endpoints return totals, not per-request charges. Each request's exact charge is listed in Logs in the console — see Observability & usage.

When the key itself can't be used

These endpoints run the same key checks as model calls. A key that could not make a model call right now gets an error here too, instead of a balance:

So a successful response always describes a usable key — is_active is true and key.status is active. If you want to watch account-wide balance even while one key is capped, query it with a key that has no cap.

Rate limits

Each key can call these endpoints up to 60 times per minute, and each IP address up to 300 times per minute. Beyond that you get HTTP 429 LIMIT_RATE_EXCEEDED with a Retry-After header. Polling once a minute is plenty.

Errors use the same envelope as model calls — see Errors.