Running NAT Gateway Diagnostics with the API

This topic describes how to use the Megaport API to run ping and traceroute diagnostics from a Megaport NAT Gateway (NAT Gateway). Use these diagnostics to test network connectivity and troubleshoot routing issues from the perspective of your NAT Gateway. Both diagnostics run asynchronously. You initiate the request, which returns an operation ID, then use a separate endpoint to retrieve the results when the operation completes. Before you begin, obtain a valid access token. For more information, see Creating an API Key.

The ping and traceroute endpoints are rate limited and intended for troubleshooting, not regular monitoring.

Use cases

These diagnostics help you troubleshoot network connectivity issues by testing reachability and path visibility from the NAT Gateway itself. Common use cases include:

Verifying connectivity to cloud provider endpoints before configuring BGP sessions
Testing reachability to on-premises networks connected via VXCs
Diagnosing routing issues by confirming whether the NAT Gateway can reach specific destinations
Validating network paths and measuring round-trip latency
Identifying routing hops and potential bottlenecks using traceroute
Troubleshooting asymmetric routing or path issues

Prerequisites

The NAT Gateway must have at least one active VXC attached. Running a diagnostic on an NAT Gateway with no VXCs returns a 400 Bad Request error with the message: “NAT Gateway has no VXCs attached. Ping/traceroute requires at least one active VXC.”

Ping

Use the ping diagnostic to test basic connectivity and measure round-trip latency to a destination IP address.

Initiating a ping request

To start a ping diagnostic from your NAT Gateway, send a GET request to the ping endpoint with the destination IP address and optional parameters. Endpoint

GET {baseUrl}/v3/products/nat_gateways/{productUid}/diagnostics/ping

Path Parameters

Parameter	Description
productUid	The unique identifier of the NAT Gateway from which to run the diagnostic.

Query Parameters

Parameter	Required	Description
destination_address	Yes	The target IPv4 or IPv6 address to ping. Must be an IP address literal, not a hostname. Cannot be a loopback, multicast, or any-local address. Private (RFC1918) and link-local addresses are allowed for testing connectivity to VPC/VNet resources.
source_address	No	The source IPv4 or IPv6 address for the ping. Must be the same address family as the destination address.
packet_count	No	The number of ICMP packets to send. Valid range: 1-60. Default: 3.
packet_size	No	The size of each ICMP packet in bytes. Valid range: 1-9186. Default: 56.

Example Request

GET {baseUrl}/v3/products/nat_gateways/abc12345-6789-0def-ghij-klmnopqrstuv/diagnostics/ping?destination_address=192.0.2.1&packet_count=5

Response A successful request returns an operationId that you use to retrieve the ping results.

{
    "message": "Please retrieve the result with the operation id: 12345678-90ab-cdef-1234-567890abcdef",
    "terms": "This data is subject to the Acceptable Use Policy.",
    "data": "12345678-90ab-cdef-1234-567890abcdef"
}

Retrieving ping results

After initiating a ping request, use the diagnostics operation endpoint to retrieve the results. The operation runs asynchronously, so you might need to poll until the results are ready. Endpoint

GET {baseUrl}/v3/products/nat_gateways/{productUid}/diagnostics/routes/operation?operationId={operationId}

Path Parameters

Parameter	Description
productUid	The unique identifier of the NAT Gateway.

Query Parameters

Parameter	Required	Description
operationId	Yes	The operation ID returned from the ping initiation request.

Response Codes

Code	Description
200	The ping operation has completed. Results are included in the response.
202	The ping operation is still pending or running. Poll again after a short delay.

Example Request

GET {baseUrl}/v3/products/nat_gateways/abc12345-6789-0def-ghij-klmnopqrstuv/diagnostics/routes/operation?operationId=12345678-90ab-cdef-1234-567890abcdef

Response

{
    "message": "Diagnostic result retrieved successfully",
    "data": {
        "rawOutput": "PING 192.0.2.1 (192.0.2.1) 56(84) bytes of data...",
        "statistics": {
            "packetsTransmitted": 5,
            "packetsReceived": 5,
            "packetLossPct": 0.0,
            "rttMinMs": 0.987,
            "rttAvgMs": 1.234,
            "rttMaxMs": 1.567,
            "rttMdevMs": 0.123,
            "totalTimeMs": 4012.0,
            "duplicates": 0,
            "errors": 0
        }
    }
}

The response includes rawOutput containing the raw ping command output, and statistics with detailed packet and timing metrics. If the ping fails, an error field contains the error message.

Traceroute

Use the traceroute diagnostic to discover the network path between your NAT Gateway and a destination IP address, showing each hop along the route.

Initiating a traceroute request

To start a traceroute diagnostic from your NAT Gateway, send a GET request to the traceroute endpoint with the destination IP address. Endpoint

GET {baseUrl}/v3/products/nat_gateways/{productUid}/diagnostics/traceroute

Path Parameters

Parameter	Description
productUid	The unique identifier of the NAT Gateway from which to run the diagnostic.

Query Parameters

Parameter	Required	Description
destination_address	Yes	The target IPv4 or IPv6 address to trace. Must be an IP address literal, not a hostname. Cannot be a loopback, multicast, or any-local address. Private (RFC1918) and link-local addresses are allowed for testing connectivity to VPC/VNet resources.
source_address	No	The source IPv4 or IPv6 address for the traceroute. Must be the same address family as the destination address.

Example Request

GET {baseUrl}/v3/products/nat_gateways/abc12345-6789-0def-ghij-klmnopqrstuv/diagnostics/traceroute?destination_address=192.0.2.1

Response A successful request returns an operationId that you use to retrieve the traceroute results.

{
    "message": "Please retrieve the result with the operation id: 12345678-90ab-cdef-1234-567890abcdef",
    "terms": "This data is subject to the Acceptable Use Policy.",
    "data": "12345678-90ab-cdef-1234-567890abcdef"
}

Retrieving traceroute results

After initiating a traceroute request, use the diagnostics operation endpoint to retrieve the results. The operation runs asynchronously, so you might need to poll until the results are ready. Endpoint

GET {baseUrl}/v3/products/nat_gateways/{productUid}/diagnostics/routes/operation?operationId={operationId}

Path Parameters

Parameter	Description
productUid	The unique identifier of the NAT Gateway.

Query Parameters

Parameter	Required	Description
operationId	Yes	The operation ID returned from the traceroute initiation request.

Response Codes

Code	Description
200	The traceroute operation has completed. Results are included in the response.
202	The traceroute operation is still pending or running. Poll again after a short delay.

Example Request

GET {baseUrl}/v3/products/nat_gateways/abc12345-6789-0def-ghij-klmnopqrstuv/diagnostics/routes/operation?operationId=12345678-90ab-cdef-1234-567890abcdef

Response

{
    "message": "Diagnostic result retrieved successfully",
    "data": {
        "hops": [
            {
                "hop": "1",
                "probes": [
                    { "host": "198.51.100.1", "rttMs": 0.543 },
                    { "host": "198.51.100.1", "rttMs": 0.487 },
                    { "host": "198.51.100.1", "rttMs": 0.512 }
                ]
            },
            {
                "hop": "2",
                "probes": [
                    { "host": "203.0.113.254", "rttMs": 1.234 },
                    { "host": "203.0.113.254", "rttMs": 1.156 },
                    { "host": "203.0.113.254", "rttMs": 1.298 }
                ]
            },
            {
                "hop": "3",
                "probes": [
                    { "host": "192.0.2.1", "rttMs": 2.876 },
                    { "host": "192.0.2.1", "rttMs": 2.654 },
                    { "host": "192.0.2.1", "rttMs": 2.789 }
                ]
            }
        ],
        "rawOutput": "traceroute to 192.0.2.1, 30 hops max, 60 byte packets..."
    }
}

The response includes an array of hops, where each hop contains a hop number and an array of probes. Each probe shows the responding host (IP address or hostname) and the rttMs (round-trip time in milliseconds). If a probe receives no response, host may be null. The rawOutput field contains the raw traceroute command output.

Megaport Documentation

Running NAT Gateway Diagnostics with the API

Use cases

Prerequisites

Ping

Initiating a ping request

Retrieving ping results

Traceroute

Initiating a traceroute request

Retrieving traceroute results

Helpful references

​Use cases

​Prerequisites

​Ping

​Initiating a ping request

​Retrieving ping results

​Traceroute

​Initiating a traceroute request

​Retrieving traceroute results

​Helpful references

Use cases

Prerequisites

Ping

Initiating a ping request

Retrieving ping results

Traceroute

Initiating a traceroute request

Retrieving traceroute results

Helpful references