Skip to main content
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 checkOptions: HTTP | HTTPS | TCP
​
check_regions
string[] | null
A list of regions from which to run health checks. Null means Cloudflare will pick a default regionOptions: 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
​
tcp_config
object | null
Parameters specific to TCP health check

​
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 checkOptions: 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

Build docs developers (and LLMs) love

Get started for freeTalk to us