The Lists API provides an interface for programmatically managing the following types of lists:
-
Custom lists: Contain one or more strings of the same type (such as IP addresses or hostnames) that you can reference collectively, by name, in rule expressions.
-
Bulk Redirect Lists: Contain URL redirects that you enable by creating a Bulk Redirect Rule.
To use a list in a rule expression, refer to Lists in the Rules language documentation.
To get started, review the Lists JSON object and Endpoints.
Cloudflare may apply rate limiting to your API requests creating, modifying, or deleting list items in custom lists and Bulk Redirect Lists.
Each operation (create, edit, or delete) on a list item counts as a modification. The following limits apply:
- You can make a maximum of 1,000,000 list item modifications in API requests over 12 hours.
- You can make a maximum of 30,000 API requests over 12 hours doing list item modifications.
If a write operation is still being processed — which happens asynchronously — and you submit a new request, you will receive a 429 HTTP status code. When this happens, submit your request again later.
Lists that are kept up to date by a CrowdSec integration have a stricter limit: you can perform one bulk operation on each of these lists every 24 hours.
If you exceed this limit, the API rejects the request with a 429 HTTP status code and error code 10040. The response does not include an operation_id, because the request is rejected before the bulk operation is created.
To avoid hitting this limit, schedule automated updates to run at most once every 24 hours, or use a separate custom list for more frequent updates.