Skip to main content
Unkey’s ratelimiting system controls the number of requests a key can make within a given timeframe. This prevents abuse, protects your API from being overwhelmed, and enables usage-based billing models.

​
Multi-Ratelimit System

Unkey supports multiple named ratelimits per key, providing fine-grained control over different aspects of your API usage. You can define separate limits for different operations, time windows, and use cases within a single key. The system offers two types of ratelimits: auto-apply ratelimits that check automatically during verification, and manual ratelimits that require explicit specification in requests.

​
Auto-Apply vs Manual Ratelimits

Auto-apply ratelimits (autoApply: true) are checked automatically during every key verification without needing explicit specification. These work well for general usage limits that should always be enforced. 
# Create a key with auto-apply ratelimit
curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "api_123",
    "ratelimits": [
      {
        "name": "general-requests",
        "limit": 100,
        "duration": 60000,
        "autoApply": true
      }
    ]
  }'

# Verify key - auto-apply ratelimits are checked automatically
curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "your_api_key_here"
  }'
Manual ratelimits (autoApply: false) must be explicitly specified in verification requests. Use these for operation-specific limits that only apply to certain endpoints. 
# Create a key with manual ratelimit
curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "api_123",
    "ratelimits": [
      {
        "name": "expensive-operations",
        "limit": 5,
        "duration": 60000
      }
    ]
  }'

# Verify key - override cost explicitly
curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "your_api_key_here",
    "ratelimits": [
      {
        "name": "expensive-operations",
        "cost": 2
      }
    ]
  }'

​
Configuration

Configure ratelimits on a per-key or per-identity basis through the dashboard or API. Each ratelimit requires a unique name, limit count, and duration in milliseconds. 
curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "api_123",
    "ratelimits": [
      {
        "name": "requests",
        "limit": 100,
        "duration": 60000,
        "autoApply": true
      },
      {
        "name": "daily-quota",
        "limit": 1000,
        "duration": 86400000,
        "autoApply": true
      }
    ]
  }'
You can apply different costs to operations by specifying a cost parameter during verification. This allows resource-intensive operations to consume more of the rate limit than simple operations.

​
Identity-Level Ratelimits

Configure ratelimits at the identity level to share limits across multiple keys. Identity ratelimits work alongside key-level ratelimits, with key-level settings taking precedence for naming conflicts. 
curl -X POST https://api.unkey.com/v2/identities.createIdentity \
  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_123",
    "ratelimits": [
      {
        "name": "user-requests",
        "limit": 1000,
        "duration": 3600000
      }
    ]
  }'
This approach works well for user-based quotas where multiple API keys should share the same usage limits.