Skip to content
Cloudflare API
Start here
API Reference
Diagnostics
Traceroutes

Traceroute

diagnostics.traceroutes.create(TracerouteCreateParams**kwargs) -> SyncSinglePage[Traceroute]
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
account_id: str

Identifier

maxLength32
targets: SequenceNotStr[str]
maxLength10
colos: Optional[SequenceNotStr[str]]

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

options: Optional[Options]
max_ttl: Optional[int]

Max TTL.

maximum64
minimum0
packet_type: Optional[Literal["icmp", "tcp", "udp", 2 more]]

Type of packet sent.

One of the following:
"icmp"
"tcp"
"udp"
"gre"
"gre+icmp"
packets_per_ttl: Optional[int]

Number of packets sent at each TTL.

maximum10
minimum0
port: Optional[int]

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: Optional[int]

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

maximum5
minimum1
ReturnsExpand Collapse
class Traceroute: …
colos: Optional[List[Colo]]
colo: Optional[ColoColo]
city: Optional[str]

Source colo city.

name: Optional[str]

Source colo name.

error: Optional[Literal["", "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: Optional[List[ColoHop]]
nodes: Optional[List[ColoHopNode]]

An array of node objects.

asn: Optional[str]

AS number associated with the node object.

ip: Optional[str]

IP address of the node.

labels: Optional[List[str]]

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: Optional[float]

Maximum RTT in ms.

mean_rtt_ms: Optional[float]

Mean RTT in ms.

min_rtt_ms: Optional[float]

Minimum RTT in ms.

name: Optional[str]

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

packet_count: Optional[int]

Number of packets with a response from this node.

std_dev_rtt_ms: Optional[float]

Standard deviation of the RTTs in ms.

packets_lost: Optional[int]

Number of packets where no response was received.

packets_sent: Optional[int]

Number of packets sent with specified TTL.

packets_ttl: Optional[int]

The time to live (TTL).

target_summary: Optional[object]

Aggregated statistics from all hops about the target.

traceroute_time_ms: Optional[int]

Total time of traceroute in ms.

target: Optional[str]

The target hostname, IPv6, or IPv6 address.

Traceroute

import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
page = client.diagnostics.traceroutes.create(
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
    targets=["203.0.113.1", "cloudflare.com"],
)
page = page.result[0]
print(page.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"
    }
  ]
}