← Waf / waf / tools

Lists

Lists allow you to group items such as IP addresses, hostnames, or autonomous system numbers (ASNs), and reference them by name in Cloudflare rule expressions. Instead of adding each item individually to every rule that needs it, you define the group once and reuse it across rules and zones.

You can create your own custom lists or use Managed Lists maintained by Cloudflare, such as Managed IP Lists that provide threat intelligence data.

Lists have the following advantages:

• When creating a rule, using a list is easier and less error-prone than adding a long list of items such as IP addresses to a rule expression.
• When updating a set of rules that target the same group of IP addresses (or hostnames), using an IP list (or a hostname list) is easier and less error prone than editing multiple rules.
• Lists are easier to read and more informative, particularly when you use descriptive names for your lists.

When you update the content of a list, any rules that use the list are automatically updated, so you can make a single change to your list rather than modify rules individually.

Cloudflare stores your lists at the account level. You can use the same list in rules of different zones in your Cloudflare account.

Cloudflare supports the following lists:

• Custom lists: Includes custom IP lists, hostname lists, and ASN lists.
• Managed Lists: Lists managed and updated by Cloudflare, such as Managed IP Lists.

Refer to each page for details.

You can also use inline lists in rule expressions. Inline lists allow you to include values directly in an expression without creating a separate list first. However, any changes to the values require editing the rule itself.

The name of a list must comply with the following requirements:

• The name uses only lowercase letters, numbers, and the underscore (_) character in the name. A valid name satisfies this regular expression: ^[a-z0-9_]+$.
• The maximum length of a list name is 50 characters.

You can create lists in the Cloudflare dashboard or using the Lists API.

After creating a list, you can add and remove items from the list, but you cannot change the list name or type.

Both the Cloudflare dashboard and the Cloudflare API support lists:

• To use lists in an expression from the Cloudflare dashboard, refer to Use lists in expressions.
• To reference a list in an API expression, refer to Lists in the Rules language reference.

You can search for list items in the dashboard or via API.

For IP lists, Cloudflare returns IP addresses or ranges that start with your search query. For example, searching 192.0.2 matches 192.0.2.1 and 192.0.2.0/24, but searching for 192.0.2.100 does not match a CIDR range like 192.0.2.0/24 that contains that address.

For Bulk Redirect Lists, Cloudflare returns entries where the source URL or target URL contains your search query.

List availability varies according to the list type and your Cloudflare plan and subscriptions.

Notes:

• The number of available custom lists depends on the highest plan in your account. Any account with at least one paid plan will get the highest quota.

• Customers on Enterprise plans can create a maximum of 1,000 custom lists in total across different list types. The following additional limits apply:

  • Up to 40 hostname lists, with a maximum of 10,000 list items across all hostname lists.
  • Up to 40 ASN lists, with a maximum of 30,000 list items across all ASN lists.

• Customers on Enterprise plans may contact their account team if they need more custom lists or a larger maximum number of items across lists.

• For details on the availability of Bulk Redirect Lists, refer to the Rules documentation.

The following user roles have access to the list management functionality:

• Super Administrator
• Administrator
• Firewall

You can only delete a list when no rules (enabled or disabled) reference it.

Cloudflare will apply the following rules when you add items to an existing list (either manually or via CSV file):

• Do not remove any existing list items before updating/adding items.
• Update items that were already in the list.
• Add items that were not present in the list.

To replace the entire contents of a list at once, format the data as an array and use the Update all list items operation in the Lists API.

The Cloudflare dashboard does not support downloading a list as a CSV file. To export list contents, use the Get list items API operation.