Overview

Welcome

Most applications will use an existing wrapper library in the language of your choice. Over the past several months, we’ve had discussions with customers using LINQ, Microsoft .NET, Python and Java to access our API content.

That said, it’s important to get familiar with the underlying methods used in the API before getting your hands dirty.

For simplicity’s sake, we’ll use cURL for documenting examples, and outputs will be shown in JSON (because it’s less verbose than XML and lends itself more readily to readability) - see response formats for more detailed information on controlling output format.

Let’s start by accessing an information-only API endpoint.

$ curl https://api.thousandeyes.com/v6/status.json

Output

This returns the current controller time (in epoch format), if run correctly. This is simply intended for verification that the API is currently running.

{"timestamp":1492606869263}

Let’s show the response headers, using the -i flag:

$ curl -i https://api.thousandeyes.com/v6/status.json

Output

Most of the headers are inconsequential - you’ll see the server’s date and time, version, http status code for your request. When working with our API programmatically, always check to make sure you receive an HTTP/200 response code to your request.

HTTP/1.1 200 OK Server: nginx Date: Wed, 19 Apr 2017 13:01:09 GMT Content-Type: text/xml Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-5

{"timestamp":1492606869263}

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

Authentication

The ThousandEyes API accepts Basic HTTP or OAuth bearer token as authentication methods. This is specified using the HTTP request wrapper of your choice. Both the Basic Authentication Token and the OAuth Bearer Token referenced here and throughout the developer reference are available from your account settings page under the “Security and Authentication” Tab.

The example below shows a standard request using cURL with basic authentication:

$ curl -i https://api.thousandeyes.com/v6/status \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

The following example leverages cURL presenting a bearer token:

$ curl -i https://api.thousandeyes.com/v6/tests.json \ --header "Authorization: Bearer d320dbc5-a3c9-4c57-b2dc-6d2b46dbee13"

For basic authentication, the parameters can be provided programmatically using whichever HTTP request object is being used (most all support Basic HTTP authentication), or prepended to the target URL, in the following format:

https://{email}:{authToken}@api.thousandeyes.com/v6/

When providing the email address prepended to the URL, it must be URL-encoded to allow the request to proceed correctly. The @ symbol corresponds to %40. See UrlEncoding characters for more information on properly formatting character strings. When using cURL, using the -u user:token method is strongly recommended.

For bearer token authentication, the parameter can only be read in the header in the form Authorization: Bearer <token string>

Powershell Syntax

We’ve been asked by a number of people how to effectively create and leverage credentials against the API in Windows Powershell. Effectively, base64 encoding the email:authtoken and setting an Authorization header will allow this to be done. The following example takes two inputs and sets the required headers to work with the ThousandEyes API using basic authentication:

$apiuser = "noreply@thousandeyes.com" $apipassword = "g351mw5xqhvkmh1vq6zfm51c62wyzib2" $authorization = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($apiuser + ":" + $apipassword)) $headers = @{"accept"= "application/json"; "content-type"= "application/json"; "authorization"= "Basic " + $authorization} $response = Invoke-WebRequest https://api.thousandeyes.com/v6/agents.json -Headers $headers $response.content

When leveraging the bearer token, the token itself can be passed directly as a string:

$apitoken="d320dbc5-a3c9-4c57-b2dc-6d2b46dbee13" $headers = @{"accept"= "application/json"; "content-type"= "application/json"; "authorization"= "Bearer " + $apitoken} $response = Invoke-WebRequest https://api.thousandeyes.com//v6/tests.json -Headers $headers $response.content

NOTE: Both the Basic Authentication Token and the OAuth Bearer Token are available from your account settings page under the “Security and Authentication” Tab.

Account Lockout

If our system detects 10 unsuccessful attempts to access the API over a period of 1 hour, the IP address making the login attempts will be banned for a period of 1 hour, beginning with the last request.

If attempts to reach the API are returning an HTTP/429 (too many requests) response code, it is likely that an attempt to login from this IP was unsuccessful. Contact support for more information and instructions on remediation.

For error responses, see the response status codes documentation.

GET /v6/account-groups Account group context

Users assigned to multiple account groups can change account group context by using the aid={aid} parameter. A list of account group IDs can be found using the /account-groups endpoint.

Returns a list of all account groups in the user’s organization that the user can access. Users without access will receive an HTTP/403 Forbidden response, indicating that the user does not have sufficient permissions to access this resource. If the user specifies an invalid account group ID, the user will receive an HTTP/400 Bad Request response.

Example

Note: the Sandbox account provided does not have access to multiple account groups, and therefore cannot be used to validate this endpoint. The example below is shown only for the purposes of continuity.

$ curl -i https://api.thousandeyes.com/v6/account-groups \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Error responses as follows:

  • Users may receive an HTTP/400 Bad Request response, in the event that an invalid account ID is specified.
  • Users attempting to access an account group to which they do not belong will receive an HTTP/403 Forbidden response, indicating a lack of permissions to the resource.

If successful, returns a list of account groups available to the authenticated user. The “default” flag indicates that this is the main account of the user, and that any query not including an aid parameter will be executed in that account group context.

The “current” flag indicates that this is the account group context you are in at present. For example, calling https://api.thousandeyes.com/v6/accounts?aid=354 would change the account context, and show current=1 for account ID 354, even though the user’s default account ID is 353. Data is shown below using this call as an example.

HTTP/1.1 200 OK Server: nginx Date: Wed, 19 Apr 2017 13:05:24 GMT Content-Type: application/json;charset=UTF-8 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: 1492607160 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

{ "account": [ { "aid": 353, "accountGroupName": "Test Account Name #1", "organizationName": "Documentation", "current": 0, "default": 1 }, { "aid": 354, "accountGroupName": "Test Account Name #2", "organizationName": "Documentation", "current": 1, "default": 0 }, { "aid": 355, "accountGroupName": "Test Account Name #3", "organizationName": "Another Organization", "current": 0, "default": 0 }, ] }

Response formats

Current version of the ThousandEyes API allows output in the following formats:

It is possible to control the output of the API’s results using the following options, in descending order of precedence.

In the event that multiple, conflicting formats are specified, the order of precedence is:

  1. Request
  2. Accept Header
  3. Querystring Parameter.

Append format to request

Appending either .xml or .json to the request will return the response in that type.

  • to request a JSON response:

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

  • to request an XML response:

$ curl https://api.thousandeyes.com/v6/tests.xml \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Accept Header

Modifying the header to accept different response types is the approach which will be most effective for guaranteeing the response type.

  • Accept:application/json will return the response in JSON
  • Accept:text/xml will return the response in XML

$ curl -H "Accept: application/json" https://api.thousandeyes.com/v6/tests \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

QueryString Parameter

Appending a format parameter to the end of a QueryString will change the response format. The parameter and values must be in lowercase. Acceptable options:

  • format=xml
  • format=json

$ curl https://api.thousandeyes.com/v6/tests?format=json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Time ranges

Most requests (check Optional Parameters section in each endpoint), allow a time range to be specified using parameters. Specifically, window is allowed for alert listings, and either window, from, or from and to are allowed on all data requests. If the endpoint doesn’t respect the optional parameters, they will be ignored.

window=[0-9]+[smhdw]? The window parameter is used to specify an amount of time in the past for which to fetch data. That is, data will be retrieved from the specified amount of time ago up until the time of the request. A time window is a number followed by an optional time interval type. The supported time interval types are s for seconds, m for minutes, h for hours, d for days, and w for weeks. If no time interval type is specified, seconds are assumed. For example, window=10d would retrieve data from the last 10 days, window=12h would retrieve data from the last 12 hours, and window=1200 will retrieve data from the last 1200 seconds.

from=YYYY-mm-ddTHH:MM:SS from=YYYY-mm-ddTHH:MM:SS&to=YYYY-mm-ddTHH:MM:SS

The from and to parameters are used to specify a specific date and time range for the data. The to parameter is optional – if omitted, the current time (at the time of the request) will be assumed. Dates must be specified in the ISO 8601 date-time format, with hyphens between date fields and colons between time fields. The full time (hours, minutes, and seconds) must be included. The date and time can be separated by either a space or the letter T. Example: 2012-01-01T00:00:00. The date range is inclusive. Time zone is UTC.

Note: The from/to and window parameters are mutually exclusive – the server will produce a 400 error if both window and either from or to is specified. It will also produce a 400 error if to is specified without from.

On endpoints where roundId is required component of the URL, roundId is represented as epoch time corresponding to the start of a round, in seconds. For example, if a round starts on 2015-06-30 16:00:00 UTC, the roundId would be 1435680000. roundId values are always exactly divisible by the test frequency, which is specified in seconds. The next rounds for a test with a 5-minute interval would be 1435680000 + 300, or 1435680300, 1435680600, 1435680900 and so on.

For error responses, see the response status codes documentation.

Response status codes

The following response status codes will be used for various endpoints around the ThousandEyes API.

Status CodeDefinitionWhen you’ll see it
200OKNearly every response
201CREATEDUsing the /tests/{testType}/new endpoint
204NO CONTENTUsing the /tests/{testType}/{testId}/delete endpoint
301MOVED PERMANENTLYRequests accessing a nonexistent version of the API
400BAD REQUESTMalformatted requests
401UNAUTHORIZEDInvalid credentials provided or account is locked
403FORBIDDENInsufficient permissions to execute request (ie, any POST method as a regular user)
404NOT FOUNDAttempting to access an endpoint that does not exist
405METHOD NOT ALLOWEDWrong request type for target endpoint (ie, POSTing data to a GET endpoint)
406NOT ACCEPTABLECan be returned when the Content Type of the data returned does not match the Accept header of the request
415UNSUPPORTED MEDIA TYPEAttempting to POST data in incorrect format
429TOO MANY REQUESTSYou have exceeded the max number of requests per 1-minute period
500INTERNAL SERVER ERRORContact support if you see this error type
503SERVICE UNAVAILABLEThe ThousandEyes API is currently in maintenance mode.

Rate limits

The ThousandEyes API throttles API requests using a 240 request per minute (per organization) limit. The limit rolls over one minute from the first request in a batch, and starts again when the minute rolls over. These values are subject to change, as we work through identifying appropriate use patterns for our API.

Users can watch three header values in responses from the ThousandEyes API for information on rate limits:

HTTP/1.1 200 OK X-Organization-RateLimit-Limit: 20 X-Organization-RateLimit-Remaining: 19 X-Organization-RateLimit-Reset: 1469560440

  • X-Organization-RateLimit-Limit is the number of requests allowed for your organization in a 60-second period.
  • X-Organization-RateLimit-Remaining is the number of requests remaining in the current 60-second period.
  • X-Organization-RateLimit-Reset is the UTC timestamp of the next rate limit rollover.

Instant tests are governed through a separate set of throttling controls, and allow up to 24 calls per minute. Instant test rate limit headers can be found below:

X-Instant-Test-RateLimit-Limit: 2 X-Instant-Test-RateLimit-Remaining: 1 X-Instant-Test-RateLimit-Reset: 1469560440

As above:

  • X-Instant-Test-RateLimit-Limit is the number of requests allowed for your organization in a 60-second period.
  • X-Instant-Test-RateLimit-Remaining is the number of requests remaining in the current 60-second period.
  • X-Instant-Test-RateLimit-Reset: is the UTC timestamp of the next rate limit rollover.

If you are receiving an HTTP/429 (Too many requests) response code, your request was refused on the basis of a rate limit. Wait until either X-Organization-RateLimit-Reset value or the X-Instant-Test-RateLimit-Reset value (as appliable based on the type of request you are submitting) before submitting another request.

For error responses, see the response status codes documentation.

Source IP block

When a 100 or more unauthorized requests (resulting in the 401 UNAUTHORIZED response) are issued from a given source IP address within a minute, API server will start responding with the 429 TOO MANY REQUESTS response code. Your API script should handle 401 UNAUTHORIZED error and prevent further requests to avoid the source IP block.

Pagination

The ThousandEyes API returns data in paginated format, where the time window requested exceeds 1 hour. For requests showing current values, or less than 1 hour’s worth of data, all data will be presented in a single page.

Look for the pages element in your response to find links to subsequent pages of result data. The pages[next] and pages[previous] elements will contain URLs to the appropriate page of data. Note that where relative windows are requested, our API translates these windows into exact times, since it may take time to iterate through several pages of response data.

  • if pages[next] is present, there is more data available. If not, you are on the last page of data.
  • if pages[previous] is present, you can traverse back to that page in your result set. if it is missing, that is an indication that you are on the first page of data.

A sample of a response including pages is shown below:

Request

$ curl -i https://api.thousandeyes.com/v6/web/page-load/818.json?window=10d \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

The main object can be ignored in this request. Note a few things:

  • The requested window was > 1h, which forced pagination. The length of time required to cause pagination varies based on the number of agents on a test, and the number of records returned per agent. For example, DNS Server tests are more verbose than page load tests, because they typically query multiple nameservers per agent.
  • If the result set exceeds one page worth of data, next and previous URLs will be shown in the pages section of data. If the time range requested in the query was specified in a window format, it will be converted to from and to format (based on the original query time), to prevent missing data as you iterate through your result set.

HTTP/1.1 200 OK Server: nginx Date: Wed, 19 Apr 2017 13:08:30 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: 1492607340 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-4

Body

{ "from": "2013-11-08 15:30:00", "to": "2013-11-08 17:45:00", "web": {...} "pages": { "next": "https://api.thousandeyes.com/v6/web/page-load/818.json?page=3&from=2013-10-29+17%3A30%3A00&to=2013-11-08+17%3A45%3A00", "previous": "https://api.thousandeyes.com/v6/web/page-load/818.json?page=1&from=2013-10-29+17%3A30%3A00&to=2013-11-08+17%3A45%3A00", "current": 2 } }

For error responses, see the response status codes documentation.

Sandbox

For many people, working with an API requires that you look at some sample data – at least, that’s how we learn, so we want to extend you the same courtesy.

If you want to play around with the API and understand the data in the system, use the API Sandbox account.

We’ve made available an account which can be used to access the ThousandEyes API, and all documentation references made in the ThousandEyes developer reference are based on content extracted from the Sandbox account, to allow you contextual cues and information.

The following username and authToken can be used to authenticate with our API.

  • Username: noreply@thousandeyes.com
  • AuthToken: g351mw5xqhvkmh1vq6zfm51c62wyzib2

Users don’t have permissions to make changes to settings and/or tests in the account, but can leverage this account for working with the methods provided by the API, and understanding the data.

Change policy

ThousandEyes may modify the attributes and resources available to the API and our policies related to access and use of the API from time to time without advance notice. ThousandEyes will use commercially reasonable efforts to notify you of any modifications to the API or policies through notifications or posts on the ThousandEyes Customer Success Center. ThousandEyes also tracks deprecation of attributes of the API on the ThousandEyes API page, located on this site.

ThousandEyes will provide an update to the version of the API in circumstances where the structure of the API output substantively changes, format is modified, or code is deprecated.

Version Support

Support for the current and prior version of the ThousandEyes API will be provided at all times. Attempts to access the ThousandEyes API with no version specified will result in the current version being used. Attempts to access a deprecated version of the API will result in a response from the oldest supported version of the API.

WARNING

API default version cutover is scheduled for our September 27, 2017 release. Cutover will move the default (no version specified) from v5 to v6. Please update your code accordingly.

API version 6 is in preview mode at the moment, but has been frozen. Cutover for the “current” version of the API will be during our release on September 27, 2017. Version 5 is presently the current release. Based on our support statement, we support the following releases, accessible at the endpoint root specified:

  • version 6 (preview): https://api.thousandeyes.com/v6/
  • version 5 (current): https://api.thousandeyes.com/v5/, https://api.thousandeyes.com/
  • version 4 (current-1): https://api.thousandeyes.com/v4/

Support Notice

New versions of the API will be released with a notification made available on our Developer reference site, and will be available using a version-specific endpoint call for a period of 90 days. After this 90-day period, the new version of the API will become the current version, and the oldest version of the API will be deprecated.

This means that the following timeline applies:

  • Upon release of new API version v(X), for first 90 days:

    • Current version: v(X-1)
    • Supported versions: v(X-2)-v(X)
  • After 90 days post-release of new API version

    • Current version: v(X)
    • Supported versions: v(X-1)-v(X)

API change summary

The following list documents a running list of changes to version 6 of the ThousandEyes API. Each release date is linked to the specific release notes for that release, for which Authentication is required. For details related to other versions of the ThousandEyes API, see the links on the left sidebar.

APIv6

July 7, 2017 * (added) Activity Log endpoint: /audit/user-events/search

June 7, 2017

  • (added) Agent Detail endpoint now provides Enterprise Cluster utilization
  • (announced) destructive change freeze for APIv6 - after today’s release, no future changes will result in a destructive change to the schema.
  • (revised announcement) 90-day countdown for APIv6 moving to default begins June 7, 2017, with a target date of September 13, 2017. Please refer to the versioning page for details.

April 26, 2017

  • (added) Agent Notification Rules endpoint: /agent-notification-rules
  • (added) Agent Notification Rule Detail endpoint: /agent-notification-rules/{ruleId}
  • (announced) target date for change of current API version is May 24, 2017. Current version will be changed from v5 to v6, and 90-day clock for APIv4 has started.

April 26, 2017

  • (added) Agent Notification Rules endpoint: /agent-notification-rules
  • (added) Agent Notification Rule Detail endpoint: /agent-notification-rules/{ruleId}
  • (announced) target date for change of current API version is May 24, 2017. Current version will be changed from v5 to v6, and 90-day clock for APIv4 has started.

April 12, 2017

  • (changed) alert rules endpoint changed: removed recipients from this endpoint in favor of adding /alert-rules/{ruleId} endpoint, which lists alert recipients of all types, including Slack, Hipchat, PagerDuty and generic webhooks
  • (added) Alert rule detail endpoint: /alert-rules/{ruleId}
  • (added) Alert Suppression Window list /alert-suppression-windows
  • (added) Alert Suppression Window detail /alert-suppression-windows/{alertSuppressionWindowId}
  • (added) Alert Suppression Window creation /alert-suppression-windows/new
  • (added) Alert Suppression Window deletion /alert-suppression-windows/{alertSuppressionWindowId}/delete endpoint
  • (added) Alert Suppression Window modification /alert-suppression-windows/{alertSuppressionWindowId}/update endpoint
  • (added) integrations list endpoint /integrations
  • (added) Endpoint user session list /endpoint-data/user-sessions
  • (added) Endpoint user session details /endpoint-data/user-sessions/{sessionId}
  • (added) Endpoint web page list /endpoint-data/user-sessions/{sessionId}/web
  • (added) Endpoint web page details /endpoint-data/user-sessions/{sessionId}/page/{pageId}
  • (added) Endpoint network sessions list /endpoint-data/user-sessions/{sessionId}/network
  • (added) Endpoint network topology list /endpoint-data/network-topology
  • (added) Endpoint network topology detail /endpoint-data/network-topology/{networkProbeId}
  • (added) Endpoint agent list /endpoint-agents/
  • (added) Endpoint agent details /endpoint-agents/{agentId}
  • (added) Endpoint networks /endpoint-data/networks
  • (added) several report snapshot list /report-snapshots
  • (added) several report snapshot detail /report-snapshots/{snapshotId}
  • (added) several report snapshot data /report-snapshots/{snapshotId}/{dataComponentId}
  • (added) several report snapshot deletion /report-snapshots/{snapshotId}/delete
  • (changed) removed BETA badge from reports endpoints (no longer in beta)

March 15, 2017

  • (added) Instant Tests 2.0 documentation is now available
  • (added) documentation for FTP server tests to /web/ftp-server/{testId}
  • (fixed) some metadata in table listed in the Transaction Detail endpoint was offset by a column.

November 23, 2016

  • (added) /reports endpoint
  • (added) /reports/{reportId} endpoint
  • (added) /reports/{reportId}/{dataComponentId} endpoint
  • (fixed) problems with setting advanced options on some test creation endpoints
  • (added) pingPayloadSize field added to network tests
  • (added) lastLogin field to /users endpoint
  • (added) dateRegistered field to /users endpoint
  • (added) oAuth support for API queries: see Authentication for more details.

August 31, 2016

  • (added) /tests/ftp-server endpoint added (filter all tests on FTP server tests)
  • (added) /web/ftp-server/{testId} endpoint added (return results for FTP server tests)
  • (added) X-Organization-RateLimit-Limit, X-Organization-RateLimit-Remaining, and X-Organization-RateLimit-Reset headers added to requests to handle rate limit control
  • (added) followRedirects (boolean) element to HTTP Server tests

July 20, 2016

  • (changed) added no-cache directive to responses from the ThousandEyes API to prevent content from being cached on proxy servers
  • (added) dnsOverride, clientCertificate desiredStatusCode advanced options for HTTP Server test setting endpoints

July 6, 2016

  • (changed) moved type attribute of XML representation of alerts endpoint to a child element.
  • (changed) fetchTime in HTTP Server results endpoint changed to totalTime
  • (added) implemented burst limit for instant test API calls
  • (changed) calling /net/path-vis/{testId} and /net/path-vis/{testId}/{agentId}/{roundId} for agent to agent tests with direction parameter of BIDIRECTIONAL will now throw an error (http/400 status code)
  • (added) agent hostname to /agents and /agents/{agentId} endpoints
  • (changed) roundsBeforeTrigger field has been removed from alert rules, and replaced with roundsViolatingRequired and roundsViolatingOutOf, respectively.

June 8, 2016

  • (added) countryID field to /net/metrics endpoint
  • (added) errorDetails field to /net/metrics endpoint
  • (fixed) changed default behavior when querying /net/metrics and /net/path-vis endpoints for agent to agent tests. In the case of bidirectional tests, the /net/metrics endpoint will return aggregate information for both directions - specifying a direction as a querystring parameter direction=[FROM_TARGET | TO_TARGET] will return that direction’s metrics specifically. For the /net/path-vis endpoint, each direction must be queried independently. Specifying an invalid direction will result in an error response.

May 25, 2016

  • Preview for APIv6 launched
  • (changed) Accounts are now shown as account-groups. The /accounts endpoint has been replaced with /account-groups
  • (changed) Network tests have been replaced with agent-to-server tests, and agent-to-agent tests. This is now reflected under the type field for tests
  • (added) /tests/agent-to-server endpoint
  • (added) /tests/agent-to-agent endpoint
  • (removed) /tests/network endpoint
  • (added) direction parameter to results endpoints (net/metrics, net/path-vis) for agent-to-agent tests
  • (added) Account Group, Role, and User management endpoints
  • (added) Usage endpoint