Running MCR and NAT Gateway Diagnostics with the API
This topic describes how to use the Megaport API to run ping and traceroute diagnostics from a Megaport Cloud Router (MCR). Use these diagnostics to test network connectivity and troubleshoot routing issues from the perspective of your MCR. Use the same procedures to run diagnostics from a 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. Results are available for approximately 10 minutes after the operation completes.
Before you begin, obtain a valid access token. For more information, see Creating an API Key.
Note
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 MCR 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 MCR 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 MCR must have at least one active VXC attached. Running a diagnostic on an MCR with no VXCs returns a 400 Bad Request error with the message: “MCR 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 MCR, send a GET request to the ping endpoint with the destination IP address and optional parameters.
Endpoint
Path Parameters
| Parameter | Description |
|---|---|
productUid |
The unique identifier of the MCR 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}/v2/product/mcr2/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": "Ping request initiated",
"data": {
"operationId": "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
Path Parameters
| Parameter | Description |
|---|---|
productUid |
The unique identifier of the MCR. |
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}/v2/product/mcr2/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 MCR and a destination IP address, showing each hop along the route.
Initiating a traceroute request
To start a traceroute diagnostic from your MCR, send a GET request to the traceroute endpoint with the destination IP address.
Endpoint
Path Parameters
| Parameter | Description |
|---|---|
productUid |
The unique identifier of the MCR 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}/v2/product/mcr2/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": "Traceroute request initiated",
"data": {
"operationId": "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
Path Parameters
| Parameter | Description |
|---|---|
productUid |
The unique identifier of the MCR. |
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}/v2/product/mcr2/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.