Quotas

Update a quota

Updates a quota's limit and/or mode. Other fields are immutable.

patch/v1/projects/{project_id}/quotas/{quota_id}

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/quotas/{quota_id}
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Path parameters

quota_idstring required

Quota ID

Request body

limitnumber

New limit

mode'enforce' | 'monitor'

New mode

on_unpriced'block' | 'allow'

New pricing posture. Only for metric cost_usd (400 on any other metric); see the create operation for what block and allow mean.

Example request

{
  "limit": 1000,
  "mode": "monitor",
  "on_unpriced": "allow"
}

Response

Quota updated successfully

idstring
project_idstring
scope'project' | 'api_key' | 'agent' | 'actor'
scope_refstring nullable

Public id of the api key / agent / actor the quota applies to. For api_key and agent scope, NULL means all entities of that scope type in the project. For actor scope, NULL means one budget per actor rather than a pooled total across all actors.

metric'requests' | 'tokens' | 'cost_usd' | 'storage_bytes'
window'rolling_1m' | 'rolling_1h' | 'rolling_24h' | 'calendar_month' | 'current'

The window the metric is aggregated over; current on storage_bytes, which caps a stored total and never resets.

limitnumber
mode'enforce' | 'monitor'
meter_type'llm_tokens' | 'compute_execution' | 'api_request' | 'storage' | 'tool_execution' | 'null' nullable

The meter a cost_usd cap answers for. Null is every priced meter, which is what a quota created without one carries.

on_unpriced'block' | 'allow' | 'null' nullable

Pricing posture of a cost_usd quota over an unpriced blackout — block refuses generations, allow lets them through (the quota_unpriced exception is filed either way, and for a partly priced window, which no posture refuses). Null for metrics with no pricing dependency.

created_atstring date-time
updated_atstring date-time

Example response

{
  "id": "quota_V1StGXR8Z5jdHi6B",
  "current_usage": {
    "window_key": "2026-07-07T12:31Z",
    "count": 42
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.