Overview

Protect any API endpoint from abuse with Unkey’s distributed rate limiting. No infrastructure required, just a single API call.

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

1. Choose an identifier

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

2. Set the limit

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

3. Check on each request

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

Quick example

TypeScript

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.

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

1. Create a root key

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

2. Install the SDK

   bash npm install @unkey/ratelimit
3. 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.