Traceroute
Trace the network path from this server to a public host. Hops stream in as they are discovered rather than arriving as one block at the end.
Overview
A traceroute shows the routers between two points and how long each one takes to answer. This one runs from the server, so it maps the path from here to your target, not from you to it. That makes it useful for answering "is the problem on my side or theirs". Run it alongside a local traceroute and compare where the paths diverge.
Three protocols are available. ICMP is the default and usually the most informative. UDP is the classic Unix behaviour. TCP is worth trying when a firewall drops the other two but permits ordinary connections.
A hop that shows no response is normal. Plenty of routers are configured not to answer while still forwarding traffic perfectly. Timeouts in the middle of an otherwise complete trace mean nothing; timeouts all the way to the end mean something.
Web interface
Enter a hostname or IP address, pick a protocol, a hop limit (15, 20, 30 or 50) and a per-hop timeout (2, 3, 5 or 10 seconds). Hops appear one at a time as the trace progresses. The Stop button abandons a trace that is going nowhere.
API
/check/traceroute
JSON request body. Any method other than POST returns HTTP 405.
| Name | Type | Default | Description |
|---|---|---|---|
| target | string | required | Hostname, IPv4 or IPv6 address. Must be public. |
| protocol | enum | icmp |
icmp, udp or tcp. |
| max_hops | integer | 20 |
1 to 50. Values outside the range are rejected, not clamped. |
| timeout | integer | 3 |
Seconds to wait per hop, 1 to 30. |
$ curl -sN -X POST https://api.troubleshooting.tools/v1/check/traceroute \
-H "Content-Type: application/json" \
-d '{"target": "example.com", "protocol": "icmp", "max_hops": 20, "timeout": 3}'Use curl -N. Without it curl buffers the response and you lose the streaming behaviour that is
the whole reason this endpoint works the way it does.
Streaming format
The response is newline-delimited JSON
(application/x-ndjson), not a single JSON document. One object per line, emitted as the trace
progresses. Parsing the body with a plain JSON parser will fail.
Four record types, distinguished by their type field.
{"type":"start","target":"example.com","max_hops":20,"timeout":3,"protocol":"icmp","target_type":"hostname"}
{"type":"hop","hop":1,"timeout":false,"ip":"192.0.2.1","hostname":"gateway.example","times":[1.2,1.1,1.3],"avg_time":1.2}
{"type":"hop","hop":2,"timeout":true}
{"type":"hop","hop":3,"timeout":false,"ip":"198.51.100.7","times":[8.4,9.1],"partial_timeout":true,"timeout_count":1}
{"type":"complete","target":"example.com","total_hops":12}| Type | Meaning |
|---|---|
| start | First line, always. Echoes the resolved parameters and whether the target was read as ipv4, ipv6 or a hostname. |
| hop | One router. See the fields below. |
| raw | A line the parser did not recognise, passed through verbatim as line. Rare; display it or ignore it, but do not treat it as a hop. |
| complete | Last line on success, with total_hops. |
| error | Emitted instead of complete when the trace itself failed. Carries message. |
Hop fields
| Field | Type | Description |
|---|---|---|
| hop | integer | Distance from the server, starting at 1. |
| timeout | boolean | true when the hop answered nothing at all. Then no other field is present. |
| ip | string | Address that answered. Absent on a full timeout. |
| hostname | string | Reverse DNS name, only when one resolved. |
| times | array | Round-trip times in milliseconds, one per probe that answered. |
| avg_time | number | Mean of times, two decimals. |
| partial_timeout | boolean | Present when some probes answered and some did not. |
| timeout_count | integer | How many probes went unanswered at this hop. |
Note the difference between timeout: true (nothing answered) and partial_timeout
(some probes answered). The second is far more interesting: it usually means rate limiting on the router
rather than a broken path.
The trace stops early when the target is reached, so total_hops is normally well below
max_hops.
Errors
Validation failures return HTTP 400 with a plain
{"success": false, "error": "..."} object, before streaming begins. A failure during the
trace arrives as an error record in the stream instead, at HTTP 200, because by then the status
line has already been sent.
| Message | Cause |
|---|---|
Target parameter is required. | No target. |
Invalid target. Must be a valid IP address or hostname. | Unparseable target. |
Cannot trace private or reserved IP addresses. | Target is not public. |
Max hops must be between 1 and 50. | Out of range. |
Timeout must be between 1 and 30 seconds. | Out of range. |
Protocol must be icmp, udp, or tcp. | Unknown protocol. |
Method not allowed. | HTTP 405, not a POST. |
Limits
50 hops maximum, 30 seconds maximum per hop. A trace with generous settings can run for minutes, so keep the connection open and read as you go.
The edge allows 50 requests per second per IP, burst 100, HTTP 429 over the limit. Traces are
expensive; run them when you need one, not on a timer.
Privacy
Targets appear in server logs for operational purposes and are not sold or shared. The trace originates from this service, so intermediate routers and the target see its address rather than yours.