Skip to main content
Unkey Docs

set-override

Create or update a custom rate limit override for a specific identifier using the Unkey CLI. Bypass namespace defaults for individual users.
2 min read

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)
Note

See the API reference for the full HTTP endpoint documentation.

Usage#

Flags#

--namespacestringrequired#

The ID or name of the rate limit namespace. Must be 1-512 characters.

--identifierstringrequired#

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-512 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
--limitintegerrequired#

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)
--durationintegerrequired#

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
--bodystringSend this JSON string as the request body. You cannot combine it with request-building flags.

Examples#

Output#

Default output shows the request ID, followed by the created or updated override:

With --output=json, the full response envelope is returned:

multi-limitget-override