API reference: Quotas

The quotas API manages per-user and per-group usage limits. Quotas enforce daily and monthly caps on token consumption, request count, and cost. When a quota is exceeded, subsequent requests from the affected user or group return HTTP 429.

All endpoints require admin authentication.

Base path: /api/admin

---

Endpoints

Method	Path	Description
GET	/api/v1/admin/users/{user_id}/quota	Get quota for a user
PUT	/api/v1/admin/users/{user_id}/quota	Create or update quota for a user
DELETE	/api/v1/admin/users/{user_id}/quota	Remove quota for a user
GET	/api/v1/admin/groups/{group_id}/quota	Get quota for a group
PUT	/api/v1/admin/groups/{group_id}/quota	Create or update quota for a group
DELETE	/api/v1/admin/groups/{group_id}/quota	Remove quota for a group

---

QuotaConfig object (request body)

Used when creating or updating a quota. All fields are optional — omit any limit you do not want to enforce.

Field	Type	Description
daily_token_limit	integer | null	Maximum tokens per day. null = no limit.
monthly_token_limit	integer | null	Maximum tokens per calendar month. null = no limit.
daily_request_limit	integer | null	Maximum requests per day. null = no limit.
monthly_request_limit	integer | null	Maximum requests per calendar month. null = no limit.
daily_cost_limit_usd	float | null	Maximum spend per day (USD). null = no limit.
monthly_cost_limit_usd	float | null	Maximum spend per calendar month (USD). null = no limit.

---

QuotaResponse object

Returned by GET and PUT endpoints.

Field	Type	Description
scope	string	"user" or "group"
id	UUID	UUID of the user or group this quota applies to
limits	object	The configured limits (same fields as QuotaConfig)
usage	object	Current period usage (see below)

usage object:

Field	Type	Description
daily_tokens	integer	Tokens consumed today (resets at UTC midnight)
monthly_tokens	integer	Tokens consumed this calendar month
daily_requests	integer	Requests made today
monthly_requests	integer	Requests made this calendar month
daily_cost_usd	float	Spend today (USD)
monthly_cost_usd	float	Spend this calendar month (USD)

---

User quota endpoints

GET /api/v1/admin/users/{user_id}/quota

Get the quota configuration and current usage for a user.

Path parameters:

Parameter	Type	Description
user_id	UUID	The user’s UUID

Response 200 OK:

{
  "scope": "user",
  "id": "usr_01abc123-...",
  "limits": {
    "daily_token_limit": 100000,
    "monthly_token_limit": 2000000,
    "daily_request_limit": 500,
    "monthly_request_limit": null,
    "daily_cost_limit_usd": null,
    "monthly_cost_limit_usd": 50.0
  },
  "usage": {
    "daily_tokens": 34820,
    "monthly_tokens": 890200,
    "daily_requests": 120,
    "monthly_requests": 3450,
    "daily_cost_usd": 1.24,
    "monthly_cost_usd": 31.80
  }
}

Response 404 Not Found: User not found or user has no quota configured.

---

PUT /api/v1/admin/users/{user_id}/quota

Create or update the quota for a user. This is an upsert — if the user has no quota, one is created; if they do, it is replaced with the new values.

Path parameters:

Parameter	Type	Description
user_id	UUID	The user’s UUID

Request body: QuotaConfig object.

PUT /api/v1/admin/users/usr_01abc123-.../quota
Authorization: Bearer <admin_token>
Content-Type: application/json

{
  "daily_token_limit": 100000,
  "monthly_token_limit": 2000000,
  "daily_request_limit": 500,
  "monthly_request_limit": null,
  "daily_cost_limit_usd": null,
  "monthly_cost_limit_usd": 50.0
}

Response 200 OK: The updated QuotaResponse object.

Response 404 Not Found: User does not exist or does not belong to the admin’s tenant.

---

DELETE /api/v1/admin/users/{user_id}/quota

Remove the quota for a user. After deletion, the user has no usage limits unless a group quota applies.

Path parameters:

Parameter	Type	Description
user_id	UUID	The user’s UUID

Response 204 No Content: Quota deleted.

Response 404 Not Found: User not found or user has no quota configured.

---

Group quota endpoints

GET /api/v1/admin/groups/{group_id}/quota

Get the quota configuration and current usage for a group.

Path parameters:

Parameter	Type	Description
group_id	UUID	The group’s UUID

Response 200 OK:

{
  "scope": "group",
  "id": "grp_01abc123-...",
  "limits": {
    "daily_token_limit": null,
    "monthly_token_limit": 10000000,
    "daily_request_limit": null,
    "monthly_request_limit": 20000,
    "daily_cost_limit_usd": null,
    "monthly_cost_limit_usd": 500.0
  },
  "usage": {
    "daily_tokens": 120400,
    "monthly_tokens": 4200000,
    "daily_requests": 480,
    "monthly_requests": 9800,
    "daily_cost_usd": 5.80,
    "monthly_cost_usd": 210.40
  }
}

Response 404 Not Found: Group not found or group has no quota configured.

---

PUT /api/v1/admin/groups/{group_id}/quota

Create or update the quota for a group.

Path parameters:

Parameter	Type	Description
group_id	UUID	The group’s UUID

Request body: QuotaConfig object (same as user quota).

Response 200 OK: The updated QuotaResponse object.

Response 404 Not Found: Group does not exist or does not belong to the admin’s tenant.

---

DELETE /api/v1/admin/groups/{group_id}/quota

Remove the quota for a group.

Path parameters:

Parameter	Type	Description
group_id	UUID	The group’s UUID

Response 204 No Content: Quota deleted.

Response 404 Not Found: Group not found or group has no quota configured.

---

Quota enforcement behavior

Limit precedence

When both a user quota and a group quota are configured for the same user, the stricter limit applies. For example, if a user has a monthly token limit of 2,000,000 and their group has a monthly token limit of 1,000,000, the effective limit is 1,000,000.

When a quota is exceeded

When a user’s usage reaches or exceeds a configured limit, subsequent requests return:

HTTP/1.1 429 Too Many Requests
Retry-After: <seconds until reset>

Response body:

{
  "error": "quota_exceeded",
  "limit_type": "monthly_token_limit",
  "limit_value": 2000000,
  "current_usage": 2001450,
  "reset_at": "2026-04-01T00:00:00Z"
}

Daily limits reset at UTC midnight. Monthly limits reset on the first day of each calendar month at UTC midnight.

Response headers

Quota status is included in response headers for every successful request:

Header	Description
X-RateLimit-Limit-Tokens-Day	Daily token limit
X-RateLimit-Remaining-Tokens-Day	Remaining tokens today
X-RateLimit-Limit-Tokens-Month	Monthly token limit
X-RateLimit-Remaining-Tokens-Month	Remaining tokens this month
X-RateLimit-Reset-Day	UTC timestamp when the daily window resets
X-RateLimit-Reset-Month	UTC timestamp when the monthly window resets

Headers for unset limits are omitted.

---

See also

• Budget enforcement — cost caps with warning thresholds and enforcement modes, managed at the outpost level
• Cost forecast API reference — projected monthly spend based on burn rate
• Groups and RBAC — group membership management
• Usage metering — raw usage data underlying quota tracking