Skip to main content
Create or update a custom rate limit for specific identifiers, bypassing the namespace default. Use this to create premium tiers with higher limits, apply stricter limits to specific users, or implement emergency throttling. Overrides take effect immediately and completely replace the default limit for matching identifiers. Important: Use wildcard patterns (e.g., premium_*) to match multiple identifiers. Set --limit=0 to completely block access for an identifier. Required permissions:
  • ratelimit.*.set_override (to set overrides in any namespace)
  • ratelimit.<namespace_id>.set_override (to set overrides in a specific namespace)
See the API reference for the full HTTP endpoint documentation.

​
Usage

unkey api ratelimit set-override [flags]

​
Flags

​
--namespace
string
required
The ID or name of the rate limit namespace. Must be 1-255 characters.
​
--identifier
string
required
Identifier of the entity receiving this custom rate limit. This can be a specific user ID, an IP address, an email domain, or any other string that identifies the target entity. Must be 1-255 characters.Wildcards (*) can be used to create pattern-matching rules that apply to multiple identifiers. For example:
  • premium_* matches all identifiers starting with premium_
  • *_admin matches all identifiers ending with _admin
  • *suspicious* matches any identifier containing suspicious
​
--limit
integer
required
The maximum number of requests allowed for this override. This defines the custom quota for the specified identifier(s) and entirely replaces the default limit for matching identifiers. Minimum value is 0.Special values:
  • Higher than default — for premium or trusted entities
  • Lower than default — for suspicious or abusive entities
  • 0 — to completely block access (useful for ban implementation)
​
--duration
integer
required
The duration in milliseconds for the rate limit window. This defines how long the rate limit counter accumulates before resetting to zero. Minimum value is 1000.Common values: 60000 (1 minute), 3600000 (1 hour), 86400000 (1 day). This can differ from the default duration for the namespace.

​
Global Flags

FlagTypeDescription
--root-keystringOverride root key ($UNKEY_ROOT_KEY)
--api-urlstringOverride API base URL (default: https://api.unkey.com)
--configstringPath to config file (default: ~/.unkey/config.toml)
--outputstringOutput format — use json for raw JSON

​
Examples

unkey api ratelimit set-override --namespace=api.requests --identifier=premium_user_123 --limit=1000 --duration=60000

​
Output

Default output shows the request ID with latency, followed by the created or updated override: 
req_2cGKbMxRyIzhCxo1Idjz8q (took 45ms)

{
  "overrideId": "ovr_1234567890abcdef"
}
With --output=json, the full response envelope is returned: 
{
  "meta": {
    "requestId": "req_2cGKbMxRyIzhCxo1Idjz8q"
  },
  "data": {
    "overrideId": "ovr_1234567890abcdef"
  }
}
Last modified on March 26, 2026