Diagnostics

Run network diagnostics from Cloudflare’s edge

The Diagnostics API allows you to run network diagnostic tools like traceroutes from Cloudflare’s global network to troubleshoot connectivity issues.

Traceroutes

Run traceroute

Run traceroutes from Cloudflare colos to one or more targets.

for await (const traceroute of client.diagnostics.traceroutes.create({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  targets: ['203.0.113.1', 'cloudflare.com'],
  colos: ['SJC', 'LAX'],
  options: {
    packet_type: 'icmp',
    packets_per_ttl: 3,
    max_ttl: 30,
    wait_time: 5
  }
})) {
  console.log(traceroute.target);
  traceroute.colos?.forEach(colo => {
    console.log(colo.colo?.name, colo.traceroute_time_ms);
  });
}

account_id · string · required

Account identifier

targets · string[] · required

Array of target hostnames, IPv4, or IPv6 addresses to traceroute

colos · string[]

Source colo names. If not specified, all colos will be used. China colos are unavailable for traceroutes

options · object

Traceroute configuration options

Show child attributes

packet_type · string

Type of packet to send

Options: icmp | tcp | udp | gre | gre+icmp

packets_per_ttl · number

Number of packets sent at each TTL

max_ttl · number

Maximum time-to-live (TTL) value

port · number

For UDP and TCP, specifies the destination port. For ICMP, specifies the initial ICMP sequence value. Default value 0 will choose the best value for each protocol

wait_time · number

Time (in seconds) to wait for a response to a probe

Response fields

target · string

The target hostname, IPv4, or IPv6 address

colos · object[]

Traceroute results from each colo

Show child attributes

colo · object

Source colo information

Show child attributes

name · string

Source colo name (e.g., “SJC”)

city · string

Source colo city

error · string

Errors resulting from collecting traceroute data

Possible values:

• "" (empty string for no error)
• “Could not gather traceroute data: Code 1”
• “Could not gather traceroute data: Code 2”
• “Could not gather traceroute data: Code 3”
• “Could not gather traceroute data: Code 4”

traceroute_time_ms · number

Total time of traceroute in milliseconds

target_summary · unknown

Aggregated statistics from all hops about the target

hops · object[]

Array of hops in the traceroute

Show child attributes

packets_ttl · number

The time to live (TTL) for this hop

packets_sent · number

Number of packets sent with specified TTL

packets_lost · number

Number of packets where no response was received

nodes · object[]

Array of node objects representing routers at this hop

Show child attributes

ip · string

IP address of the node

name · string

Hostname of the address (may be the same as IP)

asn · string

AS number associated with the node

packet_count · number

Number of packets with a response from this node

min_rtt_ms · number

Minimum round-trip time in milliseconds

mean_rtt_ms · number

Mean round-trip time in milliseconds

max_rtt_ms · number

Maximum round-trip time in milliseconds

std_dev_rtt_ms · number

Standard deviation of the RTTs in milliseconds

labels · string[]

Additional annotations (e.g., which traceroute type for GRE+ICMP)

Example response

[
  {
    "target": "cloudflare.com",
    "colos": [
      {
        "colo": {
          "name": "SJC",
          "city": "San Jose"
        },
        "traceroute_time_ms": 45.2,
        "hops": [
          {
            "packets_ttl": 1,
            "packets_sent": 3,
            "packets_lost": 0,
            "nodes": [
              {
                "ip": "192.0.2.1",
                "name": "router1.example.com",
                "asn": "13335",
                "packet_count": 3,
                "min_rtt_ms": 1.2,
                "mean_rtt_ms": 1.5,
                "max_rtt_ms": 2.1,
                "std_dev_rtt_ms": 0.4
              }
            ]
          }
        ]
      }
    ]
  }
]

Endpoint health checks

The Diagnostics API also provides endpoint health check functionality through the endpointHealthchecks sub-resource for monitoring specific endpoints.

const healthchecks = await client.diagnostics.endpointHealthchecks.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353'
});