List Load Balancers

GET

https://api.cloudflare.com/client/v4/zones/{identifier}/load_balancers

Last modified:2022-12-16 13:48:33

List configured load balancers.

Request

Path Params

identifier

string

required

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200List Load Balancers response

application/json

Body

result

required

Any of

allOf {2}

array[object (load-balancer) {21}]

allOf {2}

One of

array[object (load-balancer) {21}]

object

adaptive_routing

object

adaptive_routing

optional

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.

country_pools

object

country_pools

optional

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.

Example:

{"GB":["abd90f38ced07c2e2f4df50b1f61d4194"],"US":["de90f38ced07c2e2f4df50b1f61d4194","00920f38ce07c2e2f4df50b1f61d4194"]}

created_on

string <date-time>

timestamp

read-onlyoptional

Example:

2014-01-01T05:20:00.12345Z

default_pools

array[string]

default_pools

optional

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.

Example:

["17b5962d775c646f3f9725cbc7a53df4","9290f38c5d07c2e2f4df57b1f61d4196","00920f38ce07c2e2f4df50b1f61d4194"]

description

string

load-balancer_components-schemas-description

optional

Object description.

Example:

Load Balancer for www.example.com

enabled

boolean

load-balancer_components-schemas-enabled

optional

Whether to enable (the default) this load balancer.

Default:

true

Example:

true

fallback_pool

optional

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

load-balancer_components-schemas-identifier

optional

Example:

699d98642c564d2e855e9661899b7252

location_strategy

object

location_strategy

optional

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

modified_on

string <date-time>

timestamp

read-onlyoptional

Example:

2014-01-01T05:20:00.12345Z

name

string

load-balancer_components-schemas-name

optional

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

Example:

www.example.com

pop_pools

object

pop_pools

optional

(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.

Example:

{"LAX":["de90f38ced07c2e2f4df50b1f61d4194","9290f38c5d07c2e2f4df57b1f61d4196"],"LHR":["abd90f38ced07c2e2f4df50b1f61d4194","f9138c5d07c2e2f4df57b1f61d4196"],"SJC":["00920f38ce07c2e2f4df50b1f61d4194"]}

proxied

boolean

schemas-proxied

optional

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

Default:

false

Example:

true

random_steering

object

random_steering

optional

Configures pool weights for random steering. When steering_policy is 'random', a random pool is selected with probability proportional to these pool weights.

region_pools

object

region_pools

optional

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.

Example:

{"ENAM":["00920f38ce07c2e2f4df50b1f61d4194"],"WNAM":["de90f38ced07c2e2f4df50b1f61d4194","9290f38c5d07c2e2f4df57b1f61d4196"]}

rules

array [object {7}]

load-balancer_components-schemas-rules

optional

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

session_affinity

enum<string>

session_affinity

optional

The session_affinity specifies the type of session affinity the load balancer should use unless specified as "none" or ""(default). The supported types are "cookie" and "ip_cookie". "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 client’s ip address.

Allowed values:

nonecookieip_cookie""

Default:

Example:

session_affinity_attributes

object

session_affinity_attributes

optional

Configures cookie attributes for session affinity cookie.

session_affinity_ttl

number

session_affinity_ttl

optional

Time, in seconds, until this load balancer's session affinity cookie expires after being created. This parameter is ignored unless a supported session affinity policy is set. The current default of 23 hours will be used unless session_affinity_ttl is explicitly set. The accepted range of values is between [1800, 604800]. Once the expiry time has been reached, subsequent requests may get sent to a different origin server.

Example:

5000

steering_policy

enum<string>

steering_policy

optional

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.

"": Will map to "geo" if you use region_pools/country_pools/pop_pools otherwise "off".

Allowed values:

offgeorandomdynamic_latencyproximity""

Default:

Example:

dynamic_latency

ttl

number

schemas-ttl

optional

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.

Example:

errors

array [object {2}]

messages

required

Example:

[]

code

integer

required

>= 1000

message

string

required

messages

array [object {2}]

messages

required

Example:

[]

code

integer

required

>= 1000

message

string

required

success

enum<boolean>

required

Whether the API call was successful

Allowed value:

true

Example:

true

result_info

object

result_info

optional

count

number

optional

Total number of results for the requested service

Example:

page

number

optional

Current page within paginated list of results

Example:

per_page

number

optional

Number of results per page of results

Example:

total_count

number

optional

Total results available without any search parameters

Example:

2000

Example

{
    "errors": [],
    "messages": [],
    "result": [
        {
            "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": null,
            "id": "699d98642c564d2e855e9661899b7252",
            "location_strategy": {
                "mode": "resolver_ip",
                "prefer_ecs": "always"
            },
            "modified_on": "2014-01-01T05:20:00.12345Z",
            "name": "www.example.com",
            "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": false,
                    "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": null,
                        "location_strategy": {
                            "mode": "resolver_ip",
                            "prefer_ecs": "always"
                        },
                        "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,
                            "samesite": "Auto",
                            "secure": "Auto",
                            "zero_downtime_failover": "sticky"
                        },
                        "session_affinity_ttl": 5000,
                        "steering_policy": "dynamic_latency",
                        "ttl": 30
                    },
                    "priority": 0,
                    "terminates": false
                }
            ],
            "session_affinity": "cookie",
            "session_affinity_attributes": {
                "drain_duration": 100,
                "samesite": "Auto",
                "secure": "Auto",
                "zero_downtime_failover": "sticky"
            },
            "session_affinity_ttl": 5000,
            "steering_policy": "dynamic_latency",
            "ttl": 30
        }
    ],
    "success": true,
    "result_info": {
        "count": 1,
        "page": 1,
        "per_page": 20,
        "total_count": 2000
    }
}

🟢200List Load Balancers response failure

Modified at 2022-12-16 13:48:33

Update Load Balancer

Create Load Balancer