--- description: Reference information on the JSON object used in Lists API calls. title: List JSON object image: https://developers.cloudflare.com/og-docs.png --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/waf/llms.txt > Use this file to discover all available pages before exploring further. # List JSON object Last updated Aug 25, 2026|Copy as Markdown| [View as Markdown](https://d1-custom-bindings-docs.previews.developers.cloudflare.com/waf/tools/lists/lists-api/json-object/index.md)| [Agent setup](https://d1-custom-bindings-docs.previews.developers.cloudflare.com/agent-setup/) ## List object structure and properties A JSON response for the [Lists API](https://d1-custom-bindings-docs.previews.developers.cloudflare.com/api/resources/rules/subresources/lists/) has this structure: ```json { "id": "2c0fc9fa937b11eaa1b71c4d701ab86e", "name": "my_list_name", "description": "List description.", "kind": "(ip|hostname|asn|redirect)", "num_items": 10, "num_referencing_filters": 2, "created_on": "2021-01-01T08:00:00Z", "modified_on": "2021-01-10T14:00:00Z" } ``` This table summarizes the object properties: | Property | Description | Constraints | | --- | --- | --- | | `id`
`String` | A UUIDv4 identifier generated by Cloudflare. | Unique, read only. Length: 32 characters. | | `name`
`String` | An informative name for the list. | Maximum length: 50 characters. Only alphanumeric and underscore (`_`) characters are valid. A valid name satisfies this regular expression: `^[a-zA-Z0-9_]+$`. | | `description`
`String` | An informative summary of the list. | Maximum length: 500 characters. | | `kind`
`String` | The type of data in the list. | Valid values: `ip`, `hostname`, `asn`, `redirect`. | | `num_items`
`Number` | The number of items in the list. | Read only. | | `num_referencing_filters`
`Number` | The number of filters that reference this list. | Read only. | | `created_on`
`String` | The [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) timestamp the list was created. | Read only. | | `modified_on`
`String` | The [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) timestamp when the list was last modified. | Read only. | ## List item object structure and properties Each list type (IP address, hostname, ASN, redirects) can only contain items of the same type. ### IP address A fully populated JSON object for an IP address list item has the following structure: ```json { "id": "7c5dae5552338874e5053f2534d2767a", "ip": "10.0.0.1/32", "comment": "CF DNS server", "created_on": "2021-10-01T05:20:00.12345Z", "modified_on": "2021-10-01T05:20:00.12345Z" } ``` ### Hostname A fully populated JSON object for a hostname list item has the following structure: ```json { "id": "7c5dae5552338874e5053f2534d2767a", "hostname": { "url_hostname": "*.example.com" }, "created_on": "2021-10-11T12:39:02Z", "modified_on": "2021-10-11T12:39:02Z" } ``` ### ASN A fully populated JSON object for an ASN list item has the following structure: ```json { "id": "7c5dae5552338874e5053f2534d2767a", "asn": 13335, "comment": "My provider's ASN", "created_on": "2021-10-11T12:39:02Z", "modified_on": "2021-10-11T12:39:02Z" } ``` ### URL redirect A fully populated JSON object for a Bulk Redirect List item has the following structure: ```json { "id": "7c5dae5552338874e5053f2534d2767a", "redirect": { "source_url": "https://example.com/blog", "target_url": "https://example.com/blog/latest", "status_code": 301, "include_subdomains": false, "subpath_matching": false, "preserve_query_string": false, "preserve_path_suffix": true }, "created_on": "2021-10-11T12:39:02Z", "modified_on": "2021-10-11T12:39:02Z" } ``` ### Properties reference The JSON object properties for a list item are defined as follows: | Property | Description | Constraints | | --- | --- | --- | | `id`
`String` | A UUIDv4 identifier generated by Cloudflare. | Unique, read only. Length: 32 characters. | | `ip`
`String` | An IP address or CIDR range. | Applies only to custom lists with IP addresses (IP lists). Any of these formats can exist in the same custom list with IP addresses: | | `comment`
`String` | An informative summary of the item. | Maximum length: 500 characters. | | `redirect`
`Object` | An object that contains the definition of a URL redirect. Refer to [URL redirect parameters](https://d1-custom-bindings-docs.previews.developers.cloudflare.com/rules/url-forwarding/bulk-redirects/reference/parameters/) for details. | Applies only to Bulk Redirect Lists. | | `hostname`
`Object` | An object containing a `url_hostname` property with a hostname value. Refer to [Lists with hostnames](https://d1-custom-bindings-docs.previews.developers.cloudflare.com/waf/tools/lists/custom-lists/#lists-with-hostnames) for details on the supported hostname values. | Applies only to custom lists with hostnames. | | `asn`
`Integer` | An ASN value. | Applies only to custom lists with ASNs. | | `created_on`
`String` | The [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) timestamp when the list was created. | Read only. | | `modified_on`
`String` | The [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) timestamp when the item was last modified. | Read only. | For a detailed specification, refer to the [Lists API](https://d1-custom-bindings-docs.previews.developers.cloudflare.com/api/resources/rules/subresources/lists/) documentation. Was this helpful? YesNo ## On this page [![](https://d1-custom-bindings-docs.previews.developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://d1-custom-bindings-docs.previews.developers.cloudflare.com/) ```json {"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/waf/tools/lists/lists-api/json-object/#page","headline":"List JSON object ยท Cloudflare Web Application Firewall (WAF) docs","description":"Reference information on the JSON object used in Lists API calls.","url":"https://developers.cloudflare.com/waf/tools/lists/lists-api/json-object/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-08-25","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"},"keywords":["JSON"]} ```