This is a preview of our upcoming API version 7, subject to change without notice.
At this time, APIv6 is the recommended API version to use.

Test Data

GET /v7/net/path-vis/{testId} (Network) Path visualization

Returns a hop-by-hop summary of the path trace data collected during path visualization. In each path visualization attempt, three attempts are made to reach the destination, and the entire path will be shown in sequence. For agent-to-agent tests, there’s a special case to consider, since the test can be bidirectional. A time frame must be specified, or the current round of data will be returned.

Consider agents A, B and C testing agent D, on a bidirectional basis. To query for the route from agent A to agent D, query with testId?direction=TO_TARGET. For the path from D to A, query with testId?direction=FROM_TARGET. To get both paths, query without the direction parameter. In all cases, the source field will reflect agent A, and the destination field will reflect agent D, but the direction field will show the direction of the trace.

Optional (Querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • window=[0-9]+[smhdw]? specifies a window of time for the result set. See Time Ranges for more information.
  • from=YYYY-mm-ddTHH:MM:SS&to=YYYY-mm-ddTHH:MM:SS specifies an explicit start (and optionally, end) for your range of data. See Time Ranges for more information.
  • aid={aid} optional and requires the user to be assigned to the target account group, specifies the account group context of the request, obtained from the /account-groups endpoint. Specifying this parameter without the user being assigned to the target account will result in an error response. See Account group context for more information
  • direction=[FROM_TARGET, TO_TARGET] Applicable only for bidirectional Agent-to-Agent tests, specifies the direction for the metrics being retrieved. If available, bidirectional data is returned by default.

Request

  • {testId} the ID of the test you wish to retrieve
  • There is no request body for this request.

Response

FieldData TypeUnitsNotes
agentIdintegern/aunique ID of agent, from /agents endpoint
agentNamestringn/adisplay name of the agent responding
countryIdstringn/aISO-3166-1 alpha-2 country code of the agent
datedateTimen/ayyyy-MM-dd hh:mm:ss, in UTC
roundIdlongsecondsepoch time (seconds) indicating the start time of the round
permalinkurln/alink to jump to this result in the front end
serverurln/atarget server, including port (if method used is TCP)
serverIpstringn/aip address of target server
sourceIpstringn/aip address of source agent
sourcePrefixstringn/aip prefix of source agent
routesarrayn/ashows 3 iterations of path trace, with each iteration specified by a pathId
routes.pathIdstringn/aunique ID of path trace
routes.hopsarrayn/aarray of hop objects indicating each step in the traceroute
routes.hops.hopintegern/aindex of hop
routes.hops.ipAddressstringn/aIP address of the hop
routes.hop.prefixstringn/aPrefix of IP address shown in CIDR
routes.hop.rdnsstringn/areverse DNS entry of IP, if available
routes.hop.networkstringn/aAutonomous System originating the prefix
routes.hop.responseTimeintegermillisecondsRTT to the hop’s IP
routes.hop.locationstringn/alocation information for the hop
routes.hop.mplsstringn/aMultiprotocol Label Switching information, if available

Example

$ curl https://api.thousandeyes.com/v7/net/path-vis/1035482.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Date: Mon, 03 Feb 2020 22:28:32 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Vary: Accept-Encoding X-Server-Name: 6znrq Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 235 X-Organization-Rate-Limit-Reset: 1580768940 Strict-Transport-Security: max-age=15724800; includeSubDomains Strict-Transport-Security: max-age=31536000 X-Content-Type-Options: nosniff

Body

{ "net": { "test": { "enabled": 1, "testId": 817, "testName": "http://www.thousandeyes.com", "type": "http-server", "interval": 900, "url": "http://www.thousandeyes.com", "modifiedDate": "2013-05-11 02:02:21", "networkMeasurements": 1, "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "modifiedBy": "API Sandbox User (noreply@thousandeyes.com)", "createdDate": "2012-06-28 19:33:12", "apiLinks": [...] }, "pathVis": [ { "server": "www.google.com:443", "serverIp": "172.217.170.68", "sourceIp": "196.40.106.237", "sourcePrefix": "196.40.96.0/20", "agentName": "Cape Town, South Africa", "countryId": "ZA", "date": "2020-02-03 22:33:01", "agentId": 25, "roundId": 1580769180, "routes": [ { "pathId": "4711301366345855606023718047703941305741293841502186803", "hops": [ { "hop": 2, "ipAddress": "41.204.206.37", "prefix": "41.204.192.0/20", "rdns": "core-router1.cpt2.host-h.net", "responseTime": 0, "location": "Cape Town, South Africa", "network": "HETZNER (Pty) Ltd (AS 37153)" }, { "hop": 3, "ipAddress": "41.66.133.1", "prefix": "41.66.128.0/18", "rdns": "41-66-133-1-2.WC-RO-HET-MEE-1AE-0-4007.africainx.net", "responseTime": 0, "location": "Cape Town, South Africa", "network": "AFRICAINX (AS 37179)" }, ... ] }, { "pathId": "4711301366345855606023718047703941305741293841502186801", "hops": [ { "hop": 2, "ipAddress": "41.204.206.37", "prefix": "41.204.192.0/20", "rdns": "core-router1.cpt2.host-h.net", "responseTime": 0, "location": "Cape Town, South Africa", "network": "HETZNER (Pty) Ltd (AS 37153)" }, { "hop": 3, "ipAddress": "41.66.133.1", "prefix": "41.66.128.0/18", "rdns": "41-66-133-1-2.WC-RO-HET-MEE-1AE-0-4007.africainx.net", "responseTime": 0, "location": "Cape Town, South Africa", "network": "AFRICAINX (AS 37179)" }, ... ] } ], "permalink": "https://app.thousandeyes.com/net/path-vis?__a=154608&testId=1035482&roundId=1580769180&serverId=2696&agentId=25" }, ... ] "pages": { "current": 1 } } }

For more information on our HTTP response status codes, see the response status codes documentation.