Rate-limiting rules are deployed to the http_ratelimit phase; retrieve the phase entry-point ruleset ID for your zone with GET /zones/{zone_id}/rulesets/phases/http_ratelimit/entrypoint before creating rules.
Add a rate-limiting rule by POST to /zones/{zone_id}/rulesets/{entrypoint_ruleset_id}/rules with action set to block (or challenge, log), a filter expression in expression, and a ratelimit object containing requests_per_period, period (in seconds), and optionally characteristics[] to define the counting key.
The characteristics[] array determines what constitutes a unique counter: ip.src counts per source IP; http.request.headers["cf-connecting-ip"] counts per end-user IP when behind a proxy; you can combine multiple characteristics for compound keys.
Valid period values are a fixed set defined by Cloudflare (for example 10, 60, 300, 3600, 86400 seconds); choose the period that matches the expected legitimate usage pattern to minimise false positives.
Start with action=log and a conservative threshold to observe baseline request rates in Firewall Events before enforcing; use Security Analytics to identify the 99th-percentile rate for legitimate users.
Note that the legacy Rate Limiting API (cloudflare_rate_limit Terraform resource) was deprecated and removed in June 2025; all new and existing rate-limiting configuration must use the Rulesets API and cloudflare_ruleset Terraform resource.
Known gotchas
The counting period and mitigation period can differ only on Enterprise plans with Advanced Rate Limiting; on other plans, the mitigation period equals the counting period—requests are blocked for the same duration as the counting window.
Rate-limit counters are per data centre by default; distributed low-rate attacks that spread requests across many Cloudflare edge nodes may not trigger a single-node counter threshold—Enterprise plans offer globally distributed counting.
An expression that is too broad (for example matching all HTTP requests) can trigger rate limits on legitimate traffic bursts; always scope expressions to the specific path or resource being protected.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp