Create a rate limiting rule via API

Use the Rulesets API to create a rate limiting rule via API.

A rate limiting rule is similar to a regular rule handled by the Ruleset Engine, but contains an additional ratelimit object with the rate limiting configuration. Refer to Rate limiting parameters for more information on this field and its parameters.

You must deploy rate limiting rules to the http_ratelimit phase entry point ruleset.

Rate limiting rules must appear at the end of the rules list.

Create a rate limiting rule

To create a rate limiting rule for a zone, add a rule with a ratelimit object to the http_ratelimit phase entry point ruleset.

1. Invoke the Get a zone entry point ruleset operation to obtain the definition of the entry point ruleset for the http_ratelimit phase. You will need the zone ID for this task.

2. If the entry point ruleset already exists (that is, if you received a 200 OK status code and the ruleset definition), take note of the ruleset ID in the response. Then, invoke the Create a zone ruleset rule operation to add a rate limiting rule to the existing ruleset. Refer to the examples below for details.

3. If the entry point ruleset does not exist (that is, if you received a 404 Not Found status code in step 1), create it using the Create a zone ruleset operation. Include your rate limiting rule in the rules array. Refer to Create ruleset for an example.

Example A - Rate limiting based on request properties

This example adds a rate limiting rule to the http_ratelimit phase entry point ruleset for the zone with ID {zone_id}. The phase entry point ruleset already exists, with ID {ruleset_id}.

curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id}/rules \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "description": "My rate limiting rule",
  "expression": "(http.request.uri.path matches \"^/api/\")",
  "action": "block",
  "ratelimit": {
    "characteristics": [
      "cf.colo.id",
      "ip.src",
      "http.request.headers[\"x-api-key\"]"
    ],
    "period": 60,
    "requests_per_period": 100,
    "mitigation_timeout": 600
  }
}'

To define a specific position for the new rule, include a position object in the request body according to the guidelines in Change the order of a rule in a ruleset.

For instructions on creating an entry point ruleset and defining its rules using a single API call, refer to Add rules to phase entry point rulesets.

Example B - Rate limiting with a custom response

This example adds a rate limiting rule to the http_ratelimit phase entry point ruleset for the zone with ID {zone_id}. The phase entry point ruleset already exists, with ID {ruleset_id}.

The new rule defines a custom response for requests blocked due to rate limiting.

curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id}/rules \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "description": "My rate limiting rule",
  "expression": "(http.request.uri.path matches \"^/api/\")",
  "action": "block",
  "action_parameters": {
    "response": {
      "status_code": 403,
      "content": "You have been rate limited.",
      "content_type": "text/plain"
    }
  },
  "ratelimit": {
    "characteristics": [
      "cf.colo.id",
      "ip.src",
      "http.request.headers[\"x-api-key\"]"
    ],
    "period": 60,
    "requests_per_period": 100,
    "mitigation_timeout": 600
  }
}'

To define a specific position for the new rule, include a position object in the request body according to the guidelines in Change the order of a rule in a ruleset.

For instructions on creating an entry point ruleset and defining its rules using a single API call, refer to Add rules to phase entry point rulesets.

Example C - Rate limiting ignoring cached assets

This example adds a rate limiting rule to the http_ratelimit phase entry point ruleset for the zone with ID {zone_id}. The phase entry point ruleset already exists, with ID {ruleset_id}.

The new rule does not consider requests for cached assets when calculating the rate.

curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id}/rules \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "description": "My rate limiting rule",
  "expression": "(http.request.uri.path matches \"^/api/\")",
  "action": "block",
  "ratelimit": {
    "characteristics": [
      "cf.colo.id",
      "ip.src",
      "http.request.headers[\"x-api-key\"]"
    ],
    "period": 60,
    "requests_per_period": 100,
    "mitigation_timeout": 600,
    "requests_to_origin": true
  }
}'

To define a specific position for the new rule, include a position object in the request body according to the guidelines in Change the order of a rule in a ruleset.

For instructions on creating an entry point ruleset and defining its rules using a single API call, refer to Add rules to phase entry point rulesets.

Example D - Complexity-based rate limiting rule

Note

Complexity-based rate limiting is available in beta and can only be configured via API.

This example adds a rate limiting rule to the http_ratelimit phase entry point ruleset for the zone with ID {zone_id}. The phase entry point ruleset already exists, with ID {ruleset_id}.

The new rule is a complexity-based rate limiting rule that takes the my-score HTTP response header into account to calculate a total complexity score for the client. The counter with the total score is updated when there is a match for the rate limiting rule’s counting expression (in this case, the same as the rule expression). When this total score becomes larger than 400 during a 60-second period, any later client requests will be blocked for a period of 600 seconds (10 minutes).

curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id}/rules \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "description": "My complexity-based rate limiting rule",
  "expression": "http.request.uri.path matches \"^/graphql/\"",
  "action": "block",
  "ratelimit": {
    "characteristics": [
      "cf.colo.id",
      "http.request.headers[\"x-api-key\"]"
    ],
    "period": 60,
    "score_per_period": 400,
    "score_response_header_name": "my-score",
    "mitigation_timeout": 600,
    "counting_expression": ""
  }
}'

To define a specific position for the new rule, include a position object in the request body according to the guidelines in Change the order of a rule in a ruleset.

For instructions on creating an entry point ruleset and defining its rules using a single API call, refer to Add rules to phase entry point rulesets.

---

Next steps

Use the different operations in the Rulesets API to work with the rule you just created. The following table has a list of common tasks for working with rate limiting rules at the zone level:

Task	Procedure
List all rules in ruleset	Use the Get a zone entry point ruleset operation with the http_ratelimit phase name to obtain the list of configured rate limiting rules and their IDs. For more information, refer to View a specific ruleset.
Update a rule	Use the Update a zone ruleset rule operation. You will need to provide the ruleset ID and the rule ID. To obtain these IDs, you can use the Get a zone entry point ruleset operation with the http_ratelimit phase name. For more information, refer to Update a rule in a ruleset.
Delete a rule	Use the Delete a zone ruleset rule operation. You will need to provide the ruleset ID and the rule ID. To obtain these IDs, you can use the Get a zone entry point ruleset operation with the http_ratelimit phase name. For more information, refer to Delete a rule in a ruleset.

These operations are covered in the Ruleset Engine documentation. The Ruleset Engine powers different Cloudflare products, including rate limiting rules.