Traceroute Beta
Trace the path from our checking server to a host, on demand. Useful when a site is reachable for you but not for us, or the other way round.
Needs an X-API-Key header whose owner has access to uptime monitoring in the app. The call counts once against your daily quota. See Monitoring API: getting started for authentication, rate limits and errors.
Read-only: anything other than GET returns 405.
Query parameters
| Name | Type | Description |
|---|---|---|
host required | string | The host to trace, such as example.com or an IP address. |
hops optional | integer | How far to go, 1 to 30. Default 15. |
The host is checked the same way a monitor's target is, so private, local and internal addresses are refused with 400.
A traceroute is slow and noisy, so it's limited to three a minute per key. Over that you get 429 with Retry-After: 60, and it still costs one request against your daily quota.
Request
Response
- {
- "host": "example.com",
- "address": "203.0.113.10",
- "hops": [
- { "hop": 1, "address": "10.0.0.1", "ms": 1, "timedOut": false },
- { "hop": 2, "address": null, "ms": null, "timedOut": true },
- { "hop": 3, "address": "203.0.113.10", "ms": 14, "timedOut": false }
- ],
- "usage": { "used": 56, "dailyLimit": 100, "tier": "free" }
- }
Response fields
| Field | Type | Description |
|---|---|---|
host | string | The host you asked for. |
address | string | The address it resolved to, which is what was traced. |
hops[].hop | integer | The hop number, counting out from the checking server. |
hops[].address | string | null | The address that answered, or null when nothing did. |
hops[].ms | integer | null | The round trip to that hop. |
hops[].timedOut | boolean | true when the hop didn't answer. Plenty of routers drop these on purpose, so a gap in the middle is normal. |
Errors
| Status | When |
|---|---|
400 | No host, or a host that is private, local or otherwise not allowed. |
401 | The API key is missing or invalid. |
403 | The key's owner doesn't have access to uptime monitoring, or the key isn't linked to a workspace. |
405 | Anything other than GET. |
429 | More than three traceroutes a minute for this key, or your daily quota. Read Retry-After, in seconds. |
503 | The checking server can't run a traceroute: A traceroute isn't available from this checking server. A container often can't, and that is reported plainly rather than as a failure. |
500, 503 | Something went wrong, or the API is temporarily unavailable. Try again. |
Errors are JSON: { "error": "message" }. See Monitoring API errors.
Related
- Get an analysis: a traceroute recorded during an outage
- Diagnostics: how an outage is investigated
- Ping check: the simpler reachability question