ThousandEyes API v6
ThousandEyes API v6

(DNS) Domain trace

ThousandEyes API v6 has been deprecated as of May 27, 2024. We strongly recommend that you migrate to ThousandEyes API v7 to ensure continued support and access to new features. For more information, see the deprecation notice.

GET /v6/dns/trace/{testId}

Returns a DNS record from the vantage point of the agent. Similar to dig +trace.

Parameters

Querystring

  • 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).

Field Data Type Units Notes
agentId integer n/a unique ID of agent, from /agents endpoint
agentName string n/a display name of the agent responding
countryId string n/a ISO-3166-1 alpha-2 country code of the agent
date dateTime n/a yyyy-MM-dd hh:mm:ss, in UTC
roundId long seconds epoch time (seconds) indicating the start time of the round
permalink url n/a link to jump to this result in the front end
output string n/a verbose output from the trace request
errorDetails string n/a if an error was encountered, error text
queries integer n/a how many queries were required to get to the requested result
failedQueries integer n/a how many queries failed while getting to the requested result
finalServerQueried string n/a DNS server that provided the final result
finalQueryTime integer milliseconds how long the final query took to return a response
mappings string n/a final mappings returned from the request

Example

curl
Copy$ curl https://api.thousandeyes.com/v6/dns/trace/820.json \
  -u {email}:{authToken}
Code Snippet
CopyHTTP/1.1 200 OK
Date: Sat, 08 Feb 2020 16:55:04 GMT
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept-Encoding
X-Server-Name: d7nds
Cache-Control: no-store
X-Organization-Rate-Limit-Limit: 240
X-Organization-Rate-Limit-Remaining: 229
X-Organization-Rate-Limit-Reset: 1581180960
Strict-Transport-Security: max-age=15724800; includeSubDomains
Strict-Transport-Security: max-age=31536000
X-Content-Type-Options: nosniff

Body

json
Copy{
    "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",
            "savedEvent": 0,
            "liveShare": 0,
            "dnsTransportProtocol": "UDP",
            "dnsQueryClass": "IN",
            "alertsEnabled": 1,
            "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.

Next