Resetting key limits
Daily, weekly, calendar-month and custom call/spending periods.
Set a predictable boundary
Use the key-creation or key-settings interface in API keys. A policy can cap call count, prepaid spending, or both. All matching workspace and key policies are cumulative. Bonus calls still count toward a call cap; a money cap measures actual prepaid money, not a nominal value of included or bonus usage.
| Period | Boundary |
|---|---|
daily | 00:00 UTC each day |
weekly | Monday 00:00 UTC |
monthly | Start of the actual calendar month, UTC |
custom | Explicit half-open interval [starts_at, ends_at) |
Custom periods can optionally repeat bounded buckets anchored at starts_at; the last bucket is clipped to ends_at. Outside the configured custom interval the key is blocked by that policy. This is not an invitation to spend before the interval starts.
API contract
First-party authenticated sessions can use GET /v1/key-limits?key_id=... and PUT /v1/key-limits:
{"key_id":"YOUR_KEY_ID","period":"weekly","calls":1000,"budget_microusd":null}budget_microusd is integer micro-USD: 1000000 means USD 1. Both calls and budget_microusd can be null; both null remove only the selected period's policy. Zero is a real cap and is not treated as missing.
A custom policy also uses UTC ISO timestamps starts_at, ends_at and optional reset_interval_seconds from 60 to 31622400. A repeat duration is elapsed time anchored to the explicit start, not a calendar-month shorthand.
The response gives window_start, window_end, active, resets_at, usage/remaining calls and prepaid budget, update attribution and can_manage. Inspect the actual reset timestamp rather than calculating a month as 30 days.
Reservations and access control
Admission reserves usage atomically. Reserved/successful calls count, errors release the reservation, and free guide/report/status operations do not spend the policy's metered allowance. Windows are calculated from history; a cron task does not erase counters to reset them.
Owners/admins manage workspace keys. Developers can impose limits on their own key but cannot override an administrator's restriction. Reached limits return key_limit_reached; retryable and Retry-After are provided only when an upcoming automatic reset can actually help. A zero cap or expired fixed interval needs a policy change instead of repeated calls.
GET /v1/key-limits without a key filter returns at most 100 policies. Filter by key_id to inspect one key precisely. PUT returns policies for the key you updated. A fixed custom policy blocks after ends_at; reaching its end does not silently remove the cap.