--- 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 24, 2026|Copy as Markdown|[View as Markdown](https://mchen-ai-models-sync.previews.developers.cloudflare.com/waf/tools/lists/lists-api/json-object/index.md)|[Agent setup](https://mchen-ai-models-sync.previews.developers.cloudflare.com/agent-setup/) ## List object structure and properties A JSON response for the [Lists API](https://mchen-ai-models-sync.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 | | ------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | idString | A UUIDv4 identifier generated by Cloudflare. | Unique, read only.Length: 32 characters. | | nameString | 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\_\]+$. | | descriptionString | An informative summary of the list. | Maximum length: 500 characters. | | kindString | The type of data in the list. | Valid values: ip, hostname, asn, redirect. | | num\_itemsNumber | The number of items in the list. | Read only. | | num\_referencing\_filtersNumber | The number of filters that reference this list. | Read only. | | created\_onString | The [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) timestamp the list was created. | Read only. | | modified\_onString | 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 | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | idString | A UUIDv4 identifier generated by Cloudflare. | Unique, read only.Length: 32 characters. | | ipString | 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 | | commentString | An informative summary of the item. | Maximum length: 500 characters. | | redirectObject | An object that contains the definition of a URL redirect. Refer to [URL redirect parameters](https://mchen-ai-models-sync.previews.developers.cloudflare.com/rules/url-forwarding/bulk-redirects/reference/parameters/) for details. | Applies only to Bulk Redirect Lists. | | hostnameObject | An object containing a url\_hostname property with a hostname value. Refer to [Lists with hostnames](https://mchen-ai-models-sync.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. | | asnInteger | An ASN value. | Applies only to custom lists with ASNs. | | created\_onString | The [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) timestamp when the list was created. | Read only. | | modified\_onString | 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://mchen-ai-models-sync.previews.developers.cloudflare.com/api/resources/rules/subresources/lists/) documentation. Was this helpful? YesNo ## On this page [![](https://mchen-ai-models-sync.previews.developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://mchen-ai-models-sync.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-24","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"]} ```