Healthchecks

Monitor origin server health and availability

The Healthchecks API allows you to configure and manage health checks for your origin servers. Health checks monitor your origins and can detect when they become unhealthy.

Create health check

Create a new health check for a zone.

const healthcheck = await client.healthchecks.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  address: 'www.example.com',
  name: 'server-1',
  check_regions: ['WNAM', 'ENAM'],
  type: 'HTTPS',
  http_config: {
    method: 'GET',
    path: '/health',
    expected_codes: ['200'],
    follow_redirects: false,
    allow_insecure: false,
    header: {
      'Host': ['www.example.com']
    }
  },
  interval: 60,
  retries: 2,
  timeout: 5,
  consecutive_fails: 3,
  consecutive_successes: 2
});

zone_id · string · required

Zone identifier

address · string · required

The hostname or IP address of the origin server to run health checks on

name · string · required

A short name to identify the health check. Only alphanumeric characters, hyphens, and underscores are allowed

type · string

The protocol to use for the health check

Options: HTTP | HTTPS | TCP

check_regions · string[] | null

A list of regions from which to run health checks. Null means Cloudflare will pick a default region

Options: WNAM, ENAM, WEU, EEU, NSAM, SSAM, OC, ME, NAF, SAF, IN, SEAS, NEAS, ALL_REGIONS (Business and Enterprise only)

description · string

A human-readable description of the health check

interval · number

The interval between each health check in seconds. Shorter intervals may give quicker notifications but will increase load on the origin

retries · number

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

timeout · number

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

consecutive_fails · number

The number of consecutive fails required from a health check before changing the health to unhealthy

consecutive_successes · number

The number of consecutive successes required from a health check before changing the health to healthy

suspended · boolean

If suspended, no health checks are sent to the origin

http_config · object | null

Parameters specific to an HTTP or HTTPS health check

Show child attributes

method · string

The HTTP method to use for the health check

Options: GET | HEAD

path · string

The endpoint path to health check against

expected_codes · string[] | null

The expected HTTP response codes (e.g., “200”) or code ranges (e.g., “2xx”)

expected_body · string

A case-insensitive sub-string to look for in the response body. If not found, the origin will be marked as unhealthy

follow_redirects · boolean

Follow redirects if the origin returns a 3xx status code

allow_insecure · boolean

Do not validate the certificate when the health check uses HTTPS

header · object | null

The HTTP request headers to send in the health check. It is recommended to set a Host header. The User-Agent header cannot be overridden

port · number

Port number to connect to (defaults to 80 for HTTP or 443 for HTTPS)

tcp_config · object | null

Parameters specific to TCP health check

Show child attributes

method · string

The TCP connection method to use

Options: connection_established

port · number

Port number to connect to for the health check (defaults to 80)

Response fields

id · string

Health check identifier

address · string

The hostname or IP address of the origin server

name · string

Health check name

status · string

The current status of the origin server according to the health check

Options: unknown | healthy | unhealthy | suspended

failure_reason · string

The current failure reason if status is unhealthy

type · string

The protocol used for the health check

check_regions · string[] | null

Regions from which health checks are run

created_on · string

When the health check was created

modified_on · string

When the health check was last modified

interval · number

Interval between health checks in seconds

retries · number

Number of retries before marking as unhealthy

timeout · number

Timeout in seconds

consecutive_fails · number

Consecutive fails required to mark as unhealthy

consecutive_successes · number

Consecutive successes required to mark as healthy

suspended · boolean

Whether health checks are suspended

http_config · object | null

HTTP/HTTPS health check configuration

tcp_config · object | null

TCP health check configuration

List health checks

List all configured health checks for a zone.

for await (const healthcheck of client.healthchecks.list({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353'
})) {
  console.log(healthcheck.name, healthcheck.status);
}

Get health check

Retrieve a single configured health check.

const healthcheck = await client.healthchecks.get(
  '023e105f4ecef8ad9ca31a8372d0c353',
  { zone_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

Update health check

Update all properties of a configured health check.

const healthcheck = await client.healthchecks.update(
  '023e105f4ecef8ad9ca31a8372d0c353',
  {
    zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
    address: 'www.example.com',
    name: 'server-1-updated',
    interval: 90
  }
);

Edit health check

Patch specific properties of a configured health check.

const healthcheck = await client.healthchecks.edit(
  '023e105f4ecef8ad9ca31a8372d0c353',
  {
    zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
    address: 'www.example.com',
    name: 'server-1',
    suspended: true
  }
);

Delete health check

Delete a health check.

const result = await client.healthchecks.delete(
  '023e105f4ecef8ad9ca31a8372d0c353',
  { zone_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

id · string

ID of the deleted health check