Consent Manager

  • Your Privacy

  • Strictly Necessary Cookies

  • Performance Cookies

  • Targeting Cookies

  • Functional Cookies

Your Privacy

When you visit any website, it may store or retrieve information on your browser, mostly in the form of cookies. This information might be about you, your preferences or your device and is mostly used to make the site work as you expect it to. The information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies. Click on the different category headings to find out more and change our default settings. However, blocking some types of cookies may impact your experience of the site and the services we are able to offer. For more information on the information we collect and how we use it see the Website Privacy Statement.

Strictly Necessary Cookies

Always Active

These cookies are necessary for the website to function and cannot be switched off in our systems. They are usually only set in response to actions made by you which amount to a request for services, such as setting your privacy preferences, logging in or filling in forms. You can set your browser to block or alert you about these cookies, but some parts of the site will not then work. These cookies do not store any personally identifiable information.

Performance Cookies

Off On

These cookies allow us to count visits and traffic sources so we can measure and improve the performance of our site. They help us to know which pages are the most and least popular and see how visitors move around the site. All information these cookies collect is aggregated and therefore anonymous. If you do not allow these cookies we will not know when you have visited our site, and will not be able to monitor its performance.

Targeting Cookies

Off On

These cookies may be set through our site by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant adverts on other sites. They do not store directly personal information, but are based on uniquely identifying your browser and internet device. If you do not allow these cookies, you will experience less targeted advertising.

Functional Cookies

These cookies enable the website to provide enhanced functionality and personalization. They may be set by us or by third party providers whose services we have added to our pages. If you do not allow these cookies then some or all of these services may not function properly.

Your Privacy [`dialog closed`]

By continuing to use our website, you acknowledge the use of cookies. Privacy Statement | Change Settings

Cookies allow us to optimise your use of our website. We also use third-party cookies for advertising and analytics. Please read our Privacy Statement and Website Privacy Statement for more information on how we use cookies.

This is a limited preview of our upcoming API version 7

DEVELOPER REFERENCE

Search Results

×Clear
  • Overview

    • Welcome
    • Authentication
    • Account group context
    • Response formats
    • Time ranges
    • Response status codes
    • Rate limits
    • Pagination
    • Change policy
    • API change summary
  • Administrative API

    • Administrative API
  • Agents

    • Agents
  • Alerts

    • Alerts
  • BGP Monitors

    • BGP Monitors
  • Credentials

    • Credentials
  • Dashboards

    • Dashboards
  • Endpoint Agents

    • Endpoint Agents
  • Endpoint Instant Tests

    • Endpoint Instant Tests
  • Endpoint Labels

    • Endpoint Labels
  • Endpoint Test Results

    • Endpoint Test Results
  • Endpoint Tests

    • Endpoint Tests
  • Internet Insights

    • Outages
  • Instant Tests

    • Instant Tests
  • Snapshots

    • Snapshots
  • Tags

    • Tags
  • Tests

    • Tests
  • Test Results

    • Test Results
  • Test Templates

    • Test Templates
  • ThousandEyes for OpenTelemetry

    • ThousandEyes for OpenTelemetry
  • Usage

    • Usage

  • APIv6  |  Showing APIv7 (preview)

  • Product Documentation
  • Customer Success Center
  • Public GitHub Repository

Try ThousandEyes Now! Sign Up

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.

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

$ curl https://api.thousandeyes.com/v7/status

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

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: application/hal+json;charset=UTF-8 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 OAuth2 bearer token as authentication methods. This is specified using the HTTP request wrapper of your choice. The OAuth2 Bearer Token referenced here and throughout the developer reference is available from your account settings page under the “Profile” tab, in the “User API Tokens” section.

The following example leverages cURL presenting a bearer token:

$ curl -i https://api.thousandeyes.com/v7/tags \ --header "Authorization: Bearer {authToken}"

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. When leveraging the bearer token, the token itself can be passed directly as a string:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 $apitoken = "{bearerToken}" $headers = @{"accept"= "application/json"; "content-type"= "application/json"; "authorization"= "Bearer " + $apitoken} $response = Invoke-WebRequest https://api.thousandeyes.com//v7/tags -Headers $headers $response.content

NOTE: The OAuth2 Bearer Token is available from your account settings page under the “Profile” tab, in the “User API Tokens” section.

Account Lockout

You account could be locked up due to a number of failed authentication attempts into the ThousandEyes application.

If attempts to reach the API are returning an 401 UNAUTHORIZED response code, but your credentials are correct it is possible that your account is locked up. Try logging into the App, it your account is locked up, you will be required to reset your password.

Source IP block

When 120 or more unauthorized requests (resulting in the 401 UNAUTHORIZED response) are issued from a given source IP address within an hour, 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.

For error responses, see the response status codes documentation.

GET /v7/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 group list endpoint.

Response formats

The ThousandEyes v7 API allows output in the following formats:

  • JSON (JavaScript Object Notation)

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:application/hal+json will return the response in HAL JSON

$ curl https://api.thousandeyes.com/v7/tags \ -u {email}:{authToken}

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 POST /tags endpoint
204NO CONTENTUsing the DELETE /tags 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-Rate-Limit-Limit: 20 X-Organization-Rate-Limit-Remaining: 19 X-Organization-Rate-Limit-Reset: 1469560440

  • X-Organization-Rate-Limit-Limit is the number of requests allowed for your organization in a 60-second period.
  • X-Organization-Rate-Limit-Remaining is the number of requests remaining in the current 60-second period.
  • X-Organization-Rate-Limit-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-Rate-Limit-Limit: 2 X-Instant-Test-Rate-Limit-Remaining: 1 X-Instant-Test-Rate-Limit-Reset: 1469560440

As above:

  • X-Instant-Test-Rate-Limit-Limit is the number of requests allowed for your organization in a 60-second period.
  • X-Instant-Test-Rate-Limit-Remaining is the number of requests remaining in the current 60-second period.
  • X-Instant-Test-Rate-Limit-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-Rate-Limit-Reset value or the X-Instant-Test-Rate-Limit-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.

Pagination

The ThousandEyes API returns data in paginated format, where the response exceeds a page of data. For requests showing current values, or less than a page 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] element will contain the URL to the next 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.

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

Version 6 is presently the current release. Based on our support statement, we support the following releases, accessible at the endpoint root specified:

  • version 7 (limited preview): https://api.thousandeyes.com/v7/
  • version 6 (current): https://api.thousandeyes.com/v6/, https://api.thousandeyes.com/

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

APIv7

July 24, 2023

  • (updated) the alertId attribute in the alerts and alertdetail API has been converted from an integer to a string. This update takes effect from 1 August, 2023.

May 11, 2023

  • (added) New ThousandEyes for OpenTelemetry API endpoints, at /v7/stream
  • (added) New Test Template API endpoints, at /v7/tests/templates
  • (added) New Tags API endpoints, at /v7/tags

February 14, 2023

  • (removed) id attribute in alerts and alertdetail api
  • (added) new attribute id in alert and alert details api response to represent 128-bit alphanumeric UUID of alert

January 13, 2023

  • (removed) Alert-Grid widget has now been removed from the platform and from snapshots

October 10, 2022

  • (removed) Reports v7 API is deprecated when dashboards and reports merge.

June 24, 2020

  • (added) Alert details endpoint now returns list of affected tests for network-outage alerts

April 28, 2020

  • (added) New alert endpoints added, at /v7/alerts, with support for Internet Insights outage alerts

February 04, 2020

  • (added) New dashboard endpoints, at /v7/dashboard

November 26, 2019

  • (updated) Path visualization endpoint now returns complete data at once

October 15, 2019

  • (updated) Reports endpoints have been updated with new functionality and structure, at /v7/reports

October 01, 2019

  • Preview for APIv7 launched

March 29, 2023

  • (added) New dashboard endpoint, at /v7/dashboard, for updating expiration date of a snapshot

June 1, 2023

  • (updated) Restored missing documentation for traditional report widgets in /v7/dashboard.
© 2023 ThousandEyes. All rights reserved.