Lists

Use lists to refer to a group of items (such as IP addresses) collectively, by name, in rule expressions of Cloudflare products. You can create your own custom lists or use lists managed by Cloudflare, such as Managed IP Lists.

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, using an IP 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.

​​ List types

Cloudflare supports the following types of lists:

• IP Lists
• Bulk Redirect Lists

Refer to the page about each list type for details.

​​ List names

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.

​​ Working with lists

​​ Creating and editing lists

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.

​​ Using lists in expressions

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 Values: Lists in the Rules language reference.

​​ Availability

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

The number of IP Lists you can create depends on the Cloudflare plans associated with the zones in your account. You can store up to a total of 10,000 items across all your lists, regardless of your plan.

The Cloudflare Enterprise plan provides access to the Cloudflare Open Proxies Managed IP List. Other Managed IP Lists are available as part of Enterprise Security Bundles. For more information, contact your account team.

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

​​ User role requirements

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

• Super Administrator
• Administrator
• Firewall

​​ Final remarks

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

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, format the data as an array and use the Update all list items Open API docs link operation in the Lists API.

You cannot download a list in CSV format from the Cloudflare dashboard. If you need to download the contents of a list, use the Get list items Open API docs link operation to fetch the list items.