Skip to main content
Version: 0.6.0

Budgets & Limits

Routerly has a three-level budget hierarchy that lets you control spending at the platform, router, and individual-token levels. Budgets can be configured for any metric — cost, call count, or token usage — over a rolling or calendar window.


Budget Hierarchy​

Global budget
└── Router budget
└── Per-token budget

A request must pass all applicable budget checks before Routerly forwards it to a provider. If any budget is exhausted, Routerly returns 503 Service Unavailable with a descriptive message.

Passthrough routers are not covered

None of the budget or limit checks on this page apply to Passthrough routers. A Passthrough router forwards the request with the client's own upstream credential and no model resolution, so Routerly has no price to attribute — usage records for that traffic always show cost: null. Set budgets on the model or token as usual for regular routers; a Passthrough router bypasses them entirely, by design, regardless of any budget configured elsewhere in the account.


Budget Levels​

Global budget​

Applies to all requests across all routers. Useful for setting a hard ceiling on total platform spending.

Configure via Dashboard → Settings → Budgets or in settings.json.

Router budget​

Applies to all requests through a specific router. Configure per router via the General tab in the router settings.

Per-token budget​

Applies to requests made with a specific router token. Configured in the router's Tokens tab. Per-token limits are useful when different applications share a router and you want to isolate their spending.

Spend groups (org / team)​

Spend groups add an org- and team-level tier on top of the model/router/token limits, giving a full cascade:

Organisation group
└── Team group
└── Router (spendGroupId) → per-token budget

A router joins a group via its spendGroupId, and groups nest via parentGroupId. Usage is attributed to a group by the routers that belong to it and to its descendant groups. When a request runs through a router in a group, every group in the parent chain must have budget remaining, in addition to the per-model/router/token checks. Child group limits cannot exceed their parent's matching limit — this is validated when creating or updating a group.

Spend groups use the same Limit shape (metrics, period/rolling windows) as the other levels. Manage them via the /api/spend-groups endpoints (see the Management API reference).


Metrics​

Each budget limit tracks one metric:

MetricDescription
costUSD cost calculated from token prices
callsTotal number of API requests
input_tokensTotal input tokens consumed
output_tokensTotal output tokens generated
total_tokensSum of input and output tokens

Window Types​

Budgets reset based on the configured window type.

Period windows​

Reset at the start of each calendar period:

WindowResets
hourlyTop of each hour
dailyMidnight (UTC)
weeklyMonday midnight (UTC)
monthly1st of each month
yearlyJanuary 1st

Rolling windows​

Track usage over a sliding time window:

WindowPeriod
rolling_secondLast 1 second
rolling_minuteLast 60 seconds
rolling_hourLast 3,600 seconds
rolling_dayLast 86,400 seconds
rolling_weekLast 7 days
rolling_monthLast 30 days

Limit Modes (per-token budgets)​

When a per-token budget is configured, the mode field controls how it interacts with the parent router budget:

ModeBehaviour
replaceThe per-token limit overrides the router limit entirely for this token
extendThe per-token limit stacks on top of the router limit (both must pass)
disableNo budget limit for this token, regardless of router limits

Configuring Budgets​

Dashboard​

Global budget (per model): Open Models, edit the model, then the Limits section. Per-token budget: Open the router → Tokens tab → click the edit icon next to a token. The editor shows the limit inherited from the model so you can see what you are overriding.

CLI​

Global limits are set on the model, either with the two cost shorthands or with the full limits array:

routerly model edit gpt-5-mini --daily-budget 5.00 --monthly-budget 50.00

routerly model edit gpt-5-mini --limits-json \
'[{"metric":"cost","windowType":"period","period":"monthly","value":100},
{"metric":"calls","windowType":"rolling","rollingAmount":1,"rollingUnit":"minute","value":60}]'

Per-token limits are set on the token, one spec per model:

routerly router token edit "My App" <token-id> \
--add-limit "gpt-5-mini:cost:period:daily:5"
note

The router level (limits on a router's model entry) is honoured at request time but has no dashboard or CLI editor yet: it can only be written directly in routers.json. Set budgets on the model or on the token instead.


What Happens When a Budget Is Exhausted​

  • Routerly returns HTTP 503 with a JSON error body:
    {"error":"budget_exceeded","message":"Monthly cost limit for router 'my-app' reached ($50.00)"}
  • The response is immediate — no provider API call is made.
  • Once the budget window resets (e.g. at the start of next month), requests are accepted again automatically.

Notifications​

You can configure Routerly to send an alert when a budget reaches a configured threshold (e.g. 80% used) or when it is exhausted. See Concepts: Notifications for setup.