Overview - Unkey Docs

Rate limiting controls how many requests a user, IP, or any identifier can make in a given time window. Unkey provides distributed rate limiting that runs across the Unkey network without infrastructure for you to manage.

When to use rate limiting#

Prevent abuse

Stop bad actors from hammering your endpoints or scraping your data.

Protect costs

Limit expensive operations (AI calls, database queries) before they blow up your bill.

Fair usage

Ensure no single user monopolizes shared resources.

Compliance

Enforce contractual limits (e.g., 10,000 requests/month on a Basic plan).

How it works#

Choose an identifier

Decide what you're limiting: a user ID, API key, IP address, organization, or any string that uniquely identifies the requester.

Set the limit

Define how many requests are allowed and over what duration. Example: 100 requests per minute.

Check on each request

Call limiter.limit(identifier) and Unkey tells you whether to allow or reject the request.

Quick example#

import { Ratelimit } from "@unkey/ratelimit";const limiter = new Ratelimit({  rootKey: process.env.UNKEY_ROOT_KEY,  namespace: "my-app", // Group related limits together  limit: 10, // 10 requests...  duration: "60s", // ...per minute});export async function handler(req: Request) {  // Use any identifier: user ID, API key, IP, etc.  const identifier = req.headers.get("x-user-id") ?? getClientIP(req);  const { success, remaining, reset } = await limiter.limit(identifier);  if (!success) {    return new Response("Too many requests", {      status: 429,      headers: {        "X-RateLimit-Remaining": "0",        "X-RateLimit-Reset": reset.toString(),      },    });  }  // Request allowed, continue with your logic  return new Response(`Hello! ${remaining} requests remaining.`);}

Standalone vs Key-attached rate limits#

Unkey offers two ways to rate limit:

Approach	Best for	How it works
Standalone	Any endpoint, public or private	You call `limiter.limit()` with any identifier
Key-attached	API key authenticated endpoints	Rate limits are configured per-key and checked during `keys.verify()`

Standalone is what this section covers, it works anywhere, with or without API keys.

Key-attached rate limits are configured when you create API keys and are automatically enforced during verification.

Tip

You can use both. Standalone rate limits work well for public endpoints such as login and signup. Key-attached rate limits work well for authenticated API calls.

What makes Unkey rate limiting different?#

No infrastructure to manage

No Redis clusters, no Upstash accounts, no connection strings. Install the SDK and call the API.

Globally distributed

Requests are processed across Unkey's globally distributed infrastructure. Your rate limits are checked close to your users, not in a single region. Identifiers approaching their limit converge globally within seconds. See how rate limiting works.

Performance at scale

See real-time performance metrics at ratelimit.unkey.com, our global latency and throughput benchmarks updated live.

Timeout and fallback

Configure custom timeout and fallback behavior for resilience when network issues occur.

Per-identifier overrides

Give specific users higher limits without changing code. "User X gets 1000/min instead of 100/min."

Analytics built in

See which identifiers are hitting limits, when, and how often, in your Unkey dashboard.

Get started#

Create a root key

Go to Settings → Root Keys and create a new key with these permissions: - ratelimit.*.create_namespace - ratelimit.*.limit

Install the SDK

bash npm install @unkey/ratelimit

Add to your code

See the Next.js, Bun, Express, or Hono guides for complete examples.

Next steps#

Quickstart

Full walkthrough for your framework.

How it works

Understand global consistency and response behavior.

Overrides

Give specific users custom limits.

SDK Reference

All configuration options and methods.