Skip to main content
Check and enforce multiple rate limits in a single request for any identifiers (user IDs, IP addresses, API clients, etc.). Use this to efficiently check multiple rate limits at once. Each rate limit check is independent and returns its own result with a top-level passed indicator showing if all checks succeeded. Response Codes: Rate limit checks return HTTP 200 regardless of whether limits are exceeded — check the passed field to see if all limits passed, or the success field in each individual result. A 429 may be returned if the workspace exceeds its API rate limit. Other 4xx responses indicate auth, namespace existence/deletion, or validation errors (e.g., 410 Gone for deleted namespaces). 5xx responses indicate server errors. Required permissions:
  • ratelimit.*.limit (to check limits in any namespace)
  • ratelimit.<namespace_id>.limit (to check limits in all specific namespaces being checked)
See the API reference for the full HTTP endpoint documentation.

​
Usage

unkey api ratelimit multi-limit [flags]

​
Flags

​
--limits-json
string
required
JSON array of rate limit check objects. Each object defines an independent rate limit check to perform.

​
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 multi-limit \
  --limits-json='[{"namespace":"api.requests","identifier":"user_abc123","limit":100,"duration":60000},{"namespace":"auth.login","identifier":"user_abc123","limit":5,"duration":60000}]'

​
Output

Default output shows the request ID with latency, followed by the multi-limit result: 
req_01H9TQPP77V5E48E9SH0BG0ZQX (took 38ms)

{
  "passed": true,
  "limits": [
    {
      "namespace": "api.requests",
      "identifier": "user_abc123",
      "limit": 100,
      "remaining": 99,
      "reset": 1714582980000,
      "passed": true
    },
    {
      "namespace": "auth.login",
      "identifier": "user_abc123",
      "limit": 5,
      "remaining": 4,
      "reset": 1714582980000,
      "passed": true
    }
  ]
}
With --output=json, the full response envelope is returned: 
{
  "meta": {
    "requestId": "req_01H9TQPP77V5E48E9SH0BG0ZQX"
  },
  "data": {
    "passed": true,
    "limits": [
      {
        "namespace": "api.requests",
        "identifier": "user_abc123",
        "limit": 100,
        "remaining": 99,
        "reset": 1714582980000,
        "passed": true
      },
      {
        "namespace": "auth.login",
        "identifier": "user_abc123",
        "limit": 5,
        "remaining": 4,
        "reset": 1714582980000,
        "passed": true
      }
    ]
  }
}
Last modified on March 26, 2026