Test Data

GET /v6/net/metrics/{testId} (Network) End-to-End metrics

Returns network metrics (loss, latency, jitter, and bandwidth) from each agent, for each roundId in the requested window. A time frame must be specified, or the current round of data will be returned.

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, BIDIRECTIONAL] Applicable only for bidirectional Agent-to-Agent tests, specifies the direction for the metrics being retrieved. In the case of bidirectional data, the aggregated data is returned, otherwise unidirectional data will be returned. In the case of unidirectional tests queried with an invalid direction parameter, an error response will be thrown.

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
serverIpstringn/aip of target server
serverurln/atarget server, including port (if method used is TCP)
lossfloatpercentage% of packets not reaching destination
minLatencyintegermillisecondsminimum RTT for packets sent to destination
maxLatencyintegermillisecondsmaxmimum RTT for packets sent to destination
avgLatencyfloatmillisecondsaverage RTT for packets sent to destination
jitterfloatmillisecondsstandard deviation of latency

Example

$ curl https://api.thousandeyes.com/v6/net/metrics/817.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Thu, 08 Nov 2013 07:32:48 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 229 X-Organization-Rate-Limit-Reset: 1493231280 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

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": [...] }, "metrics": [ { "agentName": "Hong Kong", "countryId": "HK", "date": "2013-11-13 02:33:05", "serverIp": "50.18.127.223", "loss": 0, "permalink": "https://app.thousandeyes.com/net/metrics?__a=75&testId=817&roundId=1384309800&serverId=71&agentId=12", "agentId": 12, "server": "www.thousandeyes.com:80", "roundId": 1384309800 "minLatency": 167, "avgLatency": 167.04, "maxLatency": 168, "jitter": 0.076808 }, ... ] }, "pages": { "current": 1 } }

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

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

Returns a summary of the path visualization data collected from each agent to the destination. In each path visualization attempt, three attempts are made to reach the destination. Each set of data is summarized, based on response time, number of hops, and response time to the target. A time frame must be specified, or the current round of data will be returned.

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, BIDIRECTIONAL] Applicable only for bidirectional Agent-to-Agent tests, specifies the direction for the metrics being retrieved. In the case of bidirectional data, each direction must be queried independently in order to retrieve the information.

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
endpointsarrayn/ashows all iterations of path trace, with each iteration specified by a pathId
endpoints.numberOfHopsintegern/anumber of hops for path trace to destination
endpoints.ipAddressstringn/adestination
endpoints.pathIdstringn/aunique ID of path trace
endpoints.responseTimeintegern/aRTT of the path trace to the destination

Example

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

HTTP/1.1 200 OK Server: nginx Date: Wed, 26 Apr 2017 18:31:00 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 234 X-Organization-Rate-Limit-Reset: 1493231520 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

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": [ { "agentName": "Hong Kong", "countryId": "HK", "date": "2013-11-13 02:47:46", "server": "www.thousandeyes.com:80", "serverIp": "50.18.127.223", "sourceIp": "123.103.248.179", "sourcePrefix": "123.103.248.0/24", "permalink": "https://app.thousandeyes.com/net/path-vis?__a=75&testId=817&roundId=1384310700&serverId=71&agentId=12", "agentId": 12, "endpoints": [ { "numberOfHops": 16, "ipAddress": "50.18.127.223", "responseTime": 167, "pathId": "6537222451557817610263112715264" }, { "numberOfHops": 16, "ipAddress": "50.18.127.223", "responseTime": 167, "pathId": "6537222451557817610263112715265" }, { "numberOfHops": 16, "ipAddress": "50.18.127.223", "responseTime": 167, "pathId": "6537222451557817610263112715266" } ], "roundId": 1384310700 }, ... ] }, "pages": { "current": 1 } }

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

GET /v6/net/path-vis/{testId}/{agentId}/{roundId} (Network) Detailed path trace

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. A roundId must be specified. For agent-to-agent tests, there’s a special case to consider, since the test can be bidirectional.

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/{agentA}/roundId?direction=TO_TARGET. For the path from D to A, qeury with testId/{agentA}/roundId?direction=FROM_TARGET. To get both paths, query the same endpoint with direction=BIDIRECTIONAL. 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
  • 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

Request

Required parameters:

  • {testId} the ID of the test you wish to retrieve
  • {agentId} the ID of the agent from which you wish to obtain data
  • {roundId} the round ID for which you wish to obtain data. Equals the beginning of the testing round, in epoch time format.
  • There is no request body for this request.

Optional request parameter:

  • direction=[TO_TARGET, FROM_TARGET, BIDIRECTIONAL] indicates the direction of a path trace in the case of a bidirectional agent-to-agent test. This parameter is only applied in the case of bidirectional agent-to-agent tests. Specify the value on the querystring. Without specifying the field, the test will use the default direction for the test, which is chosen based on the following list:

    • BIDIRECTIONAL (shows both TO_TARGET and FROM_TARGET directions)
    • TO_TARGET (shows path from source agent to target agent)
    • FROM_TARGET (shows path from target agent to source agent)

Response

  • Each route should start with a hop of 1
  • Where a hop number is missing from response data, this is an indication that a star (*) response was returned in the path trace attempt for that hop.
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
directionstringn/adirection of the trace results. Can be [TO_TARGET, FROM_TARGET]. This field is only shown in the case of Agent to Agent tests.
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

Example

$ curl https://api.thousandeyes.com/v6/net/path-vis/817/146/1383887700.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Thu, 07 Nov 2013 07:32:48 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 229 X-Organization-Rate-Limit-Reset: 1493233740 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

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": [ { "agentName": "San Jose, CA", "countryId": "US", "date": "2013-11-08 05:15:12", "server": "www.thousandeyes.com:80", "serverIp": "50.18.127.223", "sourceIp": "198.89.98.67", "sourcePrefix": "198.89.96.0/19", "routes": [ { "pathId": "6535224890535563750337719341569", "hops": [ { "hop": 4, "ipAddress": "154.54.84.53", "prefix": "154.48.0.0/12", "rdns": "te0-2-0-4.ccr21.sjc01.atlas.cogentco.com", "network": "Cogent Communications (AS 174)", "responseTime": 2, "location": "San Francisco Area" }, { "hop": 5, "ipAddress": "154.54.6.106", "prefix": "154.48.0.0/12", "rdns": "be2000.ccr21.sjc03.atlas.cogentco.com", "network": "Cogent Communications (AS 174)", "responseTime": 1, "location": "San Francisco Area" }, { "hop": 6, "ipAddress": "154.54.13.126", "prefix": "154.48.0.0/12", "rdns": "verio.sjc03.atlas.cogentco.com", "network": "Cogent Communications (AS 174)", "responseTime": 1, "location": "San Francisco Area" }, { "hop": 7, "ipAddress": "129.250.4.118", "prefix": "129.250.0.0/16", "rdns": "ae-4.r06.plalca01.us.bb.gin.ntt.net", "network": "NTT America, Inc. (AS 2914)", "responseTime": 2, "location": "San Francisco Area" }, { "hop": 8, "ipAddress": "140.174.21.182", "prefix": "140.174.0.0/16", "rdns": "ae-1.amazon.plalca01.us.bb.gin.ntt.net", "network": "NTT America, Inc. (AS 2914)", "responseTime": 2, "location": "San Francisco Area" }, { "hop": 9, "ipAddress": "205.251.229.46", "prefix": "205.251.228.0/22", "network": "Amazon.com, Inc. (AS 16509)", "responseTime": 4, "location": "Seattle Area" }, { "hop": 10, "ipAddress": "72.21.222.19", "prefix": "72.21.220.0/22", "network": "Amazon.com, Inc. (AS 16509)", "responseTime": 3, "location": "Seattle Area" }, { "hop": 11, "ipAddress": "216.182.236.109", "prefix": "216.182.232.0/21", "network": "Amazon.com, Inc. (AS 14618)", "responseTime": 4, "location": "Seattle Area" }, { "hop": 16, "ipAddress": "50.18.127.223", "prefix": "50.18.64.0/18", "rdns": "ec2-50-18-127-223.us-west-1.compute.amazonaws.com", "network": "Amazon.com, Inc. (AS 16509)", "responseTime": 4, "location": "San Francisco Area" } ] }, { "pathId": "6535224890535563750337719341568", "hops": [...] }, { "pathId": "6535224890535563750337719341570", "hops": [...] } ], "permalink": "https://app.thousandeyes.com/net/path-vis?__a=75&testId=817&roundId=1383887700&serverId=71&agentId=146", "agentId": 146, "roundId": 1383887700 } ] } }

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

GET /v6/net/bgp-metrics/{testId} (Network) BGP metrics

Returns a list of BGP monitors observing the target prefix of the destination, and returns the prefix, AS Number, and reachability, path updates, and path changes for the target network.

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

Request

  • {testId} the ID of the test for which BGP data is of interest
  • There is no request body for this request.

Response

  • Note: Monitors are not agents. Not all agents are in a network being monitored, and not all monitors have associated agents.
FieldData TypeUnitsNotes
monitorIdintegern/aunique ID of monitor, from /bgp-monitors endpoint
monitorNamestringn/adisplay name used for the monitor
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
prefixIdintegern/ainternally tracked prefix ID
prefixstringn/aprefix being tracked
updatesintegern/anumber of updates tracked against this prefix by this monitor
pathChangesintegern/anumber of path changes tracked against this prefix by this monitor
reachabilityfloatpercentagepercentage reachability

Example

$ curl https://api.thousandeyes.com/v6/net/bgp-metrics/817.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Thu, 07 Nov 2013 07:32:48 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 228 X-Organization-Rate-Limit-Reset: 1493233860 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

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": [...] }, "bgpMetrics": [ { "countryId": "CA", "date": "2013-11-13 03:45:00", "prefixId": 215, "prefix": "50.16.0.0/14", "monitorName": "Vancouver, Canada - Bell Canada (AS 6539)", "monitorId": 45, "reachability": 100, "roundId": 1384314300, "updates": 0, "permalink": "https://app.thousandeyes.com/net/bgp-vis?__a=75&testId=817&roundId=1384314300&prefixId=215", "pathChanges": 0 }, ... ] }, "pages": { "current": 1 } }

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

GET /v6/net/bgp-routes/{testId}/{prefixId}/{roundId} (Network) BGP route information

Returns a sequenced list of networks transited for a specific network prefix. Shows a list of monitors assigned to the test, and the paths transited to reach the destination. This is analogous to showing the ASPath information from a BGP Routing Information Base (rib) dump.

Optional (Querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats 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

Request

  • {testId} the ID of the test for which BGP data is of interest
  • {prefixId} the ID of the prefix in question. Obtain prefixId from the /net/bgp-metrics/{testId} endpoint
  • {roundId} the round for which you wish to obtain data. Obtain roundId from the /net/bgp-metrics/{testId} endpoint
  • There is no request body for this request.

Response

  • Note: Monitors are not agents. Not all agents are in a network being monitored, and not all monitors have associated agents.
FieldData TypeUnitsNotes
monitorIdintegern/aunique ID of monitor, from /bgp-monitors endpoint
monitorNamestringn/adisplay name used for the monitor
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
prefixIdintegern/ainternally tracked prefix ID
prefixstringn/aprefix being tracked
activebooleann/a1 for active, 0 for inactive
hopsarrayn/asee below for individual hop fields
hops.asnintegern/aASN of transit autonomous system
hops.asNamestringn/aname of autonomous system

Example

$ curl https://api.thousandeyes.com/v6/net/bgp-routes/1137/27/1413225900.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Thu, 07 Nov 2013 07:32:48 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 228 X-Organization-Rate-Limit-Reset: 1493233860 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

{ "net": { "test": { "enabled": 1, "savedEvent": 0, "testId": 1137, "testName": "Agents up?", "type": "network", "interval": 300, "server": "www.google.com:80", "protocol": "TCP", "networkMeasurements": 1, "mtuMeasurements": 0, "bandwidthMeasurements": 0, "bgpMeasurements": 1, "alertsEnabled": 0, "liveShare": 0, "createdDate": "2013-03-06 18:07:51", "modifiedDate": "2014-10-13 18:17:53", "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "modifiedBy": "API Sandbox User (noreply@thousandeyes.com)", "apiLinks": [...] }, "bgpRoutes": [ { "countryId": "CA", "date": "2014-10-13 18:45:00", "monitorId": 15, "monitorName": "Calgary, Canada - Telus (AS 852)", "prefixId": 27, "prefix": "74.125.0.0/16", "active": 1, "roundId": 1413225900, "hops": [ { "asn": 852, "asName": "Telus Advanced Communications" }, { "asn": 15169, "asName": "Google Inc." } ], "permalink": "https://app.thousandeyes.com/net/bgp-vis?__a=11&testId=1137&roundId=1413225900&agentId=null" }, ... ] } }

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

GET /v6/web/http-server/{testId} (Web) HTTP server

Returns response code, response and fetch times, as well as component-level (DNS, Connect, Wait, Receive and Fetch) timing for the load of an object over HTTP.

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
  • headers=1 optional, will output request and response header information in output. Example below assumes headers=1 was specified as an optional parameter.

Request

  • {testId} the ID of the HTTP Server (or page load) 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
serverIpstringn/aIP address of destination server
responseCodeintegern/acode of HTTP response
numRedirectsintegern/anumber of redirects
redirectTimeintegermillisecondscumulative redirect timing
dnsTimeintegermillisecondstime required to resolve DNS
sslTimeintegermillisecondstime to negotiate SSL/TLS
connectTimeintegermillisecondstime required to establish a TCP connection to the server
waitTimeintegermillisecondstime elapsed between completion of request and first byte of response
receiveTimeintegermillisecondselapsed time between first and last byte of response
wireSizefloatbytessize of content, in bytes
responseTimeintegermillisecondstime to first byte
throughputintegerbytes per secondwireSize divided by receiveTime
totalTimeintegermillisecondsresponse time + receive time
requestHeadersstringn/acrlf-delimited list of request headers in header: value format
reponseHeadersstringn/acrlf-delimited list of response headers in header: value format
errorTypestringn/atype of error encountered; corresponds to phase of connection
errorDetailsstringn/aerror details, if an error were encountered

Example

$ curl https://api.thousandeyes.com/v6/web/http-server/817.json?headers=1 \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Wed, 09 Aug 2017 07:45:48 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 228 X-Organization-Rate-Limit-Reset: 1502264900 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

{ "web": { "test": { "alertsEnabled": 1, "apiLinks": [...], "bandwidthMeasurements": 0, "bgpMeasurements": 1, "contentRegex": "", "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "createdDate": "2012-06-28 19:33:12", "enabled": 1, "followRedirects": 1, "httpTargetTime": 1000, "httpTimeLimit": 5, "interval": 900, "liveShare": 0, "modifiedBy": "Deleted User", "modifiedDate": "2016-09-20 23:01:55", "mtuMeasurements": 1, "networkMeasurements": 1, "savedEvent": 0, "sslVersion": "Auto", "sslVersionId": 0, "testId": 817, "testName": "http://www.thousandeyes.com", "type": "http-server", "url": "http://www.thousandeyes.com", "useNtlm": 0, "verifyCertificate": 1 }, "httpServer": [ { "agentId": 12, "agentName": "San Po Kong, Hong Kong", "connectTime": 4, "countryId": "HK", "date": "2017-08-09 07:45:37", "dnsTime": 0, "errorType": "None", "numRedirects": 1, "permalink": "https://app.thousandeyes.com/web/http-server?__a=75&testId=817&roundId=1502264700&agentId=12", "receiveTime": 75, "redirectTime": 16, "responseCode": 200, "responseTime": 92, "roundId": 1502264700, "serverIp": "52.222.238.124", "sslTime": 43, "throughput": 1038237, "totalTime": 167, "waitTime": 45, "wireSize": 78198, "requestHeaders": "GET / HTTP/1.1\r\nHost: www.thousandeyes.com\r\nUser-Agent: curl/7.51.0-DEV\r\nAccept: */*\r\nX-ThousandEyes-Agent: yes\r\n", "responseHeaders": "HTTP/1.1 200 OK\r\nContent-Type: text/html;charset=ISO-8859-1\r\nTransfer-Encoding: chunked\r\nConnection: keep-alive\r\nDate: Wed, 09 Aug 2017 07:45:37 GMT\r\nServer: Apache\r\nContent-Language: en-US\r\nX-Frame-Options: sameorigin\r\nCache-Control: max-age=600, must-revalidate\r\nStrict-Transport-Security: max-age=31536000\r\nVary: Accept-Encoding\r\nAge: 572\r\nX-Cache: Hit from cloudfront\r\nVia: 1.1 f2e2a7eca4778c8776461616fad77017.cloudfront.net (CloudFront)\r\nX-Amz-Cf-Id: olqsnihH0wLtBa2oPuH0rlQik0aKP6wnC16sEFF4jAHeC9gTsBCKxQ==\r\n" }, ... ] }, "pages": { "current": 1 } }

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

GET /v6/web/page-load/{testId} (Web) Page load

Returns response time, total size, count of objects and errors, and provides page and DOM load times for a web page.

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

Request

  • {testId} the ID of the page load test you for wish to retrieve data
  • 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
responseTimeintegermillisecondstime to first byte
totalSizeintegerbytessum of wire size of all objects on page
numObjectsintegern/anumber of objects found on the page
numErrorsintegern/anumber of objects which encountered errors during download
domLoadTimeintegermillisecondstime to interaction
pageLoadTimeintegermillisecondstime to completely load page

Example

$ curl https://api.thousandeyes.com/v6/web/page-load/818.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Thu, 08 Nov 2013 07:32:48 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 228 X-Organization-Rate-Limit-Reset: 1493288220 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

{ "web": { "test": { "enabled": 1, "savedEvent": 0, "liveShare": 0, "testId": 818, "testName": "http://www.google.com", "type": "page-load", "interval": 900, "httpTimeLimit": 5, "pageLoadTimeLimit": 30, "httpInterval": 900, "url": "http://www.google.com", "modifiedDate": "2013-05-22 03:53:15", "networkMeasurements": 1, "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "modifiedBy": "API Sandbox User (noreply@thousandeyes.com)", "createdDate": "2012-06-28 19:34:33", "apiLinks": [...] }, "pageLoad": [ { "agentName": "Hong Kong", "countryId": "HK", "date": "2013-11-13 04:33:09", "permalink": "https://app.thousandeyes.com/web/page-load?__a=75&testId=818&roundId=1384317000&agentId=12", "agentId": 12, "roundId": 1384317000, "responseTime": 36, "totalSize": 7089, "numObjects": 4, "numErrors": 0, "domLoadTime": 105, "pageLoadTime": 132 }, ... ] }, "pages": { "current": 1 } }

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

GET /v6/web/page-load/{testId}/{agentId}/{roundId} (Web) Page load component detail

Returns HAR (http archive) information, including component list and timing for elements loaded in a Page Load test. This is analogous to what is shown in the waterfall view for a Page Load test, with an agent selected. Includes response data, dns, connect, ssl, send, wait and receive times for each component loaded in a page.

Note: this endpoint is only available in v5 or higher of the ThousandEyes API

Optional (Querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats 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

Request

  • {testId} the ID of the Page Load test you for wish to retrieve data
  • {agentId} the ID of the agent for which you wish to retrieve data
  • {roundId} the ID of the round for which you wish to retrieve data
  • There is no request body for this request.

Response

Response data is returned according to the HAR specification.

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
responseTimeintegermillisecondstime to first byte
totalSizeintegerbytessum of wire size of all objects on page
numObjectsintegern/anumber of objects found on the page
numErrorsintegern/anumber of objects which encountered errors during download
domLoadTimeintegermillisecondstime to interaction
pageLoadTimeintegermillisecondstime to completely load page
harhar*n/asee HAR specification for details.

Example

$ curl https://api.thousandeyes.com/v6/web/page-load/818/12/1493288100.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Thu, 08 Nov 2013 07:32:48 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 228 X-Organization-Rate-Limit-Reset: 1493288220 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

{ "web": { "test": { "alertsEnabled": 0, "apiLinks": [...] "bandwidthMeasurements": 0, "bgpMeasurements": 1, "contentRegex": "", "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "createdDate": "2012-06-28 19:34:33", "enabled": 1, "followRedirects": 1, "httpInterval": 900, "httpTargetTime": 1000, "httpTimeLimit": 5, "includeHeaders": 0, "interval": 900, "liveShare": 0, "modifiedBy": "API Sandbox User (noreply@thousandeyes.com)", "modifiedDate": "2016-09-20 23:01:55", "mtuMeasurements": 1, "networkMeasurements": 1, "pageLoadTargetTime": 2, "pageLoadTimeLimit": 30, "savedEvent": 0, "sslVersion": "Auto", "sslVersionId": 0, "testId": 818, "testName": "http://www.google.com", "type": "page-load", "url": "http://www.google.com", "useNtlm": 0, "verifyCertificate": 1 }, "pageLoad": [ { "agentId": 12, "agentName": "San Po Kong, Hong Kong", "countryId": "HK", "date": "2017-04-27 10:15:58", "domLoadTime": 3079, "har": { "log": { "creator": { "name": "ThousandEyes DB Exporter" }, "entries": [ { "pageref": "page_0", "request": { "method": "GET", "queryString": [], "url": "http://www.google.com/" }, "response": { "bodySize": 262, "content": { "mimeType": "text/html", "size": 262 }, "headersSize": 247, "redirectURL": "", "status": 302, "statusText": "FOUND" }, "serverIPAddress": "216.58.199.4", "startedDateTime": "2017-04-27T17:15:58.001Z", "time": 506, "timings": { "blocked": 0, "connect": 217, "dns": 0, "receive": 2, "send": 0, "ssl": -1, "wait": 287 } }, ... ], "pages": [ { "id": "page_0", "pageTimings": { "onContentLoad": 3079, "onLoad": 5338 }, "responseCode": 0, "startedDateTime": "2017-04-27T17:15:58.000Z", "title": "" } ], "version": "1.2" } }, "numErrors": 0, "numObjects": 14, "pageLoadTime": 5338, "permalink": "https://app.thousandeyes.com/web/page-load?__a=75&testId=818&roundId=1493288100&agentId=12", "responseTime": 504, "roundId": 1493288100, "totalSize": 376585 } ] } }

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

GET /v6/web/transactions/{testId} (Web) Transactions

Returns transaction time, counts of steps and errors from each agent selected to run a transaction. A time frame must be specified, or the current round of data will be returned.

For step-level detail, see Detailed Transactions

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

Request

  • {testId} the ID of the transaction 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
componentErrorsintegern/anumber of components which did not successfully load
stepsCompletedintegern/anumber of steps successfully completed
totalStepsintegern/atotal number of steps in the transaction script
transactionTimeintegermillisecondselapsed execution time between beginning of start step and end of end step in the transaction

Example

$ curl https://api.thousandeyes.com/v6/web/transactions/825.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Thu, 08 Nov 2013 07:32:48 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 228 X-Organization-Rate-Limit-Reset: 1493288220 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

{ "web": { "test": { "enabled": 1, "testId": 825, "testName": "http://thousandeyes.com", "type": "transactions", "interval": 900, "url": "http://thousandeyes.com", "totalSteps": 1, "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "createdDate": "2012-06-29 00:39:35", "apiLinks": [...] }, "transaction": [ { "agentName": "Hong Kong", "countryId": "HK", "date": "2013-11-13 04:30:15", "stepsCompleted": 1, "totalSteps": 1, "componentErrors": 0, "permalink": "https://app.thousandeyes.com/web/transactions?__a=75&testId=825&roundId=1384317000&agentId=12", "agentId": 12, "transactionTime": 4096, "roundId": 1384317000 }, ... ] }, "pages": { "current": 1 } }

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

GET /v6/web/transactions/{testId}/{agentId}/{roundId} (Web) Transaction detail

Returns transaction time, duration and error counts of steps and pages transited during a execution of a transaction. An agent and roundId is required, since results from a single round of transaction execution will be returned.

Optional (Querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats 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

Request

  • {testId} the ID of the transaction you wish to retrieve
  • {agentId} the ID of the agent for which you wish to obtain transaction data
  • {roundId} the roundID for which data is being requested
  • 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
stepsCompletedintegern/anumber of steps successfully completed
totalStepsintegern/atotal number of steps in the transaction script
transactionTimeintegermillisecondselapsed execution time between beginning of start step and end of end step in the transaction
componentErrorsintegern/atotal number of component errors encountered during load of this page
stepsarrayn/asee below
steps.stepNumintegern/astep index
steps.pageNumintegern/apage index
steps.durationintegermillisecondstime spent on this step
steps.offsetintegermillisecondstime spent waiting for previous steps to execute
pagesarrayn/asee below
pages.pageNumintegern/apage index
pages.pageNamestringn/ameta title value for page visited
pages.componentCountintegern/anumber of components on target page
pages.errorCountintegern/anumber of errors encountered during page load
pages.durationintegermillisecondstime spent on page

Example

$ curl https://api.thousandeyes.com/v6/web/transactions/825/12/1383891300.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Thu, 08 Nov 2013 07:32:48 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 228 X-Organization-Rate-Limit-Reset: 1493288220 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

{ "web": { "test": { "enabled": 1, "testId": 825, "testName": "http://thousandeyes.com", "type": "transactions", "interval": 900, "url": "http://thousandeyes.com", "totalSteps": 1, "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "createdDate": "2012-06-29 00:39:35", "apiLinks": [...] }, "transaction": [ { "agentName": "Hong Kong", "countryId": "HK", "date": "2013-11-08 06:15:10", "stepsCompleted": 1, "totalSteps": 1, "componentErrors": 0, "steps": [ { "stepNum": 0, "pageNum": 0, "duration": 4095, "offset": 0 } ], "pages": [ { "pageNum": 0, "pageName": "IT Performance Management for the Cloud Era - ThousandEyes", "componentCount": 46, "errorCount": 0, "duration": 4091 } ], "permalink": "https://app.thousandeyes.com/web/transactions?__a=75&testId=825&roundId=1383891300&agentId=12", "agentId": 12, "transactionTime": 4095, "roundId": 1383891300 } ] } }

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

GET /v6/web/transactions/{testId}/{agentId}/{roundId}/{pageNum} (Web) Transaction component detail

Returns HAR (http archive) information, including component list and timing for elements loaded in a transaction test. This is analogous to what is shown in the waterfall view for a page load or transaction test, with an agent selected. Includes response data, dns, connect, ssl, send, wait and receive times for each component loaded in a page.

Note: this endpoint is only available in v5 or higher of the ThousandEyes API.

Optional (Querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats 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

Request

  • {testId} the ID of the Transaction test you for wish to retrieve data
  • {agentId} the ID of the agent for which you wish to retrieve data
  • {roundId} the ID of the round for which you wish to retrieve data
  • {pageNum} the page number for the page reached in a transaction. Can be obtained from /web/transactions/{testId}/{agentId}/{roundId} endpoint. Page numbers are zero-indexed.
  • There is no request body for this request.

Response

Response data is returned according to the HAR specification.

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
responseTimeintegermillisecondstime to first byte
stepsCompletedintegern/anumber of steps successfully completed
totalStepsintegern/atotal number of steps in the transaction script
transactionTimeintegermillisecondselapsed execution time between beginning of start step and end of end step in the transaction
harhar*n/asee HAR specification for details.

Example

$ curl https://api.thousandeyes.com/v6/web/transactions/825/12/1412784300/0.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Thu, 08 Nov 2013 07:32:48 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 228 X-Organization-Rate-Limit-Reset: 1493288220 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

{ "web": { "test": { "alertsEnabled": 1, "apiLinks": [...], "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "createdDate": "2012-06-29 00:39:35", "enabled": 1, "endStep": 0, "includeHeaders": 0, "interval": 900, "liveShare": 0, "modifiedBy": "Deleted User", "modifiedDate": "2016-06-08 06:50:34", "savedEvent": 0, "startStep": 0, "targetTime": 10000, "testId": 825, "testName": "http://thousandeyes.com", "timeLimit": 60, "totalSteps": 1, "type": "transactions", "url": "http://thousandeyes.com", "userAgent": "Mozilla/5.0 AppleWebKit/999.0 (KHTML, like Gecko) Chrome/99.0 Safari/999.0" }, "transaction": [ { "agentId": 12, "agentName": "San Po Kong, Hong Kong", "componentErrors": 0, "countryId": "HK", "date": "2017-04-27 10:30:23", "har": { "log": { "creator": { "name": "ThousandEyes DB Exporter" }, "entries": [ { "pageref": "page_0", "request": { "method": "GET", "queryString": [], "url": "http://thousandeyes.com/" }, "response": { "bodySize": 213, "content": { "mimeType": "text/html", "size": 213 }, "headersSize": 239, "redirectURL": "", "status": 302, "statusText": "FOUND" }, "serverIPAddress": "54.208.6.220", "startedDateTime": "2017-04-27T17:30:23.001Z", "time": 402, "timings": { "blocked": 0, "connect": 190, "dns": 0, "receive": 2, "send": 0, "ssl": -1, "wait": 210 } }, ... ], "pages": [ { "id": "page_0", "pageTimings": {}, "responseCode": 0, "startedDateTime": "2017-04-27T17:30:23.000Z", "title": "Network Intelligence Software | ThousandEyes" } ], "version": "1.2" } }, "pages": [ { "componentCount": 44, "duration": 1640, "errorCount": 0, "pageName": "Network Intelligence Software | ThousandEyes", "pageNum": 0 } ], "permalink": "https://app.thousandeyes.com/web/transactions?__a=75&testId=825&roundId=1493289000&agentId=12", "roundId": 1493289000, "steps": [ { "duration": 1656, "offset": 0, "pageNum": 0, "stepNum": 0 } ], "stepsCompleted": 1, "totalSteps": 1, "transactionTime": 1656 } ] } }

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

GET /v6/web/ftp-server/{testId} (Web) FTP server

Returns response code, response and fetch times, as well as component-level (DNS, Connect, Negotiation, Response and Transfer) timing for the load of an object over FTP. FTP tests support plain text FTP, FTPS (FTP over SSL), and SFTP (secure FTP).

Note: this endpoint is only available in API v6 and higher.

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

Request

  • {testId} the ID of the HTTP Server (or page load) 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
serverIpstringn/aIP address of destination server
responseCodeintegern/acode of FTP response
dnsTimefloatmillisecondstime required to resolve DNS
connectTimefloadmillisecondstime required to establish a TCP connection to the server
negotiationTimefloatmillisecondstime negotiate the connection and authenticate with the destination server
waitTimefloatmillisecondstime elapsed between completion of request and first byte of response
responseTimefloatmillisecondssum of DNS, connect, negotiation and wait times
transferTimefloatmillisecondselapsed time between first and last byte of the transfer
wireSizefloatbytessize of content, in bytes
totalTimeintegermillisecondssum of response + transfer time
errorTypestringn/atype of error encountered; corresponds to phase of connection
errorDetailsstringn/aerror details, if an error were encountered

Example

$ curl https://api.thousandeyes.com/v6/web/ftp-server/367580.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Thu, 08 Nov 2013 07:32:48 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 228 X-Organization-Rate-Limit-Reset: 1493288220 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

{ "pages": { "current": 1 }, "web": { "ftpServer": [ { "agentId": 144, "agentName": "Vienna, Austria", "connectTime": 50.153, "countryId": "AT", "date": "2017-04-27 11:44:13", "dnsTime": 0.589, "errorType": "None", "negotiationTime": 503.413, "permalink": "https://app.thousandeyes.com/web/ftp-server?__a=75&testId=367580&roundId=1493293440&agentId=144", "responseCode": 226, "responseTime": 605.689, "roundId": 1493293440, "serverIp": "193.2.1.88", "throughput": 222019, "totalTime": 705.554, "transferTime": 99.865, "waitTime": 52.1, "wireSize": 22172 } ], "test": { "alertsEnabled": 0, "apiLinks": [...], "bandwidthMeasurements": 0, "bgpMeasurements": 1, "createdBy": "Deleted User", "createdDate": "2017-04-27 11:40:12", "enabled": 1, "ftpTargetTime": 1000, "ftpTimeLimit": 10, "interval": 120, "liveShare": 0, "modifiedBy": "Deleted User", "modifiedDate": "2017-04-27 11:42:31", "mtuMeasurements": 1, "networkMeasurements": 1, "requestType": "List", "savedEvent": 0, "testId": 367580, "testName": "ftp://ftp.arnes.si", "type": "ftp-server", "url": "ftp://ftp.arnes.si/packages/gnu/", "useActiveFtp": 0, "useExplicitFtps": 0, "username": "anonymous" } } }

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

GET /v6/dns/trace/{testId} (DNS) Domain trace

Returns a DNS record from the vantage point of the agent. Similar to dig +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

Request

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

Response

Take note of the output field in the response body below – depending on the record type requested, the data can be extremely verbose. Test metadata is shown in the first element of the response (test), and the “trace” element follows as the second element, showing an array of responses (one from each agent).

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
outputstringn/averbose output from the trace request
errorDetailsstringn/aif an error was encountered, error text
queriesintegern/ahow many queries were required to get to the requested result
failedQueriesintegern/ahow many queries failed while getting to the requested result
finalServerQueriedstringn/aDNS server that provided the final result
finalQueryTimeintegermillisecondshow long the final query took to return a response
mappingsstringn/afinal mappings returned from the request

Example

$ curl https://api.thousandeyes.com/v6/dns/trace/820.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Thu, 08 Nov 2013 07:32:48 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 229 X-Organization-Rate-Limit-Reset: 1493294160 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "dns": { "test": { "enabled": 1, "testId": 17594, "testName": "thousandeyes.com A", "type": "dns-trace", "interval": 900, "domain": "thousandeyes.com A", "modifiedDate": "2014-01-21 03:19:16", "createdBy": "API Sandbox Admin (api.sandbox+admin@thousandeyes.com)", "modifiedBy": "API Sandbox Admin (api.sandbox+admin@thousandeyes.com)", "createdDate": "2014-01-21 03:19:16", "apiLinks": [...] }, "trace": [ { "agentName": "São Paulo, Brazil", "countryId": "BR", "date": "2014-01-21 03:20:09", "output": "com.\t172800\tIN\tNS\ta.gtld-servers.net.\ncom.\t172800\tIN\tNS\tf.gtld-servers.net.\ncom.\t172800\tIN\tNS\tc.gtld-servers.net.\ncom.\t172800\tIN\tNS\tb.gtld-servers.net.\ncom.\t172800\tIN\tNS\td.gtld-servers.net.\ncom.\t172800\tIN\tNS\te.gtld-servers.net.\ncom.\t172800\tIN\tNS\tg.gtld-servers.net.\ncom.\t172800\tIN\tNS\tm.gtld-servers.net.\ncom.\t172800\tIN\tNS\th.gtld-servers.net.\ncom.\t172800\tIN\tNS\tj.gtld-servers.net.\ncom.\t172800\tIN\tNS\ti.gtld-servers.net.\ncom.\t172800\tIN\tNS\tl.gtld-servers.net.\ncom.\t172800\tIN\tNS\tk.gtld-servers.net.\n;; Received 498 bytes from 199.7.91.13(d.root-servers.net.) in 119 ms\n\nthousandeyes.com.\t172800\tIN\tNS\ta1.verisigndns.com.\nthousandeyes.com.\t172800\tIN\tNS\ta2.verisigndns.com.\nthousandeyes.com.\t172800\tIN\tNS\ta3.verisigndns.com.\nthousandeyes.com.\t172800\tIN\tNS\tu1.verisigndns.com.\n;; Received 266 bytes from 192.5.6.30(a.gtld-servers.net.) in 178 ms\n\napp.thousandeyes.com.\t300\tIN\tCNAME\tweb.thousandeyes.com.\nweb.thousandeyes.com.\t300\tIN\tCNAME\tlb-app.thousandeyes.com.\nlb-app.thousandeyes.com.\t3600\tIN\tA\t208.185.7.120\n;; Received 173 bytes from 209.112.113.33(a1.verisigndns.com.) in 178 ms\n\n", "permalink": "https://app.thousandeyes.com/dns/trace?__a=75&testId=17594&roundId=1390274400&agentId=16", "agentId": 16, "errorDetails": "", "queries": 3, "failedQueries": 0, "finalServerQueried": "a1.verisigndns.com.", "finalQueryTime": 178, "mappings": "208.185.7.120" }, ... ] }, "pages": { "current": 1 } }

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

GET /v6/dns/server/{testId}/{serverId} (DNS) Server metrics

Returns the mappings for a DNS record, along with resolution time to each authoritative server, as measured from the vantage point of the agent. Similar to dig @server.

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

Request

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

Response

The DNS Server tests are somewhat unique, in that you are testing multiple targets with a single test configuration. For example - if you’re testing com. NS, you’ll actually end up with 13 tests, since the test should be targeting 13 different nameservers [a-m].gtld-servers.net. This test tests resolution time to each of the authoritative nameservers from each agent, ending up with something of a matrix of test results for each iteration.

For tests with Network Measurements enabled ("networkMeasurements": 1), you’ll need the serverId identified in the test to pull network metrics for your DNS server test. Syntax for DNS Server network metrics see End-to-End Metrics is as follows:

$ curl https://api.thousandeyes.com/v6/dns/server/{testId}/{serverId}.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

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
serverIdintegern/ainternal ID of DNS server being tested
serverstringn/acanonical name of server being tested
resolutionTimeintegermillisecondshow long it took to run the query against the server
errorDetailsstringn/aif an error was encountered, error text
queriesintegern/ahow many queries were reuqired to get to the requested result
mappingsstringn/afinal mappings returned from the request

Example

$ curl https://api.thousandeyes.com/v6/dns/server/821.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Thu, 08 Nov 2013 07:32:48 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 229 X-Organization-Rate-Limit-Reset: 1493294160 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "dns": { "test": { "enabled": 1, "testId": 821, "testName": "thousandeyes.com ANY", "type": "dns-server", "interval": 900, "domain": "thousandeyes.com ANY", "dnsServers": [ { "serverId": 465, "serverName": "a1.verisigndns.com." } ], "modifiedDate": "2013-05-11 02:02:16", "networkMeasurements": 1, "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "modifiedBy": "API Sandbox User (noreply@thousandeyes.com)", "createdDate": "2012-06-28 20:47:29", "apiLinks": [...] }, "server": [ { "agentName": "Hong Kong", "countryId": "HK", "date": "2013-11-13 04:30:20", "permalink": "https://app.thousandeyes.com/dns/server?__a=75&testId=821&roundId=1384317000&serverId=465&agentId=12", "agentId": 12, "serverId": 465, "server": "a1.verisigndns.com.", "resolutionTime": 3, "roundId": 1384317000, "errorDetails": "", "mappings": "a1.verisigndns.com. dnssupport.verisign-grs.com. 2284831191 28800 7200 1209600 3600 (SOA)\na1.verisigndns.com. (NS)\nu1.verisigndns.com. (NS)\na2.verisigndns.com. (NS)\na3.verisigndns.com. (NS)\n54.215.17.122 (A)\n0 aspmx.l.google.com. (MX)\n5 alt1.aspmx.l.google.com. (MX)\n10 aspmx3.googlemail.com. (MX)\n5 alt2.aspmx.l.google.com. (MX)\n10 aspmx2.googlemail.com. (MX)\n\"7LO6JGX\" (TXT)\n\"v=spf1 ip4:65.122.4.140 ip4:208.185.7.125 include:_spf.google.com include:daredevil.thousandeyes.com include:sendgrid.net include:spf.braintreegateway.com include:emailer.hubspot.com include:eventbrite.com include:support.zendesk.com include:smtp.zendesk.\" \"com include:mktoma\\\" \\\"il.com ~all\" (TXT)\n\"google-site-verification=J9DoQXN_dDvzrDb53j_fETYTJjIRKOn-42sPbrJvpHA\" (TXT)" }, ... ] }, "pages": { "current": 1 } }

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

GET /v6/dns/dnssec/{testId} (DNS) DNSSEC

Returns the keychain validity for a record on a domain secured using DNSSEC extensions.

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

Request

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

Response

Validity can be measured using the errorDetails element, which will be populated in the event of an error validating the keychain.

FieldData TypeUnitsNotes
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
agentIdintegern/aunique ID of agent, from /agents endpoint
roundIdlongsecondsepoch time (seconds) indicating the start time of the round
validbooleann/a1 for valid, 0 for invalid (see errorDetails field)
permalinkurln/alink to jump to this result in the front end
errorDetailsstringn/aif an error was encountered, error text

Example

$ curl https://api.thousandeyes.com/v6/dns/dnssec/822.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Thu, 08 Nov 2013 07:32:48 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 229 X-Organization-Rate-Limit-Reset: 1493294160 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "dns": { "test": { "enabled": 1, "testId": 822, "testName": "thousandeyes.com A", "type": "dns-dnssec", "interval": 900, "domain": "thousandeyes.com A", "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "createdDate": "2012-06-28 20:48:01", "apiLinks": [...] }, "dnssec": [ { "agentName": "Hong Kong", "countryId": "HK", "date": "2013-11-13 04:30:01", "valid": 0, "roundId": 1384317000, "permalink": "https://app.thousandeyes.com/dns/dnssec?__a=75&testId=822&roundId=1384317000&agentId=12", "agentId": 12, "errorDetails": "No DNSSEC public key(s) for thousandeyes.com A" }, ... ] }, "pages": { "current": 1 } }

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

GET /v6/dnsp/availability/{testId} (DNS+) Availability

Returns the availability percentage (as measured by the number of vantage points globally which respond with no error) for a domain, aggregated on a country basis.

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

Request

  • {testId} (Required) the ID of the DNS+ Domain test you for wish to retrieve data
  • {testId}/{countryId} (Optional) append {countryId} to return results only for that Country. Wildcard \* is supported, to return a single global aggregate.
  • {testId}/{countryId}/network (Optional) append network to obtain network-level data for a specific country. Wildcard \* is not supported.
  • There is no request body for this request.

Response

For country-agnostic DNS+ measurements, aggregate values will be returned for each country with vantage points tested in the verification. Data is grouped on a country basis; the first record returned is a * record, which indicates rollup values for all countries in which vantage points were present.

To return aggregate data for a single country, append the two-digit (ISO-3166-1 alpha-2) country code to the request:

$ curl https://api.thousandeyes.com/v6/dnsp/availability/{testId}/{countryId}.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

To return data aggregated at the network (autonomous system) level, append /network to the single-country request (as follows), and a list of networks will be shown, with aggregated information at the network level:

$ curl https://api.thousandeyes.com/v6/dnsp/availability/{testId}/{countryId}/network.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

FieldData TypeUnitsNotes
countryIdstringn/aISO-3166-1 alpha-2 country code
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
domainstringn/arecord + type requested
availabilityfloatpercentageavailability from the specified country
totalVantagePointsintegern/atotal number of vantage points used to run this test round
totalIspsintegern/anumber of ISPs with responding vantage points for this test round
referenceAvailabilityfloatpercentageavailability calculated during this round to top 25 reference sites

Example

$ curl https://api.thousandeyes.com/v6/dnsp/availability/812.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Thu, 08 Nov 2013 07:32:48 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 229 X-Organization-Rate-Limit-Reset: 1493294160 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "dnsp": { "test": { "enabled": 1, "testId": 812, "testName": "thousandeyes.com", "type": "dnsp-domain", "interval": 900, "ttl": 120, "domain": "thousandeyes.com A", "modifiedDate": "2012-06-28 19:35:19", "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "modifiedBy": "API Sandbox User (noreply@thousandeyes.com)", "createdDate": "2012-06-28 00:26:02", "apiLinks": [...] }, "availability": [ { "countryId": "*", "date": "2013-11-13 04:42:19.0", "domain": "thousandeyes.com A", "availability": 99.7154, "permalink": "https://app.thousandeyes.com/dnsp/availability?__a=75&testId=812&roundId=1384317000&countryId=", "totalVantagePoints": 2108, "totalIsps": 631, "roundId": 1384317000, "referenceAvailability": "99.6424" }, { "countryId": "AR", "date": "2013-11-13 04:41:49.0", "domain": "thousandeyes.com A", "availability": 100, "permalink": "https://app.thousandeyes.com/dnsp/availability?__a=75&testId=812&roundId=1384317000&countryId=AR", "totalVantagePoints": 49, "totalIsps": 12, "roundId": 1384317000, "referenceAvailability": "100" }, ... ] } "pages": { "current": 1 } }

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

GET /v6/dnsp/mappings/{testId} (DNS+) Mappings

Returns the mapping, and percentage (as measured by the number of vantage points globally which respond with that mapping) for a domain, aggregated on a country basis. Where multiple mappings are detected in a country, each mapping will be shown, along with a corresponding number of vantage points responding with that mapping.

Optional (Querystring) Parameters

  • format=json|xml (Optional) specifies the format of output requested. See Output Formats for more information
  • window=[0-9]+[smhdw]? (Optional) 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 (Optional) 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

Request

  • {testId} (Required) the ID of the DNS+ Domain test you for wish to retrieve data
  • {testId}/{countryId} (Optional) append {countryId} to return results only for that Country. Wildcard \* is supported, to return a single global aggregate.
  • {testId}/{countryId}/network (Optional) append network to obtain network-level data for a specific country. Wildcard \* is not supported.
  • There is no request body for this request.

Response

For country-agnostic DNS+ measurements, aggregate values will be returned for each country with vantage points tested in the verification. Data is grouped on a country basis; the first record returned is a * record, which indicates rollup values for all countries in which vantage points were present.

To return aggregate data for a single country, append the two-digit (ISO-3166-1 alpha-2) country code to the request:

$ curl https://api.thousandeyes.com/v6/dnsp/mappings/{testId}/{countryId}.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

To return data aggregated at the network (autonomous system) level, append /network to the single-country request (as follows), and a list of networks will be shown, with aggregated information at the network level:

$ curl https://api.thousandeyes.com/v6/dnsp/mappings/{testId}/{countryId}/network.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

FieldData TypeUnitsNotes
countryIdstringn/aISO-3166-1 alpha-2 country code
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
domainstringn/arecord + type requested
mappingstringn/amapping returned from server
totalVantagePointsintegern/atotal number of vantage points used to run this test round
totalIspsintegern/anumber of ISPs with responding vantage points for this test round
percentVantagePointsfloatpercentagepercentage of vantage points responding with this mapping

Example

$ curl https://api.thousandeyes.com/v6/dnsp/mappings/812.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Thu, 08 Nov 2013 07:32:48 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 229 X-Organization-Rate-Limit-Reset: 1493294160 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "dnsp": { "test": { "enabled": 1, "testId": 812, "testName": "thousandeyes.com", "type": "dnsp-domain", "interval": 900, "ttl": 120, "domain": "thousandeyes.com A", "modifiedDate": "2012-06-28 19:35:19", "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "modifiedBy": "API Sandbox User (noreply@thousandeyes.com)", "createdDate": "2012-06-28 00:26:02", "apiLinks": [...] ] }, "mapping": [ { "countryId": "*", "date": "2013-11-13 04:42:09.0", "domain": "thousandeyes.com A", "permalink": "https://app.thousandeyes.com/dnsp/mappings?__a=75&testId=812&roundId=1384317000&countryId=&mappingData=54.215.17.122", "totalVantagePoints": 2102, "totalIsps": 630, "mapping": "54.215.17.122", "roundId": 1384317000, "percentVantagePoints": 100 }, { "countryId": "AR", "date": "2013-11-13 04:41:49.0", "domain": "thousandeyes.com A", "permalink": "https://app.thousandeyes.com/dnsp/mappings?__a=75&testId=812&roundId=1384317000&countryId=AR&mappingData=54.215.17.122", "totalVantagePoints": 49, "totalIsps": 12, "mapping": "54.215.17.122", "roundId": 1384317000, "percentVantagePoints": 100 }, ... ] } "pages": { "current": 1 } }

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

GET /v6/dnsp/resolution-time/{testId} (DNS+) Resolution time

Returns the average resolution time for a domain, aggregated on a country basis.

Optional (Querystring) Parameters

  • format=json|xml (Optional) specifies the format of output requested. See Output Formats for more information
  • window=[0-9]+[smhdw]? (Optional) 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 (Optional) 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

Request

  • {testId} (Required) the ID of the DNS+ Domain test you for wish to retrieve data
  • {testId}/{countryId} (Optional) append {countryId} to return results only for that Country. Wildcard \* is supported, to return a single global aggregate.
  • {testId}/{countryId}/network (Optional) append network to obtain network-level data for a specific country. Wildcard \* is not supported.
  • There is no request body for this request.

Response

For country-agnostic DNS+ measurements, aggregate values will be returned for each country with vantage points tested in the verification. Data is grouped on a country basis; the first record returned is a * record, which indicates rollup values for all countries in which vantage points were present.

To return aggregate data for a single country, append the two-digit (ISO-3166-1 alpha-2) country code to the request:

$ curl https://api.thousandeyes.com/v6/dnsp/resolution-time/{testId}/{countryId}.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

To return data aggregated at the network (autonomous system) level, append /network to the single-country request (as follows), and a list of networks will be shown, with aggregated information at the network level:

$ curl https://api.thousandeyes.com/v6/dnsp/resolution-time/{testId}/{countryId}/network.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

FieldData TypeUnitsNotes
countryIdstringn/aISO-3166-1 alpha-2 country code
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
domainstringn/arecord + type requested
totalVantagePointsintegern/atotal number of vantage points used to run this test round
totalIspsintegern/anumber of ISPs with responding vantage points for this test round
resolutionTimeintegermillisecondsaverage resolution time to this domain
referenceResolutionTimeintegermillisecondsaverage resolution time calculated during this round to top 25 reference sites

Example

$ curl https://api.thousandeyes.com/v6/dnsp/resolution-time/812.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Thu, 08 Nov 2013 07:32:48 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 229 X-Organization-Rate-Limit-Reset: 1493294160 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "dnsp": { "test": { "enabled": 1, "testId": 812, "testName": "thousandeyes.com", "type": "dnsp-domain", "interval": 900, "ttl": 120, "domain": "thousandeyes.com A", "modifiedDate": "2012-06-28 19:35:19", "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "modifiedBy": "API Sandbox User (noreply@thousandeyes.com)", "createdDate": "2012-06-28 00:26:02", "apiLinks": [...] }, "resolutionTime": [ { "countryId": "*", "date": "2013-11-13 04:40:03.0", "domain": "thousandeyes.com A", "permalink": "https://app.thousandeyes.com/dnsp/resolution-time?__a=75&testId=812&roundId=1384317000&countryId=", "totalVantagePoints": 2065, "totalIsps": 623, "resolutionTime": 78, "roundId": 1384317000, "referenceResolutionTime": "102" }, { "countryId": "AR", "date": "2013-11-13 04:31:00.0", "domain": "thousandeyes.com A", "permalink": "https://app.thousandeyes.com/dnsp/resolution-time?__a=75&testId=812&roundId=1384317000&countryId=AR", "totalVantagePoints": 48, "totalIsps": 12, "resolutionTime": 288, "roundId": 1384317000, "referenceResolutionTime": "167" }, ... ] } "pages": { "current": 1 } }

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

GET /v6/dnsp/server-latency/{testId} (DNS+) Server latency

Returns the server latency metrics from a global perspective for a specific nameserver, aggregated on a country basis.

Optional (Querystring) Parameters

  • format=json|xml (Optional) specifies the format of output requested. See Output Formats for more information
  • window=[0-9]+[smhdw]? (Optional) 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 (Optional) 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

Request

  • {testId} (Required) the ID of the DNS+ Domain test you for wish to retrieve data
  • {testId}/{countryId} (Optional) append {countryId} to return results only for that Country. Wildcard \* is supported, to return a single global aggregate.
  • {testId}/{countryId}/network (Optional) append network to obtain network-level data for a specific country. Wildcard \* is not supported.
  • There is no request body for this request.

Response

For country-agnostic DNS+ measurements, aggregate values will be returned for each country with vantage points tested in the verification. Data is grouped on a country basis; the first record returned is a * record, which indicates rollup values for all countries in which vantage points were present.

To return aggregate data for a single country, append the two-digit (ISO-3166-1 alpha-2) country code to the request:

$ curl https://api.thousandeyes.com/v6/dnsp/server-latency/{testId}/{countryId}.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

To return data aggregated at the network (autonomous system) level, append /network to the single-country request (as follows), and a list of networks will be shown, with aggregated information at the network level:

$ curl https://api.thousandeyes.com/v6/dnsp/server-latency/{testId}/{countryId}/network.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

FieldData TypeUnitsNotes
countryIdstringn/aISO-3166-1 alpha-2 country code
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
totalVantagePointsintegern/atotal number of vantage points used to run this test round
totalIspsintegern/anumber of ISPs with responding vantage points for this test round
latencyintegermillisecondsaverage latency calculated to target DNS server

Example

$ curl https://api.thousandeyes.com/v6/dnsp/server-latency/5786.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Thu, 08 Nov 2013 07:32:48 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 229 X-Organization-Rate-Limit-Reset: 1493294160 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "dnsp": { "serverLatency": [ { "countryId": "*", "date": "2017-04-27 12:01:58", "latency": 105, "roundId": 1493294400, "totalIsps": 184, "totalVantagePoints": 292 }, { "countryId": "AR", "date": "2017-04-27 12:01:58", "latency": 261, "roundId": 1493294400, "totalIsps": 4, "totalVantagePoints": 5 }, ... ], "test": { "alertsEnabled": 0, "apiLinks": [...], "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "createdDate": "2013-04-15 20:50:14", "enabled": 1, "interval": 3600, "savedEvent": 0, "server": "pdns4.ultradns.org.", "testId": 5786, "testName": "pdns4.ultradns.org", "type": "dnsp-server" } }, "pages": { "current": 1 } }

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

GET /voice/metrics/{testId} (Voice) Metrics

Returns voice metrics (loss, latency, jitter, MOS score) from each agent, for each roundId in the requested window. A time frame must be specified, or the current round of data will be returned.

Optional (Querystring) Parameters

  • format=json|xml (Optional) specifies the format of output requested. See Output Formats for more information
  • window=[0-9]+[smhdw]? (Optional) 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 (Optional) 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

Request

  • {testId} (Required) the ID of the Voice test you for wish to retrieve data
  • 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
dscpstringn/aDSCP value received by the server from the agent
dscpNamestringn/aname of DSCP value received by the server from the agent
mosfloatn/aMean opinion score for agent’s stream
codecNamestringn/aname of codec used by agent
codecMaxMosfloatn/amaximum value of Mean Opinion Score based on codec selection
lossfloatpercentagepercentage value of packets sent from agent not received by server
discardsintegern/anumber of packets discarded
latencyintegermillisecondstime to send packets from source to server
pdvfloatmillisecondsvariation in packet delay, measured in milliseconds
errorDetailstringn/aerror details, if an error was encountered.

Example

$ curl https://api.thousandeyes.com/v6/voice/metrics/6627.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Thu, 08 Nov 2013 07:32:48 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 229 X-Organization-Rate-Limit-Reset: 1493294160 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

{ "voice": { "test": { "enabled": 1, "savedEvent": 0, "testId": 6627, "testName": "my second voice test", "type": "voice", "interval": 300, "server": "vps-lhr4.thousandeyes.com:49152", "codec": "G.722 @ 32 Kbps", "codecId": 2, "dscpId": 8, "jitterBuffer": 40, "alertsEnabled": 1, "liveShare": 0, "targetAgentId": 11, "modifiedDate": "2014-07-11 22:53:04", "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "modifiedBy": "API Sandbox User (noreply@thousandeyes.com)", "dscp": "CS 1 (8)", "createdDate": "2014-06-13 23:19:23", "apiLinks": [...] }, "metrics": [ { "agentName": "va-office", "countryId": "US", "date": "2014-08-07 01:25:31", "dscp": 8, "mos": 3.95378, "codecName": "G.722 @ 32 Kbps", "codecMaxMos": 4.03, "dscpName": "CS 1 (8)", "loss": 0, "discards": 0, "permalink": "https://app.thousandeyes.com/voice/metrics?__a=11&testId=6627&roundId=1407374700&agentId=97", "agentId": 97, "roundId": 1407374700, "latency": 75, "pdv": 0, "errorDetail": "" } ] }, "pages": {} }

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