Set or remove a key quota for a calendar or custom period
PUT /v1/key-limits
PUT /v1/key-limits
Owners/admins manage all keys; developers with apiKey:update can manage their own keys' self-imposed quotas, but cannot override an administrator's policy. All periods and workspace policies apply cumulatively. Calls=0 blocks calls; budget=0 blocks paid calls. Both caps=null removes this period only. Custom [starts_at,ends_at) blocks calls outside its active range; optional reset_interval_seconds creates anchored subwindows. No reset job or monetary grant is involved.
Authorization
This operation requires a bearer credential. The description defines additional role, scope or first-party-session restrictions; an API key does not grant those permissions by itself.
Request body
| Property | Type | Required | Details |
|---|---|---|---|
key_id | string | yes | |
period | "daily" ∣ "weekly" ∣ "monthly" ∣ "custom" | yes | |
calls | integer ∣ null | yes | |
budget_microusd | integer ∣ null | yes | |
starts_at | string ∣ null | no | Custom active start, inclusive UTC ISO instant ending Z. |
ends_at | string ∣ null | no | Custom active end, exclusive UTC ISO instant ending Z. Calls remain blocked after this instant until the policy is removed. |
reset_interval_seconds | integer ∣ null | no | Custom bucket length anchored to starts_at; null means one fixed window. Calendar periods reject custom dates/intervals. |
Full schema: KeyLimitInput
{
"properties": {
"key_id": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"title": "Key Id"
},
"period": {
"type": "string",
"enum": [
"daily",
"weekly",
"monthly",
"custom"
],
"title": "Period"
},
"calls": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Calls"
},
"budget_microusd": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Budget Microusd"
},
"starts_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Starts At",
"description": "Custom active start, inclusive UTC ISO instant ending Z."
},
"ends_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Ends At",
"description": "Custom active end, exclusive UTC ISO instant ending Z. Calls remain blocked after this instant until the policy is removed."
},
"reset_interval_seconds": {
"anyOf": [
{
"type": "integer",
"maximum": 31622400,
"minimum": 60
},
{
"type": "null"
}
],
"title": "Reset Interval Seconds",
"description": "Custom bucket length anchored to starts_at; null means one fixed window. Calendar periods reject custom dates/intervals."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"key_id",
"period",
"calls",
"budget_microusd"
],
"title": "KeyLimitInput"
}Responses
| HTTP | Details | Type |
|---|---|---|
| 200 | Successful Response | application/json: KeyLimitList |
| 401 | Unauthorized | application/problem+json: ProblemDetails |
| 403 | Forbidden | application/problem+json: ProblemDetails |
| 404 | Not Found | application/problem+json: ProblemDetails |
| 422 | Unprocessable Entity | application/problem+json: ProblemDetails |
Response: KeyLimitList
| Property | Type | Required | Details |
|---|---|---|---|
items | KeyLimitStatus[] | yes | |
timezone | string | yes | |
currency | string | yes | |
microusd_per_usd | integer | yes |
Full schema
{
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/KeyLimitStatus"
},
"type": "array",
"title": "Items"
},
"timezone": {
"type": "string",
"const": "UTC",
"title": "Timezone"
},
"currency": {
"type": "string",
"const": "USD",
"title": "Currency"
},
"microusd_per_usd": {
"type": "integer",
"const": 1000000,
"title": "Microusd Per Usd"
}
},
"type": "object",
"required": [
"items",
"timezone",
"currency",
"microusd_per_usd"
],
"title": "KeyLimitList"
}This page is generated from OpenAPI; examples are schemas, not a fabricated successful response.