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 ); }); }
Array of target hostnames, IPv4, or IPv6 addresses to traceroute
Source colo names. If not specified, all colos will be used. China colos are unavailable for traceroutes
Traceroute configuration options Type of packet to send Options: icmp | tcp | udp | gre | gre+icmp
Number of packets sent at each TTL
Maximum time-to-live (TTL) value
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
Time (in seconds) to wait for a response to a probe
Response fields The target hostname, IPv4, or IPv6 address
Traceroute results from each colo Source colo information Source colo name (e.g., “SJC”)
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”
Total time of traceroute in milliseconds
Aggregated statistics from all hops about the target
Array of hops in the traceroute The time to live (TTL) for this hop
Number of packets sent with specified TTL
Number of packets where no response was received
Array of node objects representing routers at this hop Hostname of the address (may be the same as IP)
AS number associated with the node
Number of packets with a response from this node
Minimum round-trip time in milliseconds
Mean round-trip time in milliseconds
Maximum round-trip time in milliseconds
Standard deviation of the RTTs in milliseconds
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' });