Skip to main content
POST
/
v2
/
ratelimit.setOverride
Python (SDK)
from unkey.py import Unkey


with Unkey(
    root_key="<YOUR_BEARER_TOKEN_HERE>",
) as unkey:

    res = unkey.ratelimit.set_override(namespace="api.requests", duration=60000, identifier="premium_user_123", limit=1000)

    # Handle response
    print(res)
{
  "meta": {
    "requestId": "req_123"
  },
  "data": {
    "overrideId": "<string>"
  }
}

Authorizations

​
Authorization
string
header
required

Unkey uses API keys (root keys) for authentication. These keys authorize access to management operations in the API. To authenticate, include your root key in the Authorization header of each request:

Authorization: Bearer unkey_123

Root keys have specific permissions attached to them, controlling what operations they can perform. Key permissions follow a hierarchical structure with patterns like resource.resource_id.action (e.g., apis.*.create_key, apis.*.read_api). Security best practices:

  • Keep root keys secure and never expose them in client-side code
  • Use different root keys for different environments
  • Rotate keys periodically, especially after team member departures
  • Create keys with minimal necessary permissions following least privilege principle
  • Monitor key usage with audit logs.

Body

application/json

Sets a new or overwrites an existing rate limit override. Overrides allow you to apply special rate limit rules to specific identifiers, providing custom limits that differ from the default.

Overrides are useful for:

  • Granting higher limits to premium users or trusted partners
  • Implementing stricter limits for suspicious or abusive users
  • Creating tiered access levels with different quotas
  • Implementing temporary rate limit adjustments
  • Prioritizing important clients with higher limits
​
namespace
string
required

The ID or name of the rate limit namespace.

Required string length: 1 - 255
​
duration
integer<int64>
required

The duration in milliseconds for the rate limit window. This defines how long the rate limit counter accumulates before resetting to zero.

Considerations:

  • This can differ from the default duration for the namespace
  • Longer durations create stricter limits that take longer to reset
  • Shorter durations allow more frequent bursts of activity
  • Common values: 60000 (1 minute), 3600000 (1 hour), 86400000 (1 day)
Required range: x >= 1000
​
identifier
string
required

Identifier of the entity receiving this custom rate limit. This can be:

  • A specific user ID for individual custom limits
  • An IP address for location-based rules
  • An email domain for organization-wide policies
  • Any other string that identifies the target entity

Wildcards (*) can be used to create pattern-matching rules that apply to multiple identifiers. For example:

  • 'premium_*' would match all identifiers starting with 'premium_'
  • '*_admin' would match all identifiers ending with '_admin'
  • 'suspicious' would match any identifier containing 'suspicious'

More detailed information on wildcard pattern rules is available at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules

Required string length: 1 - 255
​
limit
integer<int64>
required

The maximum number of requests allowed for this override. This defines the custom quota for the specified identifier(s).

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)

This limit entirely replaces the default limit for matching identifiers.

Required range: x >= 0

Response

Override successfully created or updated and is now active.

​
meta
object
required

Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The requestId is particularly important when troubleshooting issues with the Unkey support team.

​
data
object
required