Nameserver sets

A nameserver set is an account-level group of two to five custom nameserver names, together with the IP addresses that Cloudflare assigns to those names. You create a set once and then assign it to zones in the same account.

Nameserver sets are a separate configuration from zone, account, and tenant custom nameservers. A zone uses either a nameserver set or one of those configurations, never both. Existing configurations cannot be converted into nameserver sets.

Nameserver sets are in beta and available to Enterprise customers through the API only.

To use a nameserver set, a zone must be in the same account as the set.

• Cloudflare assigns both IPv4 and IPv6 addresses to each nameserver name in a set.
• Each nameserver set is either standard or Advanced.
• Nameserver names can belong to any domain, even a domain that does not exist as a zone in Cloudflare.
• The same nameserver name can be used in more than one set within your account.
• Sets are immutable. You can create and delete a set, but you cannot change one.
• Cloudflare does not create or update DNS records for a nameserver set. You manage the required A, AAAA, and NS records, plus glue where DNS requires it.
• Currently, nameserver sets cannot yet be used as a DNS zone default for new zones.

Each nameserver set belongs to an IP set. The ip_set number defaults to 1 when omitted. IP sets control which addresses Cloudflare can assign:

• Sets with the same ip_set number and advanced value may reuse addresses.
• Sets with a different ip_set number or advanced value use separate address groups.

For example, a standard set with ip_set: 1 and an Advanced set with ip_set: 1 use separate IP sets.

A zone cannot use the same nameserver IP addresses as its parent zone, its subdomains, or a zone with the same name in another account. To use the same set type on a zone and its subdomains, create sets with different ip_set numbers.

The following limits apply to nameserver sets:

All nameserver names in an Advanced set must use the same ip_count value.

To create a set, use the Create Custom Nameserver Set endpoint.

Each name in a set must be unique and lowercase. Internationalized domain names must use Punycode.

Omit advanced or set it to false to create a standard nameserver set. Standard sets can use a different ip_count for each nameserver name.

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dns_settings/nameserver_sets" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"ip_set": 1,
		"nameservers": [
				{
						"name": "ns1.example.com"
				},
				{
						"name": "ns2.example.com",
						"ip_count": 2
				}
		]
	}'

The response contains the set ID and the addresses assigned to each nameserver name:

{
	"result": {
		"id": "0e1f2a3b4c5d6e7f8091a2b3c4d5e6f7",
		"advanced": false,
		"ip_set": 1,
		"nameservers": [
			{
				"name": "ns1.example.com",
				"ipv4": ["192.0.2.1"],
				"ipv6": ["2001:db8::1"]
			},
			{
				"name": "ns2.example.com",
				"ipv4": ["192.0.2.2", "192.0.2.3"],
				"ipv6": ["2001:db8::2", "2001:db8::3"]
			}
		],
		"created_on": "2026-01-15T12:00:00Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}

With a Foundation DNS subscription, set advanced to true to create an Advanced Custom Nameserver set. Cloudflare distributes its addresses across Advanced anycast network groups to improve resiliency.

Every nameserver name in the request must have the same ip_count. Cloudflare chooses the anycast groups.

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dns_settings/nameserver_sets" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"advanced": true,
		"ip_set": 1,
		"nameservers": [
				{
						"name": "ns1.example.com",
						"ip_count": 1
				},
				{
						"name": "ns2.example.com",
						"ip_count": 1
				},
				{
						"name": "ns3.example.com",
						"ip_count": 1
				}
		]
	}'

Advanced set responses include an anycast group for each address:

{
	"result": {
		"id": "1f2a3b4c5d6e7f8091a2b3c4d5e6f708",
		"advanced": true,
		"ip_set": 1,
		"nameservers": [
			{
				"name": "ns1.example.com",
				"ipv4": ["192.0.2.1"],
				"ipv4_groups": ["a"],
				"ipv6": ["2001:db8::1"],
				"ipv6_groups": ["a"]
			},
			{
				"name": "ns2.example.com",
				"ipv4": ["192.0.2.2"],
				"ipv4_groups": ["b"],
				"ipv6": ["2001:db8::2"],
				"ipv6_groups": ["b"]
			},
			{
				"name": "ns3.example.com",
				"ipv4": ["192.0.2.3"],
				"ipv4_groups": ["c"],
				"ipv6": ["2001:db8::3"],
				"ipv6_groups": ["c"]
			}
		],
		"created_on": "2026-01-15T12:00:00Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}

The ipv4_groups and ipv6_groups arrays map one-to-one to their corresponding address arrays. Each group value identifies the anycast group for the address at the same index.

Groups a and b are advertised from two separate sets of data centers that do not overlap. Each set is spread across the globe as evenly as possible. Group c is advertised from all Cloudflare data centers, so it includes every data center in a and b. For an example, refer to Anycast network groups.

An account cannot contain two sets with exactly the same nameserver names and addresses.

To list the sets in your account, send a GET request to the same endpoint, using the page and per_page query parameters to page through the results. To retrieve a single set, add its ID to the path.

Cloudflare does not create these records for you, even if the nameserver names belong to a domain that uses Cloudflare DNS.

To assign a set to a zone, use the Update DNS Settings for a Zone endpoint:

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_settings" \
	--request PATCH \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"nameservers": {
				"type": "custom",
				"nameserver_set_id": "0e1f2a3b4c5d6e7f8091a2b3c4d5e6f7"
		}
	}'

The assignment fails if the addresses in the set are already used by the parent zone, by a subdomain zone, or by a zone with the same name in another account. In that case, use a set with a different ip_set number.

Assigning a set replaces the zone's existing Cloudflare-branded standard or Advanced Nameservers, or its existing nameserver set. Both standard and Advanced Custom Nameserver sets use type: "custom" in zone DNS settings.

At the registrar of the zone that uses the set — or in the parent zone, if the zone is delegated — set the nameservers to all nameserver names in the set.

For a zone to activate and remain active without multi-provider DNS, these sets of values must match exactly:

• Nameserver names in the set and NS record set returned from the parent
• For each nameserver name, its assigned IPv4 addresses and live A answers
• For each nameserver name, its assigned IPv6 addresses and live AAAA answers

Cloudflare validates address answers for each nameserver name separately. An address assigned to one name cannot satisfy the requirement for another name, even if the records across the set contain every assigned address.

With multi-provider DNS, each expected nameserver name must be present amongst the NS record set returned from the parent. Each nameserver name must also return every IPv4 and IPv6 address assigned to it. Additional names and addresses are allowed.

Cloudflare does not separately validate parent glue. In-bailiwick nameservers still need usable glue for recursive resolution. Out-of-bailiwick nameservers do not inherently need parent glue.

A set cannot be deleted while it is assigned to a zone. To stop using custom nameservers on a zone, set the nameserver type back to cloudflare.standard or cloudflare.advanced, and update the nameservers at the registrar of the zone:

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_settings" \
	--request PATCH \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"nameservers": {
				"type": "cloudflare.standard"
		}
	}'

After the delegation or nameserver change has propagated, remove obsolete A, AAAA, and parent glue records. Wait for these removals to propagate.

Once no zone uses the set and these removals have propagated, delete the set:

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dns_settings/nameserver_sets/$NAMESERVER_SET_ID" \
	--request DELETE \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Cloudflare does not reserve the deleted set's name-to-address assignments. A new set may receive different addresses.