Budgets & Limits
Routerly has a three-level budget hierarchy that lets you control spending at the platform, project, 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
└── Project 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.
Budget Levels
Global budget
Applies to all requests across all projects. Useful for setting a hard ceiling on total platform spending.
Configure via Dashboard → Settings → Budgets or in settings.json.
Project budget
Applies to all requests through a specific project. Configure per project via the General tab in the project settings.
Per-token budget
Applies to requests made with a specific project token. Configured in the project's Tokens tab. Per-token limits are useful when different applications share a project 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/project/token limits, giving a full cascade:
Organisation group
└── Team group
└── Project (spendGroupId) → per-token budget
A project joins a group via its spendGroupId, and groups nest via
parentGroupId. Usage is attributed to a group by the projects that belong to
it and to its descendant groups. When a request runs through a project in a
group, every group in the parent chain must have budget remaining, in addition
to the per-model/project/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:
| Metric | Description |
|---|---|
cost | USD cost calculated from token prices |
calls | Total number of API requests |
input_tokens | Total input tokens consumed |
output_tokens | Total output tokens generated |
total_tokens | Sum 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:
| Window | Resets |
|---|---|
hourly | Top of each hour |
daily | Midnight (UTC) |
weekly | Monday midnight (UTC) |
monthly | 1st of each month |
yearly | January 1st |
Rolling windows
Track usage over a sliding time window:
| Window | Period |
|---|---|
rolling_second | Last 1 second |
rolling_minute | Last 60 seconds |
rolling_hour | Last 3,600 seconds |
rolling_day | Last 86,400 seconds |
rolling_week | Last 7 days |
rolling_month | Last 30 days |
Limit Modes (per-token budgets)
When a per-token budget is configured, the mode field controls how it interacts with the parent project budget:
| Mode | Behaviour |
|---|---|
replace | The per-token limit overrides the project limit entirely for this token |
extend | The per-token limit stacks on top of the project limit (both must pass) |
disable | No budget limit for this token, regardless of project limits |
Configuring Budgets
Dashboard
Project budget: Open the project → General tab → Budget section. Per-token budget: Open the project → Tokens tab → click the edit icon next to a token. Global budget: Open Settings → Budgets.
CLI
You can set a project-level daily or monthly cost budget when adding a model to a project:
routerly project add-model \
--slug my-app \
--model gpt-5-mini \
--daily-budget 5.00 \
--monthly-budget 50.00
What Happens When a Budget Is Exhausted
- Routerly returns HTTP 503 with a JSON error body:
{"error":"budget_exceeded","message":"Monthly cost limit for project '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.