To deploy rate limiting rules at the account level, you must create a rate limiting ruleset with one or more rules. Use theRulesets API to create and deploy rate limiting rulesets via API.

Each rate limiting rule contains aratelimit object with the rate limiting configuration. Refer toRate limiting parameters for more information on this object and its parameters.

If you are using Terraform, refer toRate limiting rules configuration using Terraform.

To deploy a rate limiting ruleset in your account, follow these general steps:

1. Create a rate limiting ruleset (that is, a custom ruleset in thehttp_ratelimit phase) with one or more rate limiting rules.
2. Deploy the ruleset to theentry point ruleset of thehttp_ratelimit phase at the account level.

The following example creates a rate limiting ruleset with a single rate limiting rule in therules array.

curl"https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rulesets"\
--requestPOST\
--header"Authorization: Bearer$CLOUDFLARE_API_TOKEN"\
--json'{
"description": "",
"kind": "custom",
"name": "My rate limiting ruleset",
"rules": [
{
"description": "Rate limit API requests",
"expression": "(starts_with(http.request.uri.path, \"/my-api/\"))",
"ratelimit": {
"characteristics": [
"ip.src",
"cf.colo.id"
],
"requests_to_origin": false,
"requests_per_period": 30,
"period": 60,
"mitigation_timeout": 120
},
"action": "block",
"action_parameters": {
"response": {
"status_code": 429,
"content_type": "application/json",
"content": "{ \"error\": \"Your API requests have been rate limited. Wait a couple of minutes and try again.\" }"
}
},
"enabled": true
}
],
"phase": "http_ratelimit"
}'

The available characteristics depend on your Cloudflare plan and product subscriptions. Refer toAvailability for more information.

Save the ruleset ID in the response for the next step.

To deploy the rate limiting ruleset, add a rule with"action": "execute" to thehttp_ratelimit phase entry point ruleset at the account level.

1. Invoke theGet an account entry point ruleset operation to obtain the definition of the entry point ruleset for thehttp_ratelimit phase. You will need theaccount ID for this task.

   Required API token permissions

   At least one of the followingtoken permissions is required:

   • Account WAF Write
   • Account WAF Read
   • Account Rulesets Read
   • Account Rulesets Write

   curl"https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rulesets/phases/http_ratelimit/entrypoint"\
   --requestGET\
   --header"Authorization: Bearer$CLOUDFLARE_API_TOKEN"

   {
   "result":{
   "description":"Account-level phase entry point",
   "id":"<RULESET_ID>",
   "kind":"root",
   "last_updated":"2024-03-16T15:40:08.202335Z",
   "name":"root",
   "phase":"http_ratelimit",
   "rules":[
   // ...
   ],
   "source":"firewall_managed",
   "version":"10"
   },
   "success":true,
   "errors":[],
   "messages":[]
   }

2. If the entry point ruleset already exists (that is, if you received a200 OK status code and the ruleset definition), take note of the ruleset ID in the response. Then, invoke theCreate an account ruleset rule operation to add anexecute rule to the existing ruleset deploying the rate limiting ruleset. By default, the rule will be added at the end of the list of rules already in the ruleset.

   The following request creates a rule that executes the rate limiting ruleset with ID<RATE_LIMITING_RULESET_ID> for all Enterprise zones in the account:

   Required API token permissions

   At least one of the followingtoken permissions is required:

   • Account WAF Write
   • Account Rulesets Write

   curl"https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rulesets/$RULESET_ID/rules"\
   --requestPOST\
   --header"Authorization: Bearer$CLOUDFLARE_API_TOKEN"\
   --json'{
   "description": "Execute rate limiting ruleset",
   "expression": "(cf.zone.plan eq \"ENT\")",
   "action": "execute",
   "action_parameters": {
   "id": "<RATE_LIMITING_RULESET_ID>"
   },
   "enabled": true
   }'

   You can only apply rate limiting rulesets to incoming traffic of zones on an Enterprise plan. To enforce this requirement, you must includecf.zone.plan eq "ENT" in the expression of theexecute rule deploying the rate limiting ruleset.

3. If the entry point ruleset does not exist (that is, if you received a404 Not Found status code in step 1), create it using theCreate an account ruleset operation. Include a single rule in therules array that executes the rate limiting ruleset for all incoming requests of Enterprise zones in your account.

   Required API token permissions

   At least one of the followingtoken permissions is required:

   • Account WAF Write
   • Account Rulesets Write

   curl"https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rulesets"\
   --requestPOST\
   --header"Authorization: Bearer$CLOUDFLARE_API_TOKEN"\
   --json'{
   "description": "",
   "kind": "root",
   "name": "Account-level phase entry point",
   "rules": [
   {
   "action": "execute",
   "expression": "(cf.zone.plan eq \"ENT\")",
   "action_parameters": {
   "id": "<RATE_LIMITING_RULESET_ID>"
   }
   }
   ],
   "phase": "http_ratelimit"
   }'

For examples of rate limiting rule definitions for the API, refer to thezone-level API documentation.

Use the different operations in theRulesets API to work with the ruleset you just created and deployed. The following table has a list of common tasks for working with rate limiting rulesets at the account level:

For more information on the different rate limiting parameters you can configure in your rate limiting rules, refer toRate limiting parameters.