--- title: List JSON object description: Reference information on the JSON object used in Lists API calls. image: https://developers.cloudflare.com/core-services-preview.png --- > 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. [Skip to content](#%5Ftop) # List JSON object ## List object structure and properties A JSON response for the [Lists API](https://developers.cloudflare.com/api/resources/rules/subresources/lists/) has this structure: ``` { "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: ``` { "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: ``` { "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: ``` { "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: ``` { "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:IPv4 addressIPv6 addressIPv4 ranges as /8 through /32 CIDRsIPv6 ranges as /12 through /128 CIDRs | | 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://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://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://developers.cloudflare.com/api/resources/rules/subresources/lists/) documentation. ```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/core-services-preview.png","dateModified":"2026-04-16","publisher":{"@type":"Organization","name":"Cloudflare","url":"https://www.cloudflare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"},"keywords":["JSON"]} {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/waf/","name":"WAF"}},{"@type":"ListItem","position":3,"item":{"@id":"/waf/tools/","name":"Additional tools"}},{"@type":"ListItem","position":4,"item":{"@id":"/waf/tools/lists/","name":"Lists"}},{"@type":"ListItem","position":5,"item":{"@id":"/waf/tools/lists/lists-api/","name":"Lists API"}},{"@type":"ListItem","position":6,"item":{"@id":"/waf/tools/lists/lists-api/json-object/","name":"List JSON object"}}]} ```