# Traceroutes ## Traceroute `diagnostics.traceroutes.create(TracerouteCreateParams**kwargs) -> SyncSinglePage[Traceroute]` **post** `/accounts/{account_id}/diagnostics/traceroute` Run traceroutes from Cloudflare colos. ### Parameters - `account_id: str` Identifier - `targets: SequenceNotStr[str]` - `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. - `packet_type: Optional[Literal["icmp", "tcp", "udp", 2 more]]` Type of packet sent. - `"icmp"` - `"tcp"` - `"udp"` - `"gre"` - `"gre+icmp"` - `packets_per_ttl: Optional[int]` Number of packets sent at each TTL. - `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. - `wait_time: Optional[int]` Set the time (in seconds) to wait for a response to a probe. ### Returns - `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. - `""` - `"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. ### Example ```python 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) ``` #### Response ```json { "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" } ] } ``` ## Domain Types ### Traceroute - `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. - `""` - `"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.