Load balancers

Manage Cloudflare Load Balancers to distribute traffic across multiple origin servers

The Load Balancers API allows you to create and manage load balancers that distribute traffic across multiple origin servers, improving availability and performance.

Create a load balancer

Create a new load balancer for a zone.

const loadBalancer = await client.loadBalancers.create({
  zone_id: '699d98642c564d2e855e9661899b7252',
  default_pools: [
    '17b5962d775c646f3f9725cbc7a53df4',
    '9290f38c5d07c2e2f4df57b1f61d4196',
    '00920f38ce07c2e2f4df50b1f61d4194',
  ],
  fallback_pool: 'fallback_pool',
  name: 'www.example.com',
});

zone_id · string · required

The zone identifier

default_pools · array · required

A list of pool IDs ordered by their failover priority. Cloudflare steers traffic to the first pool in the list, failing over to the next healthy pool.

fallback_pool · string · required

The pool ID to use when all other pools are detected as unhealthy.

name · string · required

The DNS hostname to associate with your load balancer.

description · string

An optional description of your load balancer.

enabled · boolean

Whether the load balancer is enabled. Defaults to true.

proxied · boolean

Whether the hostname gets Cloudflare’s origin protection. Defaults to false.

ttl · number

Time to live (TTL) of the DNS entry for the IP address returned by this load balancer.

region_pools · object

A mapping of region/country codes to a list of pool IDs (ordered by their failover priority) for the given region.

adaptive_routing · object

Controls features that modify the routing of requests to pools and origins in response to dynamic conditions.

failover_across_pools · boolean

Extends zero-downtime failover of requests to healthy origins from alternate pools.

session_affinity · string

Specifies the type of session affinity the load balancer should use. Options: none, cookie, ip_cookie, header.

id · string

The unique identifier of the load balancer

created_on · string

The timestamp when the load balancer was created

modified_on · string

The timestamp when the load balancer was last modified

name · string

The DNS hostname associated with the load balancer

default_pools · array

The list of pool IDs ordered by their failover priority

fallback_pool · string

The pool ID used when all other pools are unhealthy

Update a load balancer

Update a configured load balancer.

const loadBalancer = await client.loadBalancers.update(
  '699d98642c564d2e855e9661899b7252',
  {
    zone_id: '699d98642c564d2e855e9661899b7252',
    default_pools: [
      '17b5962d775c646f3f9725cbc7a53df4',
      '9290f38c5d07c2e2f4df57b1f61d4196',
    ],
    fallback_pool: 'fallback_pool',
    name: 'www.example.com',
  },
);

loadBalancerId · string · required

The load balancer identifier

List load balancers

List all load balancers configured in a zone.

for await (const loadBalancer of client.loadBalancers.list({
  zone_id: '699d98642c564d2e855e9661899b7252',
})) {
  console.log(loadBalancer.name);
}

zone_id · string · required

The zone identifier

Get a load balancer

Fetch details for a single configured load balancer.

const loadBalancer = await client.loadBalancers.get(
  '699d98642c564d2e855e9661899b7252',
  { zone_id: '699d98642c564d2e855e9661899b7252' },
);

loadBalancerId · string · required

The load balancer identifier

zone_id · string · required

The zone identifier

Edit a load balancer

Apply changes to an existing load balancer, overwriting only the supplied properties.

const loadBalancer = await client.loadBalancers.edit(
  '699d98642c564d2e855e9661899b7252',
  { 
    zone_id: '699d98642c564d2e855e9661899b7252',
    enabled: false,
  },
);

loadBalancerId · string · required

The load balancer identifier

zone_id · string · required

The zone identifier

Delete a load balancer

Delete a configured load balancer.

await client.loadBalancers.delete(
  '699d98642c564d2e855e9661899b7252',
  { zone_id: '699d98642c564d2e855e9661899b7252' },
);

loadBalancerId · string · required

The load balancer identifier

zone_id · string · required

The zone identifier

Related resources

• Monitors: Health check monitors for your origin servers
• Pools: Groups of origin servers that can be used by load balancers
• Monitor Groups: Manage groups of health check monitors