--- name: azion-rate-limit-the-addresses-in-a-list description: >- Create a network list and a firewall rule that holds each client in it to a request rate, in Azion Console, the Azion CLI, or the API. --- # Rate-limit the addresses in a list You can hold the clients in a [network list](/en/documentation/platform/firewall/network-shield/network-lists/) to a request rate from Azion Console, the [Azion CLI](/en/documentation/devtools/cli/), or the API. The rule sets no limit on any client outside the list. One [firewall](/en/documentation/platform/firewall/) rule pairs the *Network* criterion, which reads the list, with the *Set Rate Limit* behavior. Use it when a set of addresses may keep using your application, but only at a pace the application can serve. To refuse those addresses instead of slowing them, refer to [Block requests by IP, ASN, or country](/en/documentation/guides/application-security/bots-and-network/blocklists-ip-addresses-edge/). --- Select the interface for this guide. Its prerequisites and every task on this page switch to that interface. ## Prerequisites - A [workload](/en/documentation/platform/workloads/) bound to a firewall. The rate-limit rule goes on that firewall. - [Network Shield](/en/documentation/platform/firewall/#network-shield) on for that firewall, because the *Network* criterion comes from it. It starts on in every firewall and stays on until someone turns it off. **Console** - An account that can sign in to [Azion Console](https://console.azion.com/). **CLI** - The Azion CLI, installed and authenticated with a [personal token](/en/documentation/fundamentals/personal-tokens/). - The ID of the firewall that your workload is bound to. **API** - A [personal token](/en/documentation/fundamentals/personal-tokens/). Each request in this guide sends it in place of `[TOKEN VALUE]`. - The ID of the firewall that your workload is bound to. --- ## Create the list of addresses to limit The addresses to limit go in a list of the `ip_cidr` type, shown as *IP/CIDR* in Azion Console. Its items are addresses and ranges, such as `203.0.113.0/24` and `198.51.100.7`. The rule stores the ID of the list rather than its items. An address you add to the list or remove from it therefore changes which clients are limited, and the rule needs no edit. For every field and type a list accepts, refer to [Network list fields](/en/documentation/platform/firewall/network-shield/network-lists/#network-list-fields) and [List types](/en/documentation/platform/firewall/network-shield/network-lists/#list-types). **Console** To create the list in Azion Console: 1. **Open the Network Lists page** Access [Azion Console](https://console.azion.com/) > **Edge Libraries** > **Network Lists**. 2. **Select Network List** 3. **Name the list** In the **General** section, enter a **Name**. For example: `Rate-limited addresses`. 4. **Select the IP/CIDR type** In the **Network List Settings** section, select *IP/CIDR*. When the form opens, *ASN* is the selected type. 5. **Enter the addresses to limit** In the **List** field, enter each address or range on its own line. For example: `203.0.113.0/24` and `198.51.100.7`. 6. **Save the list** Select **Save**. Azion Console confirms with the message `Your network list has been created`. The list `Rate-limited addresses` then appears in **Network Lists**. **CLI** To create the list with the Azion CLI, write it to a file named `network-list.json`: ```json {"name":"Rate-limited addresses","type":"ip_cidr","items":["203.0.113.0/24","198.51.100.7"],"active":true} ``` Create the list from that file: ```bash azion create network-list --file network-list.json ``` The output carries the ID of the list: ```text Created Network List with ID ``` Keep that ID, because the rule refers to `Rate-limited addresses` by it. **API** To create the list with the API, send it in a `POST` request to `/v4/workspace/network_lists`. Put your personal token in place of `[TOKEN VALUE]`: ```bash curl -X POST https://api.azion.com/v4/workspace/network_lists \ -H "Authorization: Token [TOKEN VALUE]" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"name":"Rate-limited addresses","type":"ip_cidr","items":["203.0.113.0/24","198.51.100.7"]}' ``` The API answers `201`. Its `state` of `executed` says the list was stored at once: ```json { "state": "executed", "data": { "id": , "name": "Rate-limited addresses", "type": "ip_cidr", "items": ["203.0.113.0/24", "198.51.100.7"], "last_editor": "", "last_modified": "2026-01-01T12:00:00.000000Z", "created_at": "2026-01-01T12:00:00.000000Z", "active": true, "version_id": null, "version_state": null, "is_versioned": false, "version": null } } ``` Keep the value of `data.id`. The rule takes it as the argument of its criterion. --- ## Create the rule that rate-limits the list The rule joins the *Network* criterion, with its *matches* operator, to the *Set Rate Limit* behavior. Only a client in the list makes that criterion true, so only those clients are limited. A request from any other client leaves the criterion false: the rule runs nothing, and the firewall goes on to its next rule. The behavior in this guide allows each client IP address an average of `10` requests per second, with a burst of `10`. *Set Rate Limit* is a behavior of Firewall itself, and Network Shield adds only the criterion. For what each field of the behavior counts, refer to [Set Rate Limit](/en/documentation/platform/firewall/rules-engine/#set-rate-limit). **Console** To create the rule that rate-limits the list in Azion Console: 1. **Open the firewall bound to your workload** Access [Azion Console](https://console.azion.com/) > **Secure** > **Firewalls**, and select the firewall. 2. **Select the Rules Engine tab** 3. **Select Rule** Azion Console opens the **Create Rule** drawer. 4. **Name the rule** In the **General** section, enter a **Name**. For example: `Rate-limit listed addresses`. 5. **Set the Network criterion** In the **Criteria** section, select the *Network* variable and the *matches* operator. A variable that reads *Network - required Network Shield* means that Network Shield is off on this firewall. Turn it on in **Main Settings** > **Modules** and save the firewall, and the variable becomes selectable. 6. **Select your list** In the **Select a Network** dropdown, select the list of addresses to limit. For example: `Rate-limited addresses`. 7. **Add the Set Rate Limit behavior** In the **Behaviors** section, select *Set Rate Limit*. **Rate Limit Type** starts at *Req/s* and **Limit By** at *Client IP address*. Keep both values. 8. **Set the average rate** In **Average Rate Limit**, enter `10`. 9. **Set the burst size** In **Maximum Burst Size**, enter `10`. 10. **Save the rule** Select **Save**. Azion Console confirms with the message `Rule successfully created`. In the **Rules Engine** tab, the **Status** column of the rule reads *Active*. **CLI** `azion create firewall-rule` takes the rule only as a JSON file, through `--file`, next to `--firewall-id`. To create it with the Azion CLI, write it to a file named `rule.json`. Put the ID of your list in place of ``, as a number with no quotes: ```json { "name": "Rate-limit listed addresses", "active": true, "criteria": [ [ { "variable": "${network}", "conditional": "if", "operator": "is_in_list", "argument": } ] ], "behaviors": [ { "type": "set_rate_limit", "attributes": { "type": "second", "limit_by": "client_ip", "average_rate_limit": 10, "maximum_burst_size": 10 } } ] } ``` Create the rule from that file on the firewall bound to your workload. Put the ID of that firewall in place of ``: ```bash azion create firewall-rule --firewall-id --file rule.json ``` The output carries the ID of the rule: ```text Created Firewall Rule with ID ``` The rule is active on the firewall, and it limits the clients in `Rate-limited addresses` once it reaches traffic. **API** To create the rate-limit rule with the API, send a `POST` request to `/v4/workspace/firewalls/{firewall_id}/request_rules`. Write the ID of the firewall bound to your workload in place of ``. Put `data.id` from the list response in place of ``, as a number with no quotes: ```bash curl -X POST https://api.azion.com/v4/workspace/firewalls//request_rules \ -H "Authorization: Token [TOKEN VALUE]" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "name": "Rate-limit listed addresses", "active": true, "criteria": [ [ { "variable": "${network}", "conditional": "if", "operator": "is_in_list", "argument": } ] ], "behaviors": [ { "type": "set_rate_limit", "attributes": { "type": "second", "limit_by": "client_ip", "average_rate_limit": 10, "maximum_burst_size": 10 } } ] }' ``` The API answers `202`, with a `state` of `pending` and the `id` of the rule it created. > **Note** > > In the JSON body of the CLI and the API, `${network}` names the *Network* criterion and `is_in_list` its *matches* operator. The `attributes` of `set_rate_limit` set `type` to `second`, which is *Req/s* in Azion Console, and `limit_by` to `client_ip`, which is *Client IP address*. Both `average_rate_limit` and `maximum_burst_size` are `10`. A list ID sent as a string, such as `""` in quotes, is refused with `400` and `25042 Invalid Operator Argument Type`. A firewall with Network Shield off refuses the rule with `25047 Missing Required Modules`, because of its *Network* criterion: *Set Rate Limit* alone needs no Network Shield. For the operators of the criterion, refer to [The Network criterion](/en/documentation/platform/firewall/network-shield/network-lists/#the-network-criterion). --- ## Confirm that the rate limit applies to listed clients A rule you add can take from 6 minutes 29 seconds to 9 minutes 18 seconds to reach traffic across Azion's distributed infrastructure. Until it does, the rule limits no client. Send the requests again until they answer as expected. *Set Rate Limit* does not refuse a request over the rate at once. For example, take a rule with a rate of one request per second and a burst of `1`. Requests that match it one after another are each held about one second, then served. Only concurrent requests beyond the burst receive `429`. A check that sends one request at a time can therefore get no `429` at all. For how the burst queues requests, refer to [Rate limits](/en/documentation/platform/firewall/how-it-works/#rate-limits). A refused request from a listed client receives `HTTP 429` and Azion's default error page, headed **Too Many Requests**. No rate-limit header comes back, so the client gets no signal of when to retry. The response looks like this: ```text HTTP/2 429 server: nginx content-type: text/html; charset=utf-8 x-content-type-options: nosniff x-azion-request-id: x-azion-edge-location: Azion - Default error page ... Too Many Requests ... Status Code 429 ``` The rule limits whichever clients the list holds when a request arrives. A change to the items of the list reaches traffic in 46 seconds to about 100 seconds, sooner than a rule you add. Until it settles, answers can switch between the old items and the updated ones. Repeat a request until the answers agree. --- ## Next steps - [Block addresses until a date](/en/documentation/guides/application-security/bots-and-network/temporary-block.md): Give an address in a list a due date, and remove it with a write once the date passes. - [Guard one path with a network list](/en/documentation/guides/application-security/bots-and-network/guard-one-path.md): Chain a Request Uri criterion in the same block, so a list rule applies to one path only. - [Network Lists](/en/documentation/platform/firewall/network-shield/network-lists.md): Each list type and item format, and every error that a list or a Network criterion returns. - [How Firewall works](/en/documentation/platform/firewall/how-it-works.md#network-shield): Its Network Shield section explains how a list matches a client address, and why a list change reaches traffic sooner than a rule. - [Firewall best practices](/en/documentation/platform/firewall/best-practices.md#keep-a-rate-limits-burst-within-ten-times-its-average-rate): Size the burst of a rate limit against its average rate before the rule reaches traffic. - [Firewall guides and tutorials](/en/documentation/platform/firewall/guides.md): Every guide for a firewall, with the other network list configurations among them.