Cloudflare API | Load Balancers › Monitors

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.

CheckRegion = "WNAM" | "ENAM" | "WEU" | 11 more...

WNAM: Western North America, ENAM: Eastern North America, WEU: Western Europe, EEU: Eastern Europe, NSAM: Northern South America, SSAM: Southern South America, OC: Oceania, ME: Middle East, NAF: North Africa, SAF: South Africa, SAS: Southern Asia, SEAS: South East Asia, NEAS: North East Asia, ALL_REGIONS: all regions (ENTERPRISE customers only).

DefaultPools = string

A pool ID.

FilterOptions = { disable, healthy }

Filter options for a particular resource type (pool or origin). Use null to reset.

Header = { Host }

The request header is used to pass additional information with an HTTP request. Currently supported header is 'Host'.

Host = string

LoadBalancer = { id, adaptive_routing, country_pools, 20 more... }

LoadShedding = { default_percent, default_policy, session_percent, 1 more... }

Configures load shedding policies and percentages for the pool.

LocationStrategy = { mode, prefer_ecs }

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

NotificationFilter = { origin, pool }

Filter pool and origin health notifications by resource type or health status. Use null to reset.

Origin = { address, disabled_at, enabled, 4 more... }

OriginSteering = { policy }

Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity.

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 pool's outstanding requests.
steering_policy="least_connections": Use pool weights to scale each pool's open connections.

Rules = { condition, disabled, fixed_response, 4 more... }

A rule object containing conditions and overrides for this load balancer to evaluate.

SessionAffinity = "none" | "cookie" | "ip_cookie" | 1 more...

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 client's 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.

SessionAffinityAttributes = { drain_duration, headers, require_all_headers, 3 more... }

Configures attributes for session affinity.

SteeringPolicy = "off" | "geo" | "random" | 5 more...

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 pool's 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 pool's 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".

Load Balancers

Monitors

load_balancers.monitors

Methods

Create Monitor -> Envelope<

Monitor

post/accounts/{account_id}/load_balancers/monitors

Create a configured monitor.

Security

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

Example: Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

Accepted Permissions (at least one required)

Load Balancing: Monitors and Pools Write

path Parameters

account_id: string

(maxLength: 32)

Identifier

Body parameters

allow_insecure: boolean

Optional

Do not validate the certificate when monitor use HTTPS. This parameter is currently only valid for HTTP and HTTPS monitors.

consecutive_down: number

Optional

To be marked unhealthy the monitored origin must fail this healthcheck N consecutive times.

consecutive_up: number

Optional

To be marked healthy the monitored origin must pass this healthcheck N consecutive times.

description: string

Optional

Object description.

expected_body: string

Optional

A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy. This parameter is only valid for HTTP and HTTPS monitors.

expected_codes: string

Optional

The expected HTTP response code or code range of the health check. This parameter is only valid for HTTP and HTTPS monitors.

follow_redirects: boolean

Optional

Follow redirects if returned by the origin. This parameter is only valid for HTTP and HTTPS monitors.

header: Record<string, Array<string>>

Optional

The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden. This parameter is only valid for HTTP and HTTPS monitors.

interval: number

Optional

(default: 60)

The interval between each health check. Shorter intervals may improve failover time, but will increase load on the origins as we check from multiple locations.

method: string

Optional

(default: "GET")

The method to use for the health check. This defaults to 'GET' for HTTP/HTTPS based checks and 'connection_established' for TCP based health checks.

path: string

Optional

(default: "/")

The endpoint path you want to conduct a health check against. This parameter is only valid for HTTP and HTTPS monitors.

port: number

Optional

The port number to connect to for the health check. Required for TCP, UDP, and SMTP checks. HTTP and HTTPS checks should only define the port when using a non-standard port (HTTP: default 80, HTTPS: default 443).

probe_zone: string

Optional

Assign this monitor to emulate the specified zone while probing. This parameter is only valid for HTTP and HTTPS monitors.

retries: number

Optional

(default: 2)

The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately.

timeout: number

Optional

(default: 5)

The timeout (in seconds) before marking the health check as failed.

type: "http" | "https" | "tcp" | 3 more...

Optional

(default: "http")

The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'.

Response fields

errors: Array<

ResponseInfo

messages: Array<

ResponseInfo

result:

Monitor

success: true

Whether the API call was successful

Request example

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/load_balancers/monitors \
    -H 'Content-Type: application/json' \
    -H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
    -H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
    -d '{
      "allow_insecure": true,
      "description": "Login page monitor",
      "expected_body": "alive",
      "expected_codes": "2xx",
      "follow_redirects": true,
      "header": {
        "Host": [
          "example.com"
        ],
        "X-App-ID": [
          "abc123"
        ]
      },
      "method": "GET",
      "path": "/health",
      "probe_zone": "example.com",
      "type": "http"
    }'

200Example

{
  "errors": [
    {
      "code": 1000,
      "message": "message"
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message"
    }
  ],
  "result": {
    "id": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "allow_insecure": true,
    "consecutive_down": 0,
    "consecutive_up": 0,
    "description": "Login page monitor",
    "expected_body": "alive",
    "expected_codes": "2xx",
    "follow_redirects": true,
    "header": {
      "Host": [
        "example.com"
      ],
      "X-App-ID": [
        "abc123"
      ]
    },
    "interval": 0,
    "method": "GET",
    "path": "/health",
    "port": 0,
    "probe_zone": "example.com",
    "retries": 0,
    "timeout": 0,
    "type": "http"
  },
  "success": true
}

Delete Monitor -> Envelope<{ id }>

delete/accounts/{account_id}/load_balancers/monitors/{monitor_id}

Delete a configured monitor.

Patch Monitor -> Envelope<

Monitor

patch/accounts/{account_id}/load_balancers/monitors/{monitor_id}

Apply changes to an existing monitor, overwriting the supplied properties.

Monitor Details -> Envelope<

Monitor

get/accounts/{account_id}/load_balancers/monitors/{monitor_id}

List a single configured monitor for an account.

List Monitors -> SinglePage<

Monitor

get/accounts/{account_id}/load_balancers/monitors

List configured monitors for an account.

Update Monitor -> Envelope<

Monitor

put/accounts/{account_id}/load_balancers/monitors/{monitor_id}

Modify a configured monitor.

Domain types

Monitor = { id, allow_insecure, consecutive_down, 16 more... }

Load Balancers Monitors

Previews

load_balancers.monitors.previews

Methods

Preview Monitor -> Envelope<{ pools, preview_id }>

post/accounts/{account_id}/load_balancers/monitors/{monitor_id}/preview

Preview pools using the specified monitor with provided monitor details. The returned preview_id can be used in the preview endpoint to retrieve the results.

Load Balancers Monitors

References

load_balancers.monitors.references

Methods

List Monitor References -> SinglePage<{ reference_type, resource_id, resource_name, 1 more... }>

get/accounts/{account_id}/load_balancers/monitors/{monitor_id}/references

Get the list of resources that reference the provided monitor.

Load Balancers

Pools

load_balancers.pools

Methods

Patch Pools -> SinglePage<

Pool

patch/accounts/{account_id}/load_balancers/pools

Apply changes to a number of existing pools, overwriting the supplied properties. Pools are ordered by ascending name. Returns the list of affected pools. Supports the standard pagination query parameters, either limit/offset or per_page/page.

Create Pool -> Envelope<

Pool

post/accounts/{account_id}/load_balancers/pools

Create a new pool.

Delete Pool -> Envelope<{ id }>

delete/accounts/{account_id}/load_balancers/pools/{pool_id}

Delete a configured pool.

Patch Pool -> Envelope<

Pool

patch/accounts/{account_id}/load_balancers/pools/{pool_id}

Apply changes to an existing pool, overwriting the supplied properties.

Pool Details -> Envelope<

Pool

get/accounts/{account_id}/load_balancers/pools/{pool_id}

Fetch a single configured pool.

List Pools -> SinglePage<

Pool

get/accounts/{account_id}/load_balancers/pools

List configured pools.

Update Pool -> Envelope<

Pool

put/accounts/{account_id}/load_balancers/pools/{pool_id}

Modify a configured pool.

Domain types

Pool = { id, check_regions, created_on, 15 more... }

Load Balancers Pools

Health

load_balancers.pools.health

Methods

Preview Pool -> Envelope<{ pools, preview_id }>

post/accounts/{account_id}/load_balancers/pools/{pool_id}/preview

Preview pool health using provided monitor details. The returned preview_id can be used in the preview endpoint to retrieve the results.

Pool Health Details -> Envelope<{ pool_id, pop_health }>

get/accounts/{account_id}/load_balancers/pools/{pool_id}/health

Fetch the latest pool health status for a single pool.

Load Balancers Pools

References

load_balancers.pools.references

Methods

List Pool References -> SinglePage<{ reference_type, resource_id, resource_name, 1 more... }>

get/accounts/{account_id}/load_balancers/pools/{pool_id}/references

Get the list of resources that reference the provided pool.

Load Balancers

Previews

load_balancers.previews

Methods

Preview Result -> Envelope<Record<string, { healthy, origins }>>

get/accounts/{account_id}/load_balancers/preview/{preview_id}

Get the result of a previous preview operation using the provided preview_id.

Load Balancers

Regions

load_balancers.regions

Methods

Get Region -> Envelope<unknown | string>

get/accounts/{account_id}/load_balancers/regions/{region_id}

Get a single region mapping.

List Regions -> Envelope<unknown | string>

get/accounts/{account_id}/load_balancers/regions

List all region mappings.

Load Balancers

Searches

load_balancers.searches

Methods

Search Resources -> V4PagePagination<{ resources }>

get/accounts/{account_id}/load_balancers/search

Search for Load Balancing resources.