Traceroute

client.Diagnostics.Traceroutes.New(ctx, params) (*SinglePage[Traceroute], error)

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 TracerouteNewParams

AccountID param.Field[string]

Path param: Identifier

maxLength32

Targets param.Field[[]string]

Body param

maxLength10

Colos param.Field[[]string]optional

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

Options param.Field[TracerouteNewParamsOptions]optional

Body param

MaxTTL int64optional

Max TTL.

maximum64

minimum0

PacketType TracerouteNewParamsOptionsPacketTypeoptional

Type of packet sent.

One of the following:

const TracerouteNewParamsOptionsPacketTypeIcmp TracerouteNewParamsOptionsPacketType = "icmp"

const TracerouteNewParamsOptionsPacketTypeTCP TracerouteNewParamsOptionsPacketType = "tcp"

const TracerouteNewParamsOptionsPacketTypeUdp TracerouteNewParamsOptionsPacketType = "udp"

const TracerouteNewParamsOptionsPacketTypeGRE TracerouteNewParamsOptionsPacketType = "gre"

const TracerouteNewParamsOptionsPacketTypeGREIcmp TracerouteNewParamsOptionsPacketType = "gre+icmp"

PacketsPerTTL int64optional

Number of packets sent at each TTL.

maximum10

minimum0

Port int64optional

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

WaitTime int64optional

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

maximum5

minimum1

ReturnsExpand Collapse

type Traceroute struct{…}

Colos []TracerouteColooptional

Colo TracerouteColosColooptional

City stringoptional

Source colo city.

Name stringoptional

Source colo name.

Error TracerouteColosErroroptional

Errors resulting from collecting traceroute from colo to target.

One of the following:

const TracerouteColosErrorEmpty TracerouteColosError = ""

const TracerouteColosErrorCouldNotGatherTracerouteDataCode1 TracerouteColosError = "Could not gather traceroute data: Code 1"

const TracerouteColosErrorCouldNotGatherTracerouteDataCode2 TracerouteColosError = "Could not gather traceroute data: Code 2"

const TracerouteColosErrorCouldNotGatherTracerouteDataCode3 TracerouteColosError = "Could not gather traceroute data: Code 3"

const TracerouteColosErrorCouldNotGatherTracerouteDataCode4 TracerouteColosError = "Could not gather traceroute data: Code 4"

Hops []TracerouteColosHopoptional

Nodes []TracerouteColosHopsNodeoptional

An array of node objects.

ASN stringoptional

AS number associated with the node object.

IP stringoptional

IP address of the node.

Labels []stringoptional

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.

MaxRTTMs float64optional

Maximum RTT in ms.

MeanRTTMs float64optional

Mean RTT in ms.

MinRTTMs float64optional

Minimum RTT in ms.

Name stringoptional

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

PacketCount int64optional

Number of packets with a response from this node.

StdDevRTTMs float64optional

Standard deviation of the RTTs in ms.

PacketsLost int64optional

Number of packets where no response was received.

PacketsSent int64optional

Number of packets sent with specified TTL.

PacketsTTL int64optional

The time to live (TTL).

TargetSummary unknownoptional

Aggregated statistics from all hops about the target.

TracerouteTimeMs int64optional

Total time of traceroute in ms.

Target stringoptional

The target hostname, IPv6, or IPv6 address.

Traceroute

package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/diagnostics"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  page, err := client.Diagnostics.Traceroutes.New(context.TODO(), diagnostics.TracerouteNewParams{
    AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
    Targets: cloudflare.F([]string{"203.0.113.1", "cloudflare.com"}),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}

{
  "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"
    }
  ]
}