Skip to content
Cloudflare API
Start here
API Reference
Diagnostics
Traceroutes

Traceroute

client.diagnostics.traceroutes.create(TracerouteCreateParams { account_id, targets, colos, options } params, RequestOptionsoptions?): SinglePage<Traceroute { colos, target } >
POST/accounts/{account_id}/diagnostics/traceroute

Run traceroutes from Cloudflare colos.

Security
API Token

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

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY
API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194
Accepted Permissions (at least one required)
Magic Transit Write
ParametersExpand Collapse
params: TracerouteCreateParams { account_id, targets, colos, options }
account_id: string

Path param: Identifier

maxLength32
targets: Array<string>

Body param

maxLength10
colos?: Array<string>

Body param: If no source colo names specified, all colos will be used. China colos are unavailable for traceroutes.

options?: Options

Body param

max_ttl?: number

Max TTL.

maximum64
minimum0
packet_type?: "icmp" | "tcp" | "udp" | 2 more

Type of packet sent.

One of the following:
"icmp"
"tcp"
"udp"
"gre"
"gre+icmp"
packets_per_ttl?: number

Number of packets sent at each TTL.

maximum10
minimum0
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 to use for each protocol.

maximum65535
minimum0
wait_time?: number

Set the time (in seconds) to wait for a response to a probe.

maximum5
minimum1
ReturnsExpand Collapse
Traceroute { colos, target }
colos?: Array<Colo>
colo?: Colo { city, name }
city?: string

Source colo city.

name?: string

Source colo name.

error?: "" | "Could not gather traceroute data: Code 1" | "Could not gather traceroute data: Code 2" | 2 more

Errors resulting from collecting traceroute from colo to target.

One of the following:
""
"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"
hops?: Array<Hop>
nodes?: Array<Node>

An array of node objects.

asn?: string

AS number associated with the node object.

ip?: string

IP address of the node.

labels?: Array<string>

Field appears if there is an additional annotation printed when the probe returns. Field also appears when running a GRE+ICMP traceroute to denote which traceroute a node comes from.

max_rtt_ms?: number

Maximum RTT in ms.

mean_rtt_ms?: number

Mean RTT in ms.

min_rtt_ms?: number

Minimum RTT in ms.

name?: string

Host name of the address, this may be the same as the IP address.

packet_count?: number

Number of packets with a response from this node.

std_dev_rtt_ms?: number

Standard deviation of the RTTs in ms.

packets_lost?: number

Number of packets where no response was received.

packets_sent?: number

Number of packets sent with specified TTL.

packets_ttl?: number

The time to live (TTL).

target_summary?: unknown

Aggregated statistics from all hops about the target.

traceroute_time_ms?: number

Total time of traceroute in ms.

target?: string

The target hostname, IPv6, or IPv6 address.

Traceroute

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const traceroute of client.diagnostics.traceroutes.create({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  targets: ['203.0.113.1', 'cloudflare.com'],
})) {
  console.log(traceroute.colos);
}
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": [
    {
      "colos": [
        {
          "colo": {
            "city": "Denver, CO, US",
            "name": "den01"
          },
          "error": "",
          "hops": [
            {
              "nodes": [
                {
                  "asn": "AS13335",
                  "ip": "1.1.1.1",
                  "labels": [
                    "string"
                  ],
                  "max_rtt_ms": 0,
                  "mean_rtt_ms": 0,
                  "min_rtt_ms": 0,
                  "name": "one.one.one.one",
                  "packet_count": 3,
                  "std_dev_rtt_ms": 0
                }
              ],
              "packets_lost": 0,
              "packets_sent": 0,
              "packets_ttl": 0
            }
          ],
          "target_summary": {
            "asn": "",
            "ip": "1.1.1.1",
            "max_latency_ms": 0.034,
            "mean_latency_ms": 0.021,
            "min_latency_ms": 0.014,
            "name": "1.1.1.1",
            "packet_count": 3,
            "std_dev_latency_ms": 0.011269427669584647
          },
          "traceroute_time_ms": 0
        }
      ],
      "target": "1.1.1.1"
    }
  ]
}
Returns Examples
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": [
    {
      "colos": [
        {
          "colo": {
            "city": "Denver, CO, US",
            "name": "den01"
          },
          "error": "",
          "hops": [
            {
              "nodes": [
                {
                  "asn": "AS13335",
                  "ip": "1.1.1.1",
                  "labels": [
                    "string"
                  ],
                  "max_rtt_ms": 0,
                  "mean_rtt_ms": 0,
                  "min_rtt_ms": 0,
                  "name": "one.one.one.one",
                  "packet_count": 3,
                  "std_dev_rtt_ms": 0
                }
              ],
              "packets_lost": 0,
              "packets_sent": 0,
              "packets_ttl": 0
            }
          ],
          "target_summary": {
            "asn": "",
            "ip": "1.1.1.1",
            "max_latency_ms": 0.034,
            "mean_latency_ms": 0.021,
            "min_latency_ms": 0.014,
            "name": "1.1.1.1",
            "packet_count": 3,
            "std_dev_latency_ms": 0.011269427669584647
          },
          "traceroute_time_ms": 0
        }
      ],
      "target": "1.1.1.1"
    }
  ]
}