Patch account or zone Load Balancer

PATCH/{accounts_or_zones}/{account_or_zone_id}/load_balancers/{load_balancer_id}

Apply changes to an existing account or zone-scoped load balancer, overwriting the supplied properties.

Security

API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194

Accepted Permissions (at least one required)

Load Balancers Account Write

Path ParametersExpand Collapse

load_balancer_id: string

account_id: optional string

The Account ID to use for this endpoint. Mutually exclusive with the Zone ID.

zone_id: optional string

The Zone ID to use for this endpoint. Mutually exclusive with the Account ID.

Body ParametersJSONExpand Collapse

adaptive_routing: optional AdaptiveRouting { failover_across_pools }

Controls features that modify the routing of requests to pools and origins in response to dynamic conditions, such as during the interval between active health monitoring requests. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin.

failover_across_pools: optional boolean

Extends zero-downtime failover of requests to healthy origins from alternate pools, when no healthy alternate exists in the same pool, according to the failover order defined by traffic and origin steering. When set false (the default) zero-downtime failover will only occur between origins within the same pool. See session_affinity_attributes for control over when sessions are broken or reassigned.

country_pools: optional map[array of string]

A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools.

default_pools: optional array of DefaultPools

A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region.

description: optional string

Object description.

enabled: optional boolean

Whether to enable (the default) this load balancer.

fallback_pool: optional string

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

location_strategy: optional LocationStrategy { mode, prefer_ecs }

Controls location-based steering for non-proxied requests. See steering_policy to learn how steering is affected.

mode: optional "pop" or "resolver_ip"

Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful.

"pop": Use the Cloudflare PoP location.
"resolver_ip": Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location.

One of the following:

"pop"

"resolver_ip"

prefer_ecs: optional "always" or "never" or "proximity" or "geo"

Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location.

"always": Always prefer ECS.
"never": Never prefer ECS.
"proximity": Prefer ECS only when steering_policy="proximity".
"geo": Prefer ECS only when steering_policy="geo".

One of the following:

"always"

"never"

"proximity"

"geo"

The DNS hostname to associate with your Load Balancer. If this hostname already exists as a DNS record in Cloudflares DNS, the Load Balancer will take precedence and the DNS record will not be used.

networks: optional array of string

List of networks where Load Balancer or Pool is enabled.

pop_pools: optional map[array of string]

Enterprise only: A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using the corresponding country_pool, then region_pool mapping if it exists else to default_pools.

proxied: optional boolean

Whether the hostname should be gray clouded (false) or orange clouded (true).

random_steering: optional RandomSteering { default_weight, pool_weights }

Configures pool weights.

steering_policy="random": A random pool is selected with probability proportional to pool weights.
steering_policy="least_outstanding_requests": Use pool weights to scale each pools outstanding requests.
steering_policy="least_connections": Use pool weights to scale each pools open connections.

default_weight: optional number

The default weight for pools in the load balancer that are not specified in the pool_weights map.

maximum1

minimum0

multipleOf0.1

pool_weights: optional map[number]

A mapping of pool IDs to custom weights. The weight is relative to other pools in the load balancer.

region_pools: optional map[array of string]

A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools.

rules: optional array of Rules { condition, disabled, fixed_response, 4 more }

BETA Field Not General Access: A list of rules for this load balancer to execute.

condition: optional string

The condition expressions to evaluate. If the condition evaluates to true, the overrides or fixed_response in this rule will be applied. An empty condition is always true. For more details on condition expressions, please see https://developers.cloudflare.com/load-balancing/understand-basics/load-balancing-rules/expressions.

disabled: optional boolean

Disable this specific rule. It will no longer be evaluated by this load balancer.

fixed_response: optional object { content_type, location, message_body, status_code }

A collection of fields used to directly respond to the client instead of routing to a pool. When supplied on a rule, that rule stops further rule evaluation.

content_type: optional string

The http Content-Type header to include in the response.

maxLength32

location: optional string

The http Location header to include in the response.

maxLength2048

message_body: optional string

Text to include as the http body.

maxLength1024

status_code: optional number

The http status code to respond with.

Name of this rule. Only used for human readability.

maxLength200

overrides: optional object { adaptive_routing, country_pools, default_pools, 13 more }

A collection of overrides to apply when this rules condition (or a pool sets match) is true. All fields are optional.

adaptive_routing: optional AdaptiveRouting { failover_across_pools }

failover_across_pools: optional boolean

country_pools: optional map[array of string]

default_pools: optional array of DefaultPools

A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region.

fallback_pool: optional string

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

location_strategy: optional LocationStrategy { mode, prefer_ecs }

Controls location-based steering for non-proxied requests. See steering_policy to learn how steering is affected.

mode: optional "pop" or "resolver_ip"

Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful.

"pop": Use the Cloudflare PoP location.
"resolver_ip": Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location.

One of the following:

"pop"

"resolver_ip"

prefer_ecs: optional "always" or "never" or "proximity" or "geo"

Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location.

"always": Always prefer ECS.
"never": Never prefer ECS.
"proximity": Prefer ECS only when steering_policy="proximity".
"geo": Prefer ECS only when steering_policy="geo".

One of the following:

"always"

"never"

"proximity"

"geo"

pool_default_weight: optional number

The default weight for pools not listed in pool_weights. The declarative alternative to random_steering.default_weight; mutually exclusive with random_steering.

maximum1

minimum0

multipleOf0.1

pool_weights: optional map[number]

A mapping of pool IDs to custom weights, relative to the other pools. The declarative alternative to random_steering.pool_weights; mutually exclusive with random_steering.

pools: optional array of string

A flat, ordered list of pool IDs to route the matched audience to. Replaces the resolved topology with exactly these pools. Mutually exclusive with fixed_response.

pop_pools: optional map[array of string]

random_steering: optional RandomSteering { default_weight, pool_weights }

Configures pool weights.

steering_policy="random": A random pool is selected with probability proportional to pool weights.
steering_policy="least_outstanding_requests": Use pool weights to scale each pools outstanding requests.
steering_policy="least_connections": Use pool weights to scale each pools open connections.

default_weight: optional number

The default weight for pools in the load balancer that are not specified in the pool_weights map.

maximum1

minimum0

multipleOf0.1

pool_weights: optional map[number]

A mapping of pool IDs to custom weights. The weight is relative to other pools in the load balancer.

region_pools: optional map[array of string]

A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools.

session_affinity: optional SessionAffinity

Specifies the type of session affinity the load balancer should use unless specified as "none". The supported types are: - "cookie": On the first request to a proxied load balancer, a cookie is generated, encoding information of which origin the request will be forwarded to. Subsequent requests, by the same client to the same load balancer, will be sent to the origin server the cookie encodes, for the duration of the cookie and as long as the origin server remains healthy. If the cookie has expired or the origin server is unhealthy, then a new origin server is calculated and used. - "ip_cookie": Behaves the same as "cookie" except the initial origin selection is stable and based on the clients ip address. - "header": On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see session_affinity_attributes.headers) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of session_affinity_ttl seconds or the origin server is unhealthy, then a new origin server is calculated and used. See headers in session_affinity_attributes for additional required configuration.

One of the following:

"none"

"cookie"

"ip_cookie"

"header"

session_affinity_attributes: optional SessionAffinityAttributes { drain_duration, headers, require_all_headers, 3 more }

Configures attributes for session affinity.

drain_duration: optional number

Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer.

headers: optional array of string

Configures the names of HTTP headers to base session affinity on when header session_affinity is enabled. At least one HTTP header name must be provided. To specify the exact cookies to be used, include an item in the following format: "cookie:<cookie-name-1>,<cookie-name-2>" (example) where everything after the colon is a comma-separated list of cookie names. Providing only "cookie" will result in all cookies being used. The default max number of HTTP header names that can be provided depends on your plan: 5 for Enterprise, 1 for all other plans.

require_all_headers: optional boolean

When header session_affinity is enabled, this option can be used to specify how HTTP headers on load balancing requests will be used. The supported values are: - "true": Load balancing requests must contain all of the HTTP headers specified by the headers session affinity attribute, otherwise sessions arent created. - "false": Load balancing requests must contain at least one of the HTTP headers specified by the headers session affinity attribute, otherwise sessions arent created.

samesite: optional "Auto" or "Lax" or "None" or "Strict"

Configures the SameSite attribute on session affinity cookie. Value Auto will be translated to Lax or None depending if Always Use HTTPS is enabled. Note: when using value None, the secure attribute can not be set to Never.

One of the following:

"Auto"

"Lax"

"None"

"Strict"

secure: optional "Auto" or "Always" or "Never"

Configures the Secure attribute on session affinity cookie. Value Always indicates the Secure attribute will be set in the Set-Cookie header, Never indicates the Secure attribute will not be set, and Auto will set the Secure attribute depending if Always Use HTTPS is enabled.

One of the following:

"Auto"

"Always"

"Never"

zero_downtime_failover: optional "none" or "temporary" or "sticky"

Configures the zero-downtime failover between origins within a pool when session affinity is enabled. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. The supported values are: - "none": No failover takes place for sessions pinned to the origin (default). - "temporary": Traffic will be sent to another other healthy origin until the originally pinned origin is available; note that this can potentially result in heavy origin flapping. - "sticky": The session affinity cookie is updated and subsequent requests are sent to the new origin. Note: Zero-downtime failover with sticky sessions is currently not supported for session affinity by header.

One of the following:

"none"

"temporary"

"sticky"

session_affinity_ttl: optional number

Time, in seconds, until a clients session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per session_affinity policy are: - "cookie" / "ip_cookie": The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. - "header": The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they havent been used for the number of seconds specified.

steering_policy: optional SteeringPolicy

Steering Policy for this load balancer.

"off": Use default_pools.
"geo": Use region_pools/country_pools/pop_pools. For non-proxied requests, the country for country_pools is determined by location_strategy.
"random": Select a pool randomly.
"dynamic_latency": Use round trip time to select the closest pool in default_pools (requires pool health checks).
"proximity": Use the pools latitude and longitude to select the closest pool using the Cloudflare PoP location for proxied requests or the location determined by location_strategy for non-proxied requests.
"least_outstanding_requests": Select a pool by taking into consideration random_steering weights, as well as each pools number of outstanding requests. Pools with more pending requests are weighted proportionately less relative to others.
"least_connections": Select a pool by taking into consideration random_steering weights, as well as each pools number of open connections. Pools with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections.
"": Will map to "geo" if you use region_pools/country_pools/pop_pools otherwise "off".

One of the following:

"off"

"geo"

"random"

"dynamic_latency"

"proximity"

"least_outstanding_requests"

"least_connections"

ttl: optional number

Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers.

priority: optional number

The order in which rules should be executed in relation to each other. Lower values are executed first. Values do not need to be sequential. If no value is provided for any rule the array order of the rules field will be used to assign a priority.

minimum0

terminates: optional boolean

If this rules condition is true, this causes rule evaluation to stop after processing this rule.

session_affinity: optional SessionAffinity

One of the following:

"none"

"cookie"

"ip_cookie"

"header"

session_affinity_attributes: optional SessionAffinityAttributes { drain_duration, headers, require_all_headers, 3 more }

Configures attributes for session affinity.

drain_duration: optional number

Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer.

headers: optional array of string

require_all_headers: optional boolean

samesite: optional "Auto" or "Lax" or "None" or "Strict"

One of the following:

"Auto"

"Lax"

"None"

"Strict"

secure: optional "Auto" or "Always" or "Never"

One of the following:

"Auto"

"Always"

"Never"

zero_downtime_failover: optional "none" or "temporary" or "sticky"

One of the following:

"none"

"temporary"

"sticky"

session_affinity_ttl: optional number

steering_policy: optional SteeringPolicy

Steering Policy for this load balancer.

"off": Use default_pools.
"geo": Use region_pools/country_pools/pop_pools. For non-proxied requests, the country for country_pools is determined by location_strategy.
"random": Select a pool randomly.
"dynamic_latency": Use round trip time to select the closest pool in default_pools (requires pool health checks).
"proximity": Use the pools latitude and longitude to select the closest pool using the Cloudflare PoP location for proxied requests or the location determined by location_strategy for non-proxied requests.
"least_outstanding_requests": Select a pool by taking into consideration random_steering weights, as well as each pools number of outstanding requests. Pools with more pending requests are weighted proportionately less relative to others.
"least_connections": Select a pool by taking into consideration random_steering weights, as well as each pools number of open connections. Pools with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections.
"": Will map to "geo" if you use region_pools/country_pools/pop_pools otherwise "off".

One of the following:

"off"

"geo"

"random"

"dynamic_latency"

"proximity"

"least_outstanding_requests"

"least_connections"

ttl: optional number

Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers.

ReturnsExpand Collapse

errors: array of ResponseInfo { code, message, documentation_url, source }

code: number

minimum1000

message: string

documentation_url: optional string

source: optional object { pointer }

pointer: optional string

messages: array of ResponseInfo { code, message, documentation_url, source }

code: number

minimum1000

message: string

documentation_url: optional string

source: optional object { pointer }

pointer: optional string

result: LoadBalancer { id, adaptive_routing, country_pools, 21 more }

id: optional string

adaptive_routing: optional AdaptiveRouting { failover_across_pools }

failover_across_pools: optional boolean

country_pools: optional map[array of string]

created_on: optional string

default_pools: optional array of DefaultPools

A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region.

description: optional string

Object description.

enabled: optional boolean

Whether to enable (the default) this load balancer.

fallback_pool: optional string

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

location_strategy: optional LocationStrategy { mode, prefer_ecs }

Controls location-based steering for non-proxied requests. See steering_policy to learn how steering is affected.

mode: optional "pop" or "resolver_ip"

Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful.

"pop": Use the Cloudflare PoP location.
"resolver_ip": Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location.

One of the following:

"pop"

"resolver_ip"

prefer_ecs: optional "always" or "never" or "proximity" or "geo"

Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location.

"always": Always prefer ECS.
"never": Never prefer ECS.
"proximity": Prefer ECS only when steering_policy="proximity".
"geo": Prefer ECS only when steering_policy="geo".

One of the following:

"always"

"never"

"proximity"

"geo"

modified_on: optional string

The DNS hostname to associate with your Load Balancer. If this hostname already exists as a DNS record in Cloudflares DNS, the Load Balancer will take precedence and the DNS record will not be used.

networks: optional array of string

List of networks where Load Balancer or Pool is enabled.

pool_sets: optional array of object { disabled, fixed_response, match, 2 more }

An optional list of pool sets, evaluated in array order with first match wins. Pool sets are independent from the standard steering fields (region_pools / country_pools / pop_pools / default_pools / steering_policy / random_steering / fallback_pool / rules). On a PATCH, an empty array (pool_sets: []) clears all pool sets, while omitting the field leaves existing pool sets unchanged.

disabled: optional boolean

Disable this specific pool set. It will no longer be evaluated.

fixed_response: optional object { content_type, location, message_body, status_code }

A collection of fields used to directly respond to the client instead of routing to a pool. When supplied on a rule, that rule stops further rule evaluation.

content_type: optional string

The http Content-Type header to include in the response.

maxLength32

location: optional string

The http Location header to include in the response.

maxLength2048

message_body: optional string

Text to include as the http body.

maxLength1024

status_code: optional number

The http status code to respond with.

match: optional object { default, topology }

Determines which requests a pool set applies to. Set topology to match by location or default: true to match all requests; the two are mutually exclusive. A pool set with no match matches all requests.

default: optional boolean

When true, matches every request. Cannot be combined with topology.

topology: optional object { countries, pops, regions }

Matches requests by location. Set any combination of pops, countries, and regions (at least one is required); a request matches when its value appears in any populated list (e.g. regions: ["WNAM"] with countries: ["US"] matches a request in either WNAM or the US).

countries: optional array of string

A list of ISO 3166-1 alpha-2 country codes. Matches when the requests country is in this list.

pops: optional array of string

A list of Cloudflare PoP codes. Matches when the requests PoP is in this list.

regions: optional array of string

A list of Cloudflare region codes (e.g. WNAM, ENAM, WEU). Matches when the requests region is in this list.

A human-readable name for this pool set.

maxLength200

overrides: optional object { fallback_pool, pool_default_weight, pool_weights, 2 more }

The behavior a pool set applies when its match succeeds. A strict subset of a rules overrides: a pool set replaces the topology wholesale with a flat pool list (pools), so only the declarative pool-routing fields plus fallback_pool and steering_policy are settable. All fields are optional.

fallback_pool: optional string

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

pool_default_weight: optional number

The default weight for pools not listed in pool_weights. The declarative alternative to random_steering.default_weight; mutually exclusive with random_steering.

maximum1

minimum0

multipleOf0.1

pool_weights: optional map[number]

A mapping of pool IDs to custom weights, relative to the other pools. The declarative alternative to random_steering.pool_weights; mutually exclusive with random_steering.

pools: optional array of string

A flat, ordered list of pool IDs to route the matched audience to. Replaces the resolved topology with exactly these pools. Mutually exclusive with fixed_response.

steering_policy: optional SteeringPolicy

Steering Policy for this load balancer.

"off": Use default_pools.
"geo": Use region_pools/country_pools/pop_pools. For non-proxied requests, the country for country_pools is determined by location_strategy.
"random": Select a pool randomly.
"dynamic_latency": Use round trip time to select the closest pool in default_pools (requires pool health checks).
"proximity": Use the pools latitude and longitude to select the closest pool using the Cloudflare PoP location for proxied requests or the location determined by location_strategy for non-proxied requests.
"least_outstanding_requests": Select a pool by taking into consideration random_steering weights, as well as each pools number of outstanding requests. Pools with more pending requests are weighted proportionately less relative to others.
"least_connections": Select a pool by taking into consideration random_steering weights, as well as each pools number of open connections. Pools with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections.
"": Will map to "geo" if you use region_pools/country_pools/pop_pools otherwise "off".

One of the following:

"off"

"geo"

"random"

"dynamic_latency"

"proximity"

"least_outstanding_requests"

"least_connections"

pop_pools: optional map[array of string]

proxied: optional boolean

Whether the hostname should be gray clouded (false) or orange clouded (true).

random_steering: optional RandomSteering { default_weight, pool_weights }

Configures pool weights.

steering_policy="random": A random pool is selected with probability proportional to pool weights.
steering_policy="least_outstanding_requests": Use pool weights to scale each pools outstanding requests.
steering_policy="least_connections": Use pool weights to scale each pools open connections.

default_weight: optional number

The default weight for pools in the load balancer that are not specified in the pool_weights map.

maximum1

minimum0

multipleOf0.1

pool_weights: optional map[number]

A mapping of pool IDs to custom weights. The weight is relative to other pools in the load balancer.

region_pools: optional map[array of string]

A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools.

rules: optional array of Rules { condition, disabled, fixed_response, 4 more }

BETA Field Not General Access: A list of rules for this load balancer to execute.

condition: optional string

disabled: optional boolean

Disable this specific rule. It will no longer be evaluated by this load balancer.

fixed_response: optional object { content_type, location, message_body, status_code }

A collection of fields used to directly respond to the client instead of routing to a pool. When supplied on a rule, that rule stops further rule evaluation.

content_type: optional string

The http Content-Type header to include in the response.

maxLength32

location: optional string

The http Location header to include in the response.

maxLength2048

message_body: optional string

Text to include as the http body.

maxLength1024

status_code: optional number

The http status code to respond with.

Name of this rule. Only used for human readability.

maxLength200

overrides: optional object { adaptive_routing, country_pools, default_pools, 13 more }

A collection of overrides to apply when this rules condition (or a pool sets match) is true. All fields are optional.

adaptive_routing: optional AdaptiveRouting { failover_across_pools }

failover_across_pools: optional boolean

country_pools: optional map[array of string]

default_pools: optional array of DefaultPools

A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region.

fallback_pool: optional string

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

location_strategy: optional LocationStrategy { mode, prefer_ecs }

Controls location-based steering for non-proxied requests. See steering_policy to learn how steering is affected.

mode: optional "pop" or "resolver_ip"

Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful.

"pop": Use the Cloudflare PoP location.
"resolver_ip": Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location.

One of the following:

"pop"

"resolver_ip"

prefer_ecs: optional "always" or "never" or "proximity" or "geo"

Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location.

"always": Always prefer ECS.
"never": Never prefer ECS.
"proximity": Prefer ECS only when steering_policy="proximity".
"geo": Prefer ECS only when steering_policy="geo".

One of the following:

"always"

"never"

"proximity"

"geo"

pool_default_weight: optional number

The default weight for pools not listed in pool_weights. The declarative alternative to random_steering.default_weight; mutually exclusive with random_steering.

maximum1

minimum0

multipleOf0.1

pool_weights: optional map[number]

A mapping of pool IDs to custom weights, relative to the other pools. The declarative alternative to random_steering.pool_weights; mutually exclusive with random_steering.

pools: optional array of string

A flat, ordered list of pool IDs to route the matched audience to. Replaces the resolved topology with exactly these pools. Mutually exclusive with fixed_response.

pop_pools: optional map[array of string]

random_steering: optional RandomSteering { default_weight, pool_weights }

Configures pool weights.

steering_policy="random": A random pool is selected with probability proportional to pool weights.
steering_policy="least_outstanding_requests": Use pool weights to scale each pools outstanding requests.
steering_policy="least_connections": Use pool weights to scale each pools open connections.

default_weight: optional number

The default weight for pools in the load balancer that are not specified in the pool_weights map.

maximum1

minimum0

multipleOf0.1

pool_weights: optional map[number]

A mapping of pool IDs to custom weights. The weight is relative to other pools in the load balancer.

region_pools: optional map[array of string]

A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools.

session_affinity: optional SessionAffinity

One of the following:

"none"

"cookie"

"ip_cookie"

"header"

session_affinity_attributes: optional SessionAffinityAttributes { drain_duration, headers, require_all_headers, 3 more }

Configures attributes for session affinity.

drain_duration: optional number

Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer.

headers: optional array of string

require_all_headers: optional boolean

samesite: optional "Auto" or "Lax" or "None" or "Strict"

One of the following:

"Auto"

"Lax"

"None"

"Strict"

secure: optional "Auto" or "Always" or "Never"

One of the following:

"Auto"

"Always"

"Never"

zero_downtime_failover: optional "none" or "temporary" or "sticky"

One of the following:

"none"

"temporary"

"sticky"

session_affinity_ttl: optional number

steering_policy: optional SteeringPolicy

Steering Policy for this load balancer.

"off": Use default_pools.
"geo": Use region_pools/country_pools/pop_pools. For non-proxied requests, the country for country_pools is determined by location_strategy.
"random": Select a pool randomly.
"dynamic_latency": Use round trip time to select the closest pool in default_pools (requires pool health checks).
"proximity": Use the pools latitude and longitude to select the closest pool using the Cloudflare PoP location for proxied requests or the location determined by location_strategy for non-proxied requests.
"least_outstanding_requests": Select a pool by taking into consideration random_steering weights, as well as each pools number of outstanding requests. Pools with more pending requests are weighted proportionately less relative to others.
"least_connections": Select a pool by taking into consideration random_steering weights, as well as each pools number of open connections. Pools with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections.
"": Will map to "geo" if you use region_pools/country_pools/pop_pools otherwise "off".

One of the following:

"off"

"geo"

"random"

"dynamic_latency"

"proximity"

"least_outstanding_requests"

"least_connections"

ttl: optional number

Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers.

priority: optional number

minimum0

terminates: optional boolean

If this rules condition is true, this causes rule evaluation to stop after processing this rule.

session_affinity: optional SessionAffinity

One of the following:

"none"

"cookie"

"ip_cookie"

"header"

session_affinity_attributes: optional SessionAffinityAttributes { drain_duration, headers, require_all_headers, 3 more }

Configures attributes for session affinity.

drain_duration: optional number

Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer.

headers: optional array of string

require_all_headers: optional boolean

samesite: optional "Auto" or "Lax" or "None" or "Strict"

One of the following:

"Auto"

"Lax"

"None"

"Strict"

secure: optional "Auto" or "Always" or "Never"

One of the following:

"Auto"

"Always"

"Never"

zero_downtime_failover: optional "none" or "temporary" or "sticky"

One of the following:

"none"

"temporary"

"sticky"

session_affinity_ttl: optional number

steering_policy: optional SteeringPolicy

Steering Policy for this load balancer.

"off": Use default_pools.
"geo": Use region_pools/country_pools/pop_pools. For non-proxied requests, the country for country_pools is determined by location_strategy.
"random": Select a pool randomly.
"dynamic_latency": Use round trip time to select the closest pool in default_pools (requires pool health checks).
"proximity": Use the pools latitude and longitude to select the closest pool using the Cloudflare PoP location for proxied requests or the location determined by location_strategy for non-proxied requests.
"least_outstanding_requests": Select a pool by taking into consideration random_steering weights, as well as each pools number of outstanding requests. Pools with more pending requests are weighted proportionately less relative to others.
"least_connections": Select a pool by taking into consideration random_steering weights, as well as each pools number of open connections. Pools with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections.
"": Will map to "geo" if you use region_pools/country_pools/pop_pools otherwise "off".

One of the following:

"off"

"geo"

"random"

"dynamic_latency"

"proximity"

"least_outstanding_requests"

"least_connections"

ttl: optional number

Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers.

zone_name: optional string

success: true

Whether the API call was successful.

Patch account or zone Load Balancer

curl https://api.cloudflare.com/client/v4/$ACCOUNTS_OR_ZONES/$ACCOUNT_OR_ZONE_ID/load_balancers/$LOAD_BALANCER_ID \
    -X PATCH \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    -d '{
          "country_pools": {
            "GB": [
              "abd90f38ced07c2e2f4df50b1f61d4194"
            ],
            "US": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "00920f38ce07c2e2f4df50b1f61d4194"
            ]
          },
          "default_pools": [
            "17b5962d775c646f3f9725cbc7a53df4",
            "9290f38c5d07c2e2f4df57b1f61d4196",
            "00920f38ce07c2e2f4df50b1f61d4194"
          ],
          "description": "Load Balancer for www.example.com",
          "enabled": true,
          "name": "www.example.com",
          "pop_pools": {
            "LAX": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "9290f38c5d07c2e2f4df57b1f61d4196"
            ],
            "LHR": [
              "abd90f38ced07c2e2f4df50b1f61d4194",
              "f9138c5d07c2e2f4df57b1f61d4196"
            ],
            "SJC": [
              "00920f38ce07c2e2f4df50b1f61d4194"
            ]
          },
          "proxied": true,
          "region_pools": {
            "ENAM": [
              "00920f38ce07c2e2f4df50b1f61d4194"
            ],
            "WNAM": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "9290f38c5d07c2e2f4df57b1f61d4196"
            ]
          },
          "session_affinity": "cookie",
          "session_affinity_ttl": 1800,
          "steering_policy": "dynamic_latency",
          "ttl": 30
        }'

200 example

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": {
    "id": "699d98642c564d2e855e9661899b7252",
    "adaptive_routing": {
      "failover_across_pools": true
    },
    "country_pools": {
      "GB": [
        "abd90f38ced07c2e2f4df50b1f61d4194"
      ],
      "US": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "00920f38ce07c2e2f4df50b1f61d4194"
      ]
    },
    "created_on": "2014-01-01T05:20:00.12345Z",
    "default_pools": [
      "17b5962d775c646f3f9725cbc7a53df4",
      "9290f38c5d07c2e2f4df57b1f61d4196",
      "00920f38ce07c2e2f4df50b1f61d4194"
    ],
    "description": "Load Balancer for www.example.com",
    "enabled": true,
    "fallback_pool": "fallback_pool",
    "location_strategy": {
      "mode": "resolver_ip",
      "prefer_ecs": "always"
    },
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "name": "www.example.com",
    "networks": [
      "string"
    ],
    "pool_sets": [
      {
        "disabled": true,
        "fixed_response": {
          "content_type": "application/json",
          "location": "www.example.com",
          "message_body": "Testing Hello",
          "status_code": 0
        },
        "match": {
          "default": true,
          "topology": {
            "countries": [
              "string"
            ],
            "pops": [
              "string"
            ],
            "regions": [
              "WNAM"
            ]
          }
        },
        "name": "wnam-primary",
        "overrides": {
          "fallback_pool": "9290f38c5d07c2e2f4df57b1f61d4196",
          "pool_default_weight": 0.2,
          "pool_weights": {
            "9290f38c5d07c2e2f4df57b1f61d4196": 0.5,
            "de90f38ced07c2e2f4df50b1f61d4194": 0.3
          },
          "pools": [
            "17b5962d775c646f3f9725cbc7a53df4"
          ],
          "steering_policy": "random"
        }
      }
    ],
    "pop_pools": {
      "LAX": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "9290f38c5d07c2e2f4df57b1f61d4196"
      ],
      "LHR": [
        "abd90f38ced07c2e2f4df50b1f61d4194",
        "f9138c5d07c2e2f4df57b1f61d4196"
      ],
      "SJC": [
        "00920f38ce07c2e2f4df50b1f61d4194"
      ]
    },
    "proxied": true,
    "random_steering": {
      "default_weight": 0.2,
      "pool_weights": {
        "9290f38c5d07c2e2f4df57b1f61d4196": 0.5,
        "de90f38ced07c2e2f4df50b1f61d4194": 0.3
      }
    },
    "region_pools": {
      "ENAM": [
        "00920f38ce07c2e2f4df50b1f61d4194"
      ],
      "WNAM": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "9290f38c5d07c2e2f4df57b1f61d4196"
      ]
    },
    "rules": [
      {
        "condition": "http.request.uri.path contains \"/testing\"",
        "disabled": true,
        "fixed_response": {
          "content_type": "application/json",
          "location": "www.example.com",
          "message_body": "Testing Hello",
          "status_code": 0
        },
        "name": "route the path /testing to testing datacenter.",
        "overrides": {
          "adaptive_routing": {
            "failover_across_pools": true
          },
          "country_pools": {
            "GB": [
              "abd90f38ced07c2e2f4df50b1f61d4194"
            ],
            "US": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "00920f38ce07c2e2f4df50b1f61d4194"
            ]
          },
          "default_pools": [
            "17b5962d775c646f3f9725cbc7a53df4",
            "9290f38c5d07c2e2f4df57b1f61d4196",
            "00920f38ce07c2e2f4df50b1f61d4194"
          ],
          "fallback_pool": "fallback_pool",
          "location_strategy": {
            "mode": "resolver_ip",
            "prefer_ecs": "always"
          },
          "pool_default_weight": 0.2,
          "pool_weights": {
            "9290f38c5d07c2e2f4df57b1f61d4196": 0.5,
            "de90f38ced07c2e2f4df50b1f61d4194": 0.3
          },
          "pools": [
            "17b5962d775c646f3f9725cbc7a53df4"
          ],
          "pop_pools": {
            "LAX": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "9290f38c5d07c2e2f4df57b1f61d4196"
            ],
            "LHR": [
              "abd90f38ced07c2e2f4df50b1f61d4194",
              "f9138c5d07c2e2f4df57b1f61d4196"
            ],
            "SJC": [
              "00920f38ce07c2e2f4df50b1f61d4194"
            ]
          },
          "random_steering": {
            "default_weight": 0.2,
            "pool_weights": {
              "9290f38c5d07c2e2f4df57b1f61d4196": 0.5,
              "de90f38ced07c2e2f4df50b1f61d4194": 0.3
            }
          },
          "region_pools": {
            "ENAM": [
              "00920f38ce07c2e2f4df50b1f61d4194"
            ],
            "WNAM": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "9290f38c5d07c2e2f4df57b1f61d4196"
            ]
          },
          "session_affinity": "cookie",
          "session_affinity_attributes": {
            "drain_duration": 100,
            "headers": [
              "x"
            ],
            "require_all_headers": true,
            "samesite": "Auto",
            "secure": "Auto",
            "zero_downtime_failover": "sticky"
          },
          "session_affinity_ttl": 1800,
          "steering_policy": "dynamic_latency",
          "ttl": 30
        },
        "priority": 0,
        "terminates": true
      }
    ],
    "session_affinity": "cookie",
    "session_affinity_attributes": {
      "drain_duration": 100,
      "headers": [
        "x"
      ],
      "require_all_headers": true,
      "samesite": "Auto",
      "secure": "Auto",
      "zero_downtime_failover": "sticky"
    },
    "session_affinity_ttl": 1800,
    "steering_policy": "dynamic_latency",
    "ttl": 30,
    "zone_name": "example.com"
  },
  "success": true
}

Returns Examples

200 example

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": {
    "id": "699d98642c564d2e855e9661899b7252",
    "adaptive_routing": {
      "failover_across_pools": true
    },
    "country_pools": {
      "GB": [
        "abd90f38ced07c2e2f4df50b1f61d4194"
      ],
      "US": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "00920f38ce07c2e2f4df50b1f61d4194"
      ]
    },
    "created_on": "2014-01-01T05:20:00.12345Z",
    "default_pools": [
      "17b5962d775c646f3f9725cbc7a53df4",
      "9290f38c5d07c2e2f4df57b1f61d4196",
      "00920f38ce07c2e2f4df50b1f61d4194"
    ],
    "description": "Load Balancer for www.example.com",
    "enabled": true,
    "fallback_pool": "fallback_pool",
    "location_strategy": {
      "mode": "resolver_ip",
      "prefer_ecs": "always"
    },
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "name": "www.example.com",
    "networks": [
      "string"
    ],
    "pool_sets": [
      {
        "disabled": true,
        "fixed_response": {
          "content_type": "application/json",
          "location": "www.example.com",
          "message_body": "Testing Hello",
          "status_code": 0
        },
        "match": {
          "default": true,
          "topology": {
            "countries": [
              "string"
            ],
            "pops": [
              "string"
            ],
            "regions": [
              "WNAM"
            ]
          }
        },
        "name": "wnam-primary",
        "overrides": {
          "fallback_pool": "9290f38c5d07c2e2f4df57b1f61d4196",
          "pool_default_weight": 0.2,
          "pool_weights": {
            "9290f38c5d07c2e2f4df57b1f61d4196": 0.5,
            "de90f38ced07c2e2f4df50b1f61d4194": 0.3
          },
          "pools": [
            "17b5962d775c646f3f9725cbc7a53df4"
          ],
          "steering_policy": "random"
        }
      }
    ],
    "pop_pools": {
      "LAX": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "9290f38c5d07c2e2f4df57b1f61d4196"
      ],
      "LHR": [
        "abd90f38ced07c2e2f4df50b1f61d4194",
        "f9138c5d07c2e2f4df57b1f61d4196"
      ],
      "SJC": [
        "00920f38ce07c2e2f4df50b1f61d4194"
      ]
    },
    "proxied": true,
    "random_steering": {
      "default_weight": 0.2,
      "pool_weights": {
        "9290f38c5d07c2e2f4df57b1f61d4196": 0.5,
        "de90f38ced07c2e2f4df50b1f61d4194": 0.3
      }
    },
    "region_pools": {
      "ENAM": [
        "00920f38ce07c2e2f4df50b1f61d4194"
      ],
      "WNAM": [
        "de90f38ced07c2e2f4df50b1f61d4194",
        "9290f38c5d07c2e2f4df57b1f61d4196"
      ]
    },
    "rules": [
      {
        "condition": "http.request.uri.path contains \"/testing\"",
        "disabled": true,
        "fixed_response": {
          "content_type": "application/json",
          "location": "www.example.com",
          "message_body": "Testing Hello",
          "status_code": 0
        },
        "name": "route the path /testing to testing datacenter.",
        "overrides": {
          "adaptive_routing": {
            "failover_across_pools": true
          },
          "country_pools": {
            "GB": [
              "abd90f38ced07c2e2f4df50b1f61d4194"
            ],
            "US": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "00920f38ce07c2e2f4df50b1f61d4194"
            ]
          },
          "default_pools": [
            "17b5962d775c646f3f9725cbc7a53df4",
            "9290f38c5d07c2e2f4df57b1f61d4196",
            "00920f38ce07c2e2f4df50b1f61d4194"
          ],
          "fallback_pool": "fallback_pool",
          "location_strategy": {
            "mode": "resolver_ip",
            "prefer_ecs": "always"
          },
          "pool_default_weight": 0.2,
          "pool_weights": {
            "9290f38c5d07c2e2f4df57b1f61d4196": 0.5,
            "de90f38ced07c2e2f4df50b1f61d4194": 0.3
          },
          "pools": [
            "17b5962d775c646f3f9725cbc7a53df4"
          ],
          "pop_pools": {
            "LAX": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "9290f38c5d07c2e2f4df57b1f61d4196"
            ],
            "LHR": [
              "abd90f38ced07c2e2f4df50b1f61d4194",
              "f9138c5d07c2e2f4df57b1f61d4196"
            ],
            "SJC": [
              "00920f38ce07c2e2f4df50b1f61d4194"
            ]
          },
          "random_steering": {
            "default_weight": 0.2,
            "pool_weights": {
              "9290f38c5d07c2e2f4df57b1f61d4196": 0.5,
              "de90f38ced07c2e2f4df50b1f61d4194": 0.3
            }
          },
          "region_pools": {
            "ENAM": [
              "00920f38ce07c2e2f4df50b1f61d4194"
            ],
            "WNAM": [
              "de90f38ced07c2e2f4df50b1f61d4194",
              "9290f38c5d07c2e2f4df57b1f61d4196"
            ]
          },
          "session_affinity": "cookie",
          "session_affinity_attributes": {
            "drain_duration": 100,
            "headers": [
              "x"
            ],
            "require_all_headers": true,
            "samesite": "Auto",
            "secure": "Auto",
            "zero_downtime_failover": "sticky"
          },
          "session_affinity_ttl": 1800,
          "steering_policy": "dynamic_latency",
          "ttl": 30
        },
        "priority": 0,
        "terminates": true
      }
    ],
    "session_affinity": "cookie",
    "session_affinity_attributes": {
      "drain_duration": 100,
      "headers": [
        "x"
      ],
      "require_all_headers": true,
      "samesite": "Auto",
      "secure": "Auto",
      "zero_downtime_failover": "sticky"
    },
    "session_affinity_ttl": 1800,
    "steering_policy": "dynamic_latency",
    "ttl": 30,
    "zone_name": "example.com"
  },
  "success": true
}