---
title: Lists API · Cloudflare Web Application Firewall (WAF) docs
description: The Lists API provides an interface for programmatically managing the following types of lists:
lastUpdated: 2024-12-16T22:33:26.000Z
source_url:
  html: https://zt-dark-mode-changelog.preview.developers.cloudflare.com/waf/tools/lists/lists-api/index.md
  md: https://zt-dark-mode-changelog.preview.developers.cloudflare.com/waf/tools/lists/lists-api/
---

The [Lists API](https://developers.cloudflare.com/api/resources/rules/subresources/lists/methods/list/) provides an interface for programmatically managing the following types of lists:

* [Custom lists](https://developers.cloudflare.com/waf/tools/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](https://developers.cloudflare.com/rules/url-forwarding/bulk-redirects/concepts/#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 [Values: Lists](https://developers.cloudflare.com/ruleset-engine/rules-language/values/#lists) in the Rules language documentation.

## Get started

To get started, review the Lists [JSON object](https://developers.cloudflare.com/waf/tools/lists/lists-api/json-object/) and [Endpoints](https://developers.cloudflare.com/waf/tools/lists/lists-api/endpoints/).

***

## Rate limiting for Lists API requests

Cloudflare may apply rate limiting to your API requests creating or deleting list items in custom lists and Bulk Redirect Lists.

Each operation (create or delete) on a list item counts as a change. The existing rate limit is based on the number of list changes over time. You can request a maximum of 10,000 list changes in five minutes.

Once the system has processed enough list changes so that they are under the threshold mentioned above, you can make additional API requests with more changes.
