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/status

Output

{"timestamp":1383931010006}

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

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

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

Output

HTTP/1.1 200 OK Date: Fri, 08 Nov 2013 17:16:50 GMT Server: Apache/2.2.22 (Ubuntu) Transfer-Encoding: chunked Content-Type: application/json;charset=UTF-8 {"timestamp":1383931010006}

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.

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:

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

The authentication 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

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.

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:

$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/agents.json -Headers $headers $response.content

NOTE: the “password” used by ThousandEyes basic HTTP authentication is the authToken, available from your account settings page.

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 /accounts Account Context

Users assigned to multiple account groups can change account context by using the aid={accountId} parameter. A list of account IDs can be found using the /accounts 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 account does not have sufficient permissions to access this resource. If the user specifies an invalid account 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/accounts \ -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/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 Date: Thu, 07 Nov 2013 07:32:48 GMT Server: Apache/2.2.22 (Ubuntu) Transfer-Encoding: chunked Content-Type: application/json

Body

{ "account": [ { "aid": 353, "accountName": "Test Account Name #1", "current": 0, "default": 1 } { "aid": 354, "accountName": "Test Account Name #2", "current": 1, "default": 0 } { "aid": 355, "accountName": "Test Account Name #3", "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/tests.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

  • to request an XML response:

$curl https://api.thousandeyes.com/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/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/tests?format=json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Time Ranges

Most requests (check Optional Parameters section), 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.

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: from/to and window 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
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 inbound 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. These values are subject to change, as we work through identifying appropriate use patterns for our API.

If you are receiving an HTTP/429 (Too many requests) response code, your request was refused on the basis of a rate limit.

For error responses, see the response status codes documentation.

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/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 Date: Thu, 07 Nov 2013 07:32:48 GMT Server: Apache/2.2.22 (Ubuntu) Transfer-Encoding: chunked Content-Type: application/json

Body

{ "from": "2013-11-08 15:30:00", "to": "2013-11-08 17:45:00", "web": {...} "pages": { "next": "https://api.thousandeyes.com/v5/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/v5/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 I 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.

API version 6 is in preview mode at the moment, and cutover to version 6 will be May 24, 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 5 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.

APIv5

June 8, 2016

  • (fixed) added countryId to /net/metrics endpoint
  • (added) errorDetails field is now exposed to /net/metrics endpoint

May 25, 2016

  • updated change policy section (v4) to show that version 6 is in preview mode and accessible
  • updated change policy section (v5) to show that version 6 is in preview mode and accessible

March 30, 2016

  • (added) groups endpoints
  • (added) groups metadata to agent and test endpoints

December 16, 2015

  • (added) OrganizationName field in to /accounts endpoint output when users are subscribed to multiple organizations
  • (changed) made some minor terminology updates to test metadata descriptions.

October 14, 2015

  • (added) Added support for transactionScript output in transaction test retrieval
  • (added) Added support for transactionScript input in transaction test creation and update
  • (added) Added two new fields, startStep and endStep in transaction test retrieval, creation and update

August 5, 2015

  • (added) Web transactions now support programmatic test creation. Refer to the test metadata page for more information on using the new field.
  • (changed) corrected minor markdown formatting errors

July 22, 2015

  • (changed) format of /agents and /agents/{agentId} endpoint
  • (changed) corrected minor markdown formatting errors

June 10, 2015

  • (removed) API versions 2 and 3 have both been deprecated
  • (changed) v5 is now the default version for API requests made without requesting an explicit version.

May 27, 2015

  • (added) added agents/{agentId}/update endpoint
  • (added) added agents/{agentId}/delete endpoint
  • (fixed) agents/{agentId} endpoint now returns only tests assigned to the agent in the current account context. Prior to the fix, all tests were being shown
  • (fixed) date fields have been added back to the /alerts endpoint when using XML-based output. Prior to the fix, these fields were missing.

May 13, 2015

  • (added) added monitorId to /net/bgp-metrics/{testId} endpoint.
  • (added) added /agents/{agentId} endpoint.
  • (updated) documentation for agents and alerts category now shows a table of possible fields returned in the data
  • (updated) removed beta flag for Voice tests

March 4, 2015

  • OFFICIAL RELEASE OF APIv5
  • (changed) savedEvent and enabled fields have been converted from attributes to elements in XML output format for the API.
  • (changed) version-specific XML schema documents (.xsd files) are now being generated for each version of the API. Refer to the Response Formats heading for more details.
  • (added) the /agents endpoint has been updated. Added new fields and modified existing fields related to ipAddresses.
  • (added) bgpMonitors field is now modifiable on tests via the API.
  • (changed) renamed includeSubPrefixes field to includeCoveredPrefixes

January 21, 2015

  • (fixed) documentation errors on test metadata page related to agents array.
  • (added) redirectTime field on HTTP Server output
  • (changed) test updates (fields modifiable via the API) now require the test to be enabled, in order to commit a change.
  • (added) /bgp-monitors endpoint (APIv5 only)

October 29, 2014

  • (added) roundsBeforeTrigger field to alert Rules
  • (fixed) issues retreiving page load data for saved events
  • (added) saved events page added to tests category

October 15, 2014