Usage Limits

Set per-user or per-group token and cost budgets that reset daily or monthly.

Usage Limits give admins fine-grained control over how much any individual user or group can consume. Set a daily token cap for a pilot group, a monthly cost ceiling for a department, or a hard block that stops users when they hit their limit.

Prerequisite

Cost-based limits require Model Pricing to be configured. Without per-model prices, cost_usd on messages is null and cost limits cannot be evaluated.

---

Limit anatomy

Each limit has five dimensions:

Field	Values	Description
Scope	user / group	Whether this limit targets one user or all users in a group
Scope ID	user ID or group ID	The specific user or group
Limit type	tokens / cost_usd	Count raw tokens or accumulated USD spend
Period	daily / monthly	When the counter resets
Limit value	number	The threshold (e.g., 1000000 tokens or 50.00 USD)

Two additional settings control behavior when usage approaches or crosses the threshold:

Field	Default	Description
hard_limit	true	If true, requests are blocked once the limit is reached. If false, it's a soft cap — the user is warned but not blocked.
alert_threshold_pct	80	Percentage of the limit at which the user starts seeing an alert banner

---

Setting a limit

Via the Admin Panel

Go to Admin Panel > Usage Limits and click Add Limit. Fill in the fields and save.

Via API

PUT /api/v1/usage-limits
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "scope": "group",
  "scope_id": "group-uuid-here",
  "limit_type": "tokens",
  "limit_value": 5000000,
  "period": "monthly",
  "hard_limit": true,
  "alert_threshold_pct": 80
}

One limit per combination

The (scope, scope_id, limit_type, period) combination is unique — upserting with the same combination updates the existing limit.

---

Viewing your own usage

Any authenticated user can check their own consumption:

GET /api/v1/usage-limits/me
Authorization: Bearer <user-token>

Returns a list of all limits that apply to the current user (both direct user limits and limits from groups they belong to), with current usage figures and percentage consumed.

To see only limits where you've crossed the alert threshold:

GET /api/v1/usage-limits/me/alerts

---

Examples

Cap a free-tier group at 1M tokens/day

{
  "scope": "group",
  "scope_id": "free-tier-group-id",
  "limit_type": "tokens",
  "limit_value": 1000000,
  "period": "daily",
  "hard_limit": true,
  "alert_threshold_pct": 90
}

Give a department a $200/month budget with warnings at $160

{
  "scope": "group",
  "scope_id": "finance-team-group-id",
  "limit_type": "cost_usd",
  "limit_value": 200.00,
  "period": "monthly",
  "hard_limit": false,
  "alert_threshold_pct": 80
}

Give a single power user a higher personal allowance

{
  "scope": "user",
  "scope_id": "user-uuid-here",
  "limit_type": "tokens",
  "limit_value": 10000000,
  "period": "monthly",
  "hard_limit": true,
  "alert_threshold_pct": 75
}

---

API reference

Method	Path	Auth	Description
GET	/api/v1/usage-limits	Admin	List all configured limits
PUT	/api/v1/usage-limits	Admin	Create or update a limit
DELETE	/api/v1/usage-limits/{limit_id}	Admin	Delete a limit
GET	/api/v1/usage-limits/me	User	Get current user's usage status
GET	/api/v1/usage-limits/me/alerts	User	Get limits currently over the alert threshold

---

FAQ

Does a group limit also affect admins? No. Admin users bypass hard limits to avoid locking out instance operators.

What happens when a hard limit is hit? The chat completion request returns a 429 Too Many Requests response with a message explaining which limit was exceeded and when it resets.

Are limits cumulative if a user belongs to multiple groups? Each limit is evaluated independently. If a user is in Group A (capped at 1M tokens/day) and Group B (capped at 500k tokens/day), the most restrictive applicable hard limit applies.

Can I set different limits for different models? Currently limits are instance-wide across all models. Per-model limits are on the roadmap.