Rate limits

Manage rate limiting rules to protect against DDoS and abusive traffic (deprecated)

The Rate Limiting API is deprecated in favor of using the Ruleset Engine. See the deprecation notice for full details.

The Rate Limits API allows you to create and manage rate limiting rules that protect your website against denial-of-service attacks, brute-force login attempts, and other types of abusive behavior.

Create a rate limit

Creates a new rate limit for a zone.

const rateLimit = await client.rateLimits.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  threshold: 60,
  period: 60,
  action: {
    mode: 'challenge',
  },
  match: {
    request: {
      url: '*.example.com/path*',
    },
  },
});

zone_id · string · required

The zone identifier

threshold · number · required

The threshold that triggers the rate limit mitigation. Configure this value along with the period property to establish a threshold per period.

period · number · required

The time in seconds to count matching traffic. If the count exceeds the threshold within this period, Cloudflare performs the configured action.

action · object · required

The action to perform when the threshold is exceeded.

mode · string · required

The action to perform: simulate, ban, challenge, js_challenge, or managed_challenge

timeout · number

The time in seconds during which Cloudflare will perform the mitigation action. Must be greater than or equal to the period.

response · object

Custom response to return when threshold is exceeded.

content_type · string

Content type: text/plain, text/xml, or application/json

body · string

The response body to return

match · object · required

Determines which traffic the rate limit counts toward the threshold.

request · object

Request matching criteria.

url · string

URL pattern to match (e.g., example.org/path*). Use * for wildcards.

methods · array

HTTP methods to match: GET, POST, PUT, DELETE, PATCH, HEAD, or _ALL_

schemes · array

HTTP schemes to match: HTTP, HTTPS, or _ALL_

response · object

Response matching criteria.

origin_traffic · boolean

When true, only uncached traffic served from origin servers counts toward rate limiting.

headers · array

Array of header matching rules.

name · string

The header name to match

op · string

Operator: eq (equal) or ne (not equal)

value · string

The header value to match

description · string

An informative summary of the rate limit rule.

disabled · boolean

When true, the rate limit is currently disabled.

bypass · array

Criteria specifying when the rate limit should be bypassed.

name · string

Set to url for URL-based bypass

value · string

The URL to bypass

id · string

The unique identifier of the rate limit

action · object

The configured action

threshold · number

The request threshold

period · number

The time period in seconds

match · object

The traffic matching criteria

disabled · boolean

Whether the rate limit is disabled

List rate limits

Fetches all rate limits for a zone.

for await (const rateLimit of client.rateLimits.list({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
  console.log(rateLimit.id);
}

zone_id · string · required

The zone identifier

page · number

Page number of paginated results

per_page · number

Number of items per page

Get a rate limit

Fetches details of a single rate limit.

const rateLimit = await client.rateLimits.get(
  'rate_limit_id',
  { zone_id: '023e105f4ecef8ad9ca31a8372d0c353' },
);

rateLimitId · string · required

The rate limit identifier

zone_id · string · required

The zone identifier

Update a rate limit

Updates an existing rate limit.

const rateLimit = await client.rateLimits.edit(
  'rate_limit_id',
  {
    zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
    threshold: 100,
    period: 60,
    action: {
      mode: 'ban',
      timeout: 300,
    },
    match: {
      request: {
        url: '*.example.com/api/*',
      },
    },
  },
);

rateLimitId · string · required

The rate limit identifier

zone_id · string · required

The zone identifier

Delete a rate limit

Deletes an existing rate limit.

await client.rateLimits.delete(
  'rate_limit_id',
  { zone_id: '023e105f4ecef8ad9ca31a8372d0c353' },
);

rateLimitId · string · required

The rate limit identifier

zone_id · string · required

The zone identifier

Example: Protect login endpoint

const rateLimit = await client.rateLimits.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  description: 'Protect login from brute force',
  threshold: 5,
  period: 60,
  action: {
    mode: 'challenge',
    timeout: 600,
  },
  match: {
    request: {
      url: 'example.com/login',
      methods: ['POST'],
    },
  },
});

Example: API rate limiting with custom response

const rateLimit = await client.rateLimits.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  description: 'API rate limit',
  threshold: 1000,
  period: 60,
  action: {
    mode: 'simulate',
    response: {
      content_type: 'application/json',
      body: JSON.stringify({
        error: 'Rate limit exceeded',
        retry_after: 60,
      }),
    },
  },
  match: {
    request: {
      url: 'api.example.com/*',
    },
  },
});

Migration to Ruleset Engine

For new implementations, use the Ruleset Engine instead of the deprecated Rate Limiting API. The Ruleset Engine provides more flexible and powerful rate limiting capabilities through custom rules.