> ## Documentation Index > Fetch the complete documentation index at: https://docs.megaport.com/llms.txt > Use this file to discover all available pages before exploring further. # Running NAT Gateway Diagnostics with the API > This help topic describes how to use the Megaport API to run ping and traceroute diagnostics from a Megaport NAT Gateway. 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](/api/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** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} 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** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} 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. ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "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** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} 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** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} GET {baseUrl}/v3/products/nat_gateways/abc12345-6789-0def-ghij-klmnopqrstuv/diagnostics/routes/operation?operationId=12345678-90ab-cdef-1234-567890abcdef ``` **Response** ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "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** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} 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** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} 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. ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "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** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} 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** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} GET {baseUrl}/v3/products/nat_gateways/abc12345-6789-0def-ghij-klmnopqrstuv/diagnostics/routes/operation?operationId=12345678-90ab-cdef-1234-567890abcdef ``` **Response** ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "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. ## Helpful references * [NAT Gateway Features](/nat/nat-gateway-features) * [Creating a NAT Gateway](/nat/creating-nat-gateway) * [Creating a NAT Gateway VXC](/nat/nat-gateway-vxc)