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.

DEVELOPER REFERENCE

Search Results

×Clear

  • Overview
    • Welcome
    • Authentication
    • Account Context
    • Response Formats
    • Time Ranges
    • Response Status Codes
    • Rate Limits
    • Pagination
    • Change Policy
    • API Change Summary

  • Tests
    • Test List
    • Test List by Type
    • Test Details
    • Test Metadata
    • Creating a Test
    • Updating a Test
    • Deleting a Test
    • Saved Events

  • Test Data
    • (Network) End-to-End Metrics
    • (Network) Path Visualization
    • (Network) Detailed Path Trace
    • (Network) BGP Metrics
    • (Network) BGP Route Information
    • (Web) HTTP Server
    • (Web) Page Load
    • (Web) Page Load Component Detail
    • (Web) Transactions
    • (Web) Transaction Detail
    • (Web) Transaction Component Detail
    • (DNS) Domain Trace
    • (DNS) Server Metrics
    • (DNS) DNSSEC
    • (Voice) Metrics

  • Agents & Monitors
    • Agent List
    • Agent Details
    • Updating an Agent
    • Deleting an Agent
    • BGP Monitor List

  • Alerts
    • Alert Rules
    • Active Alerts
    • Alert Detail

  • Labels
    • Labels List
    • Labels list by type
    • Label details
    • Label details (by label type)
    • Creating a label
    • Updating a label
    • Deleting a label

  • User Management
    • Account Groups List
  • APIv6  |  APIv7 (preview)
  • Product Documentation
  • Customer Success Center
  • Public GitHub Repository
Try ThousandEyes Now! Sign Up

Tests

GET /v5/tests Test List

Returns a list of all tests configured in ThousandEyes. Also returns data for saved events, which are indicated by a boolean field, "savedEvent": 1

Optional Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={accountId} optional and requires the user to be assigned to the target account, specifies the account context of the request, obtained from the /accounts endpoint. Specifying this parameter without the user to be assigned to the target account will result in an error response. See Account Context for more information

Request

  • no request body

Response

Sends back an array of tests. See Test Metadata page for information on fields returned by this endpoint.

Example

$curl https://api.thousandeyes.com/v5/tests.json \ -u {email}:{authToken}

Header

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

{ "test": [ { "enabled": 1, "testId": 817, "savedEvent": 0, "liveShare": 0, "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": [...] }, ... ] }

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

GET /v5/tests/{testType} Test List by Type

Returns a list of all tests of the type specified, configured in ThousandEyes. Also returns data for saved events, which are indicated by a boolean field, "savedEvent": 1

Optional Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={accountId} optional and requires the user to be assigned to the target account, specifies the account context of the request, obtained from the /accounts endpoint. Specifying this parameter without the user to be assigned to the target account will result in an error response. See Account Context for more information

Request

  • {testType} corresponds to any of the following options:

    • network
    • bgp
    • http-server
    • page-load
    • transactions
    • dns-trace
    • dns-server
    • dns-dnssec
    • voice

  • no request body

Example

$curl https://api.thousandeyes.com/v5/tests/http-server.json \ -u {email}:{authToken}

Response

Sends back an array of tests of that type. See Test Metadata page for information on fields returned by this endpoint.

Header

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

{ "test": [ { "enabled": 1, "testId": 817, "testName": "http://www.thousandeyes.com", "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": [...] } ] }

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

GET /v5/tests/{testId} Test Details

Returns a details for a test, including test type, name, intervals, targets, alert rules and agents.

Optional Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={accountId} optional and requires the user to be assigned to the target account, specifies the account context of the request, obtained from the /accounts endpoint. Specifying this parameter without the user to be assigned to the target account will result in an error response. See Account Context for more information

Request

  • {testId} the ID of the test you wish to retrieve

Response

Sends back all metadata for the requested test. See Test metadata page for more information on fields returned by this endpoint.

Example

$curl https://api.thousandeyes.com/v5/tests/817.json \ -u {email}:{authToken}

Header

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

{ "test": [ { "enabled": 1, "savedEvent": 0, "liveShare": 0, "testId": 817, "testName": "http://www.thousandeyes.com", "type": "http-server", "interval": 900, "url": "http://www.thousandeyes.com", "alertsEnabled": 1, "alertRules": [ { "ruleId": 302, "ruleName": "BGP alert rule", "expression": "((reachability < 100%) && (changes > 0))", "recipient": [ "API Sandbox User (noreply@thousandeyes.com)" ], "alertType": "BGP" } ], "agents": [ { "agentId": 12, "agentName": "Hong Kong", "location": "Hong Kong", "countryId": "HK", "ipAddresses": [ "124.248.207.183" ], "prefix": "124.248.207.0/24", "network": "SunnyVision Limited (AS 38478)", "agentType": "Cloud }, ... ], "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": [...] } ] }

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

Test Metadata

Test fields are shown in the table below, by type. The table indicates whether the fields can be used in test creation, updates, or simply in returning data. As a reminder, in order to create a new test, the user attempting the creation must be an Account Admin; Regular users are blocked from using any of the POST-based methods.

Fields are listed alphabetically by test type below.

Where a field indicates n/a for both Test Creation and Test Update, these fields are system-generated and read only, and displayed as part of test metadata.

Test TypeFieldTest CreationTest UpdateData TypeAcceptable ValuesNotes
(all)alertsEnabledOptionalOptionalinteger0 or 1choose 1 to enable alerts, or 0 to disable alerts. Defaults to 1
(all)alertRulesOptionalOptionalarray of alert rule objects {“ruleId”: ruleId}see notesget ruleId from /alert-rules endpoint. If alertsEnabled is set to 1 and alertRules is not included in a creation/update query, applicable defaults will be used.
(all)apiLinksn/an/aarray of apiLinks objectsarray of apiLink objects, showing rel and href elementsRead only; self links to endpoint to pull test metadata, and data links to endpoint for test data
(all)createdByn/an/astringUsername (email@company.com)read only
(all)createdDaten/an/astringYYYY-MM-DD HH:mm:ss formatted dateread only; shown in UTC
(all)enabledn/aOptionalinteger0 or 1choose 1 to enable the test, 0 to disable the test
(all)groupsOptionalOptionalarray of label objects ("groups": [ { "name": "groupName", "groupId": groupId, "builtIn": 0}])see notesget groupId from /groupsendpoint.
(all)liveSharen/an/ainteger0 or 1read only; indicates 1 for a test shared with your account, 0 for a normal test
(all)modifiedByn/an/astringUsername (email@company.com)read only
(all)modifiedDaten/an/astringYYYY-MM-DD HH:mm:ss formatted dateread only; shown in UTC
(all)savedEventn/an/ainteger0 or 1read only; indicates 1 for a saved event, 0 for a normal test
(all)testIdn/an/aintegerunique ID of testread only; each test is assigned a unique ID; this is used to access test data from other endpoints.
(all)testNameRequiredOptionalstring(any)Test name must be unique
(all)typen/an/astringtype of test being queriedThis is a read only value, as test type is implicit in the test creation url.
NetworkprotocolOptionaln/astringTCP or ICMPprotocol and port (shown below) are mutually exclusive - if ICMP is selected and port is provided, the request will error; defaults to TCP
HTTP Server, DNS Server, Page LoadprotocolOptionalOptionalstringTCP or ICMPprotocol used by dependent Network tests (End-to-end, Path Trace, PMTUD); defaults to TCP
BGPbgpMonitorsOptionalOptionalarray of BGP Monitor objects {“monitorId”: monitorId}see notesGet monitorId from /bgp-monitors endpoint. If a public monitor is included in the bgpMonitors list on test creation/update, all public monitors will be assigned to the test, regardless of the setting specified in the usePublicBgp parameter.
BGPusePublicBgpOptionalOptionalinteger0 or 1set to 1 to automatically add all available Public BGP Monitors
BGPincludeCoveredPrefixesOptionalOptionalinteger0 or 1set to 1 to include queries for subprefixes detected under this prefix
BGPprefixRequiredn/astringa.b.c.d/ea.b.c.d is a network address, with the prefix length defined as e. Prefixes can be any length from 8 to 24
DNS ServeragentsRequiredOptionalarray of agent objects {“agentId”: agentId}see notesget agentId from /agents endpoint
DNS ServerbandwidthMeasurementsOptionalOptionalinteger0 or 1set to 1 to measure bandwidth. Only applies to Enterprise Agents assigned to the test, and requires that networkMeasurements is set. We do not recommend setting this flag on DNS server tests
DNS ServerbgpMeasurementsOptionalOptionalinteger0 or 1choose 1 to enable bgp measurements, 0 to disable; defaults to 1 when networkMeasurements is set
DNS ServerbgpMonitorsOptionalOptionalarray of BGP Monitor objects {“monitorId”: monitorId}see notesget monitorId from /bgp-monitors endpoint.
DNS ServerdnsServersRequiredOptionalarray of DNS Server objects {“serverName”: “fqdn of server”}
DNS ServerdomainRequiredn/astringsee notestarget record for test, suffixed by record type (ie, www.thousandeyes.com CNAME). If no record type is specified, the test will default to an ANY record.
DNS ServerintervalRequiredOptionalinteger[300, 600, 900, 1800, 3600]value in seconds
DNS ServermtuMeasurementsOptionalOptionalinteger0 or 1set to 1 to measure MTU sizes on network from agents to the target
DNS ServernetworkMeasurementsOptionalOptionalinteger0 or 1choose 1 to enable network measurements, 0 to disable; defaults to 1
DNS ServerrecursiveQueriesOptionalOptionalinteger0 or 1set to 1 to run query with RD (recursion desired) flag enabled
DNS TraceagentsRequiredOptionalarray of agent objects {“agentId”: agentId}see notesget agentId from /agents endpoint
DNS TracedomainRequiredn/astringsee notestarget record for test, suffixed by record type (ie, www.thousandeyes.com CNAME). If no record type is specified, the test will default to an ANY record.
DNS TraceintervalRequiredOptionalinteger[300, 600, 900, 1800, 3600]value in seconds
DNSSECagentsRequiredOptionalarray of agent objects {“agentId”: agentId}see notesget agentId from /agents endpoint.
DNSSECdomainRequiredn/astringsee notestarget record for test, followed by record type (ie, www.thousandeyes.com A)
DNSSECintervalRequiredOptionalinteger[300, 600, 900, 1800, 3600]value in seconds
HTTP ServeragentsRequiredOptionalarray of agent objects {“agentId”: agentId}see notesget agentId from /agents endpoint.
HTTP ServerauthTypeOptionalOptionalstringNONE, BASIC, NTLM, KERBEROSHTTP Authentication type; defaults to NONE
HTTP ServerbandwidthMeasurementsOptionalOptionalinteger0 or 1set to 1 to measure bandwidth. Only applies to Enterprise Agents assigned to the test, and requires that networkMeasurements is set.
HTTP ServerbgpMeasurementsOptionalOptionalinteger0 or 1choose 1 to enable bgp measurements, 0 to disable; defaults to 1 when networkMeasurements is set
HTTP ServerbgpMonitorsOptionalOptionalarray of BGP Monitor objects {“monitorId”: monitorId}see notesget monitorId from /bgp-monitors endpoint.
HTTP ServercontentRegexOptionalOptionalstringRegular ExpressionsThis field does not require escaping
HTTP ServerdownloadLimitOptionalOptionalintegeranyspecify maximum number of bytes to download from the target object
HTTP ServerheadersOptionalOptionalarray of header strings [“header: value”, “header2: value”]anyuse HTTP header values in this list
HTTP ServerhttpTargetTimeOptionalOptionalinteger(100..5000)target time for HTTP server completion; specified in milliseconds
HTTP ServerhttpTimeLimitOptionalOptionalinteger(5..60)defaults to 5 seconds
HTTP ServerintervalRequiredOptionalinteger[120, 300, 600, 900, 1800, 3600]value in seconds
HTTP ServermtuMeasurementsOptionalOptionalinteger0 or 1set to 1 to measure MTU sizes on network from agents to the target
HTTP ServernetworkMeasurementsOptionalOptionalinteger0 or 1choose 1 to enable network measurements, 0 to disable; defaults to 1
HTTP ServerpasswordOptionalOptionalstringsee notespassword to be used for Basic/NTLM authentication
HTTP ServerpostBodyOptionalOptionalstringsee notesEnter the post body in this field. No escaping is required. If the post body is set to something other than empty, the requestMethod will be set to POST.
HTTP ServersslVersionRead onlyRead Onlystringcorresponds to sslVersionIdReflects the verbose ssl protocol version used by a test
HTTP ServersslVersionIdOptionalOptionalinteger[0,3,4,5,6]0 for auto, 3 for SSLv3, 4 for TLS v1.0, 5 for TLS v1.1, 6 for TLS v1.2
HTTP ServerurlRequiredn/astringsee notestarget for the test
HTTP ServeruseNtlmOptionalOptionalinteger0 or 1choose 1 to use NTLM, 0 to use Basic Authentication. Requires username/password to be set
HTTP ServeruserAgentOptionalOptionalstringsee notesuser-agent string to be provided during the test
HTTP ServerusernameOptionalOptionalstringsee notesusername to be used for Basic/NTLM authentication
HTTP SerververifyCertificateOptionalOptionalinteger0 or 1set to 0 to ignore certificate errors (defaults to 1)
NetworkagentsRequiredOptionalarray of agent objects {“agentId”: agentId}see notesget agentId from /agents endpoint.
NetworkbandwidthMeasurementsOptionalOptionalinteger0 or 1set to 1 to measure bandwidth. Only applies to Enterprise Agents assigned to the test
NetworkbgpMeasurementsOptionalOptionalinteger0 or 1choose 1 to enable bgp measurements, 0 to disable; defaults to 1
NetworkbgpMonitorsOptionalOptionalarray of BGP Monitor objects {“monitorId”: monitorId}see notesget monitorId from /bgp-monitors endpoint.
NetworkintervalRequiredOptionalinteger[120, 300, 600, 900, 1800, 3600]value in seconds
NetworkmtuMeasurementsOptionalOptionalinteger0 or 1set to 1 to measure MTU sizes on network from agents to the target
NetworkportOptionaln/ainteger(1..65535)if protocol is TCP, defaults to port 80. Protocol and port (shown below) are mutually exclusive - if ICMP is selected and port is provided, the request will error.
NetworkserverRequiredn/astring(any)target name or IP address
Page LoadagentsRequiredOptionalarray of agent objects {“agentId”: agentId}see notesget agentId from /agents endpoint
Page LoadauthTypeOptionalOptionalstringNONE, BASIC, NTLM, KERBEROSHTTP Authentication type; defaults to NONE
Page LoadbandwidthMeasurementsOptionalOptionalinteger0 or 1set to 1 to measure bandwidth. Only applies to Enterprise Agents assigned to the test, and requires that networkMeasurements is set
Page LoadbgpMeasurementsOptionalOptionalinteger0 or 1choose 1 to enable bgp measurements, 0 to disable; defaults to 1 when networkMeasurements is set
Page LoadbgpMonitorsOptionalOptionalarray of BGP Monitor objects {“monitorId”: monitorId}see notesget monitorId from /bgp-monitors endpoint.
Page LoadhttpIntervalRequiredOptionalinteger[120, 300, 600, 900, 1800, 3600]Cannot be larger than the interval value; defaults to the same value as interval
Page LoadhttpTargetTimeOptionalOptionalinteger(100..5000)target time for HTTP server completion; specified in milliseconds
Page LoadhttpTimeLimitOptionalOptionalinteger(5..60)defaults to 5 seconds
Page LoadincludeHeadersOptionalOptionalinteger0 or 1set to 1 to capture response headers for objects loaded by the test. Default is 1.
Page LoadintervalRequiredOptionalinteger[120, 300, 600, 900, 1800, 3600]value in seconds
Page LoadmtuMeasurementsOptionalOptionalinteger0 or 1set to 1 to measure MTU sizes on network from agents to the target
Page LoadnetworkMeasurementsOptionalOptionalinteger0 or 1choose 1 to enable network measurements, 0 to disable; defaults to 1
Page LoadpageLoadTargetTimeOptionalOptionalinteger(1..30)target time for Page Load completion; specified in seconds; cannot exceed pageLoadTimeLimit value
Page LoadpageLoadTimeLimitOptionalOptionalinteger(5..MIN(0.25 * interval, 60)must be larger than httpTimeLimit; defaults to 10 seconds
Page LoadpasswordOptionalOptionalstringsee notespassword to be used for Basic/NTLM authentication
Page LoadsslVersionRead onlyRead Onlystringcorresponds to sslVersionIdReflects the verbose ssl protocol version used by a test
Page LoadsslVersionIdOptionalOptionalinteger[0,3,4,5,6]0 for auto, 3 for SSLv3, 4 for TLS v1.0, 5 for TLS v1.1, 6 for TLS v1.2
Page LoadurlRequiredn/astringsee notestarget for the test
Page LoaduseNtlmOptionalOptionalinteger0 or 1choose 1 to use NTLM, 0 to use Basic Authentication. Requires username/password to be set
Page LoaduserAgentOptionalOptionalstringsee notesuser-agent string to be provided during the test
Page LoadusernameOptionalOptionalstringsee notesusername to be used for Basic/NTLM authentication
Page LoadverifyCertificateOptionalOptionalinteger0 or 1set to 0 to ignore certificate errors (defaults to 1)
TransactionagentsRequiredOptionalarray of agent objects {“agentId”: agentId}see notesget agentId from /agents endpoint.
TransactionauthTypeOptionalOptionalstringNONE, BASIC, KERBEROSHTTP Authentication type; defaults to NONE
TransactionincludeHeadersOptionalOptionalinteger0 or 1set to 1 to capture response headers for objects loaded by the test. Default is 1.
TransactionintervalRequiredOptionalinteger[300, 600, 900, 1800, 3600]value in seconds
TransactionpasswordOptionalOptionalstringsee notespassword to be used for Basic/NTLM authentication
TransactiontargetTimeOptionalOptionalinteger(1..60)target time for completion, defaults to 50% of time limit; specified in seconds
TransactiontimeLimitOptionalOptionalinteger(5..MIN(0.25 * interval, 180))time limit for transaction; defaults to 30s
TransactionuserAgentOptionalOptionalstringsee notesuser-agent string to be provided during the test
TransactionusernameOptionalOptionalstringsee notesusername to be used for Basic/NTLM authentication
TransactionurlRequiredRead Onlystringsee notestarget for the test
TransactiontransactionScriptOptional (see notes)Optional (see notes)stringsee notesHTML version of a transaction script. Quotes must be escaped (precede " characters with \). To obtain a transaction script for upload, click the Export as file option from the ThousandEyes Recorder. Note that this field is write-only and can only be used on test creation.
TransactiontransactionStepsOptional (see notes)Optional (see notes)array of transactionStep objects.see transactionSteps.<field> values belowEither transactionSteps or transactionScript can be specified. If transactionSteps is specified, then this value will override any transactionScript field supplied in the call
TransactiontransactionSteps.stepNumRequiredOptionalintegerZero-indexed step number.Steps must be provided sequentially, and must start at zero
TransactiontransactionSteps.stepNameRequiredOptionalstringsee notesname for the step
TransactiontransactionSteps.commandRequiredOptionalstringsee notescommand for the step
TransactiontransactionSteps.targetRequiredOptionalstringsee notestarget for the step
TransactiontransactionSteps.valueOptionalOptionalstringsee notesif a value field is required as part of the transaction step (for example, a waitForCondition command), specify the value in this field. If no value is required, omit the value field.
TransactionstartStepOptionalOptionalintegerTransaction step number to begin the transaction timer - this is based on the zero-indexed stepNum field specified in transactionSteps.If omitted, the transaction will start at step 0 of the transaction script
TransactionendStepOptionalOptionalintegerTransaction step number to end the transaction timer - this is based on the zero-indexed stepNum field specified in transactionSteps.If omitted, the transaction will end at the last step in the transaction script
VoiceagentsRequiredOptionalarray of agent objects {“agentId”: agentId}see notesget agentId from /agents endpoint.
VoicebgpMeasurementsOptionalOptionalinteger0 or 1choose 1 to enable bgp measurements, 0 to disable; defaults to 1 when networkMeasurements is set
Voicecodecn/aRead Onlystringsee notescodec label
VoicecodecIdRequiredOptionalintegerVoice codec listsee list for acceptable values
Voicedscpn/aRead Onlystringsee notesdscp label
VoicedscpIdRequiredOptionalintegerDSCP listsee list for acceptable values
VoiceintervalRequiredOptionalinteger[300, 600, 900, 1800, 3600]value in seconds
VoicejitterBufferRequiredOptionalinteger(0..150)de-jitter buffer size (in seconds)
VoicemtuMeasurementsOptionalOptionalinteger0 or 1set to 1 to measure MTU sizes on network from agents to the target
VoicenetworkMeasurementsOptionalOptionalinteger0 or 1choose 1 to enable network measurements, 0 to disable; defaults to 1
VoicetargetAgentIdRequiredRead Onlyintegerpull from /agentsBoth the "agents": [] and the targetAgentId cannot be cloud agents. Can be Enterprise Agent -> Cloud, Cloud -> Enterprise Agent, or Enterprise Agent -> Enterprise Agent

POST /v5/tests/{testType}/new Creating a Test

Creates a new test in ThousandEyes, based on properties provided in the POST data. In order to create a new test, the user attempting the creation must be an Account Admin.

Regular users are blocked from using any of the POST-based methods.

Note: When creating or updating a test and assigning alert rules, that alert rules are based on specific measurements being available. For example, when creating an HTTP server test with network measurements disabled, you will not be able to assign any alert rules that are based on network metrics. The same applies to BGP measurements.

Optional Parameters

  • aid={accountId} optional and requires the user to be assigned to the target account, specifies the account context of the request, obtained from the /accounts endpoint. Specifying this parameter without the user to be assigned to the target account will result in an error response. See Account Context for more information

Request

  • {testType} corresponds to any of the following options:
  • bgp
  • network
  • http-server
  • page-load
  • transactions
  • dns-trace
  • dns-server
  • dns-dnssec
  • voice

See the Test Metadata page for fields available during test creation.

Response

If a test is successfully created, an HTTP/201 CREATED response will be returned, and the test definition will be returned. See the example below:

Example

The following example is presented for documentation and reference purposes only.

$curl -i https://api.thousandeyes.com/v5/tests/network/new.json \ -d '{ "interval": 300, \ "agents": [\ {"agentId": 113} ], "testName": "API network test addition for www.thousandeyes.com", "server": "www.thousandeyes.com", "port": 80, "alertsEnabled": 0 }' \ -H "Content-Type: application/json" \ -u {email}:{authToken}

Header

HTTP/1.1 201 CREATED Date: Thu, 07 Nov 2013 07:32:48 GMT Server: Apache/2.2.22 (Ubuntu) Transfer-Encoding: chunked

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

POST /v5/tests/{testType}/{testId}/update Updating a Test

Updates a test in ThousandEyes, based on properties provided in the POST data. In order to edit a test, the user attempting the creation must be an Account Admin, and the target test cannot be a live share or saved event.

Regular users are blocked from using any of the POST-based methods.

Note: When creating or updating a test and assigning alert rules, that alert rules are based on specific measurements being available. For example, when creating an HTTP server test with network measurements disabled, you will not be able to assign any alert rules that are based on network metrics. The same applies to BGP measurements.

Optional Parameters

  • aid={accountId} optional and requires the user to be assigned to the target account, specifies the account context of the request, obtained from the /accounts endpoint. Specifying this parameter without the user to be assigned to the target account will result in an error response. See Account Context for more information

Request

  • {testType} corresponds to any of the following options:
  • bgp
  • network
  • http-server
  • page-load
  • transactions
  • dns-trace
  • dns-server
  • dns-dnssec
  • voice
  • {testId} corresponds to a testId of the type specified by {testType}, see the test list endpoint for a listing of tests.

See the Test Metadata page for fields available during test update.

Response

If a test is successfully edited, an HTTP/200 OK response will be returned, and the test definition will be returned. The modifiedBy and modifiedDate fields should be updated according to the user who edited the account; See the example below:

Example

The following example is presented for documentation and reference purposes only.

$curl -i https://api.thousandeyes.com/v5/tests/http-server/817/update.json \ -d '{ "interval": 900, \ "agents": [\ {"agentId": 117} ], "testName": "Edited test name for API network test addition for www.thousandeyes.com" }' \ -H "Content-Type: application/json" \ -u {email}:{authToken}

Header

HTTP/1.1 200 OK Date: Thu, 07 Nov 2013 07:32:48 GMT Server: Apache/2.2.22 (Ubuntu) Transfer-Encoding: chunked

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

POST /v5/tests/{testType}/{testId}/delete Deleting a Test

Deletes the specified test in ThousandEyes, based on the testId provided in the API request. In order to delete a test, the user attempting the creation must be an Account Admin.

Regular users are blocked from using any of the POST-based methods.

Optional Parameters

  • aid={accountId} optional and requires the user to be assigned to the target account, specifies the account context of the request, obtained from the /accounts endpoint. Specifying this parameter without the user to be assigned to the target account will result in an error response. See Account Context for more information

Request

  • {testType} corresponds to any of the following options:

    • bgp
    • network
    • http-server
    • page-load
    • transactions
    • dns-trace
    • dns-server
    • dns-dnssec
    • voice

  • {testId} corresponds to a testId of the type specified by {testType}, see the test list endpoint for a listing of tests.

  • The request body must be specified, but should be empty

Response

If a test is successfully deleted, an HTTP/204 NO CONTENT response will be returned, and an empty JSON response will be in the body of the response.

Example

The following example is presented for documentation and reference purposes only.

$curl -i https://api.thousandeyes.com/v5/tests/network/811/delete.json \ -d '' \ -H "Content-Type: application/json" \ -u {email}:{authToken}

Header

HTTP/1.1 204 NO CONTENT Date: Thu, 07 Nov 2013 07:32:48 GMT Server: Apache/2.2.22 (Ubuntu) Transfer-Encoding: chunked Content-Type: application/json

Body

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

Saved Events

While there is no specific endpoint for Saved Events, ThousandEyes allows users to retrieve data for saved events through the normal test data endpoints. See the Test Data section for a list of endpoints that can be used to retrieve data for saved events. Unlike standard tests, saved events MUST be queried with the date range you wish to retrieve. See the window= and from= parameters in the list below.

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

Without specifying a time range parameter, your query will return only the last round of data available. In the two examples below, the first request returns the test’s first round of data, whereas the second request (where a date range is specified) returns the data for the requested range.

Example 1 (no time range specified)

Note in this circumstance, the last round of data is returned (since a request without a time range was specified)

$curl https://api.thousandeyes.com/v5/web/page-load/35199.json \ -u {email}:{authToken}

{ "web": { "test": { "enabled": 1, "savedEvent": 1, "testId": 35199, "testName": "Google Event", "type": "page-load", "interval": 900, "httpInterval": 900, "url": "http://www.google.com", "networkMeasurements": 1, "mtuMeasurements": 1, "bandwidthMeasurements": 0, "bgpMeasurements": 1, "alertsEnabled": 0, "liveShare": 0, "httpTimeLimit": 5, "httpTargetTime": 1000, "pageLoadTimeLimit": 30, "pageLoadTargetTime": 2, "includeHeaders": 0, "sslVersionId": 0, "verifyCertificate": 1, "useNtlm": 0, "createdDate": "2014-10-28 16:15:10", "createdBy": "API Sandbox Admin (api.sandbox+admin@thousandeyes.com)", "sslVersion": "Default", "apiLinks": [...] }, "pageLoad": [ { "countryId": "HK", "date": "2014-10-22 10:03:04", "agentName": "Hong Kong", "agentId": 12, "roundId": 1413972000, "responseTime": 35, "totalSize": 7278, "numObjects": 4, "numErrors": 0, "domLoadTime": 171, "pageLoadTime": 205, "permalink": "https://app.thousandeyes.com/web/page-load?__a=75&testId=35199&roundId=1413972000&agentId=12" }, ... ] }, "pages": { "current": 1 } }

Example 2 (time range specified)

Note in this circumstance, the full set of data is returned, and may involve paging - since a specific range was specified. If the time range used in the query did not overlap with the available data, no data would be returned.

$curl https://api.thousandeyes.com/v5/web/page-load/35199.json?from=2014-10-22+06:00:00&to=2014-10-22+10:00:00\ -u {email}:{authToken}

{ "from": "2014-10-22 04:00:00", "to": "2014-10-22 08:00:00", "web": { "test": { "enabled": 1, "savedEvent": 1, "testId": 35199, "testName": "Google Event", "type": "page-load", "interval": 900, "httpInterval": 900, "url": "http://www.google.com", "networkMeasurements": 1, "mtuMeasurements": 1, "bandwidthMeasurements": 0, "bgpMeasurements": 1, "alertsEnabled": 0, "liveShare": 0, "httpTimeLimit": 5, "httpTargetTime": 1000, "pageLoadTimeLimit": 30, "pageLoadTargetTime": 2, "includeHeaders": 0, "sslVersionId": 0, "verifyCertificate": 1, "useNtlm": 0, "createdDate": "2014-10-28 16:15:10", "createdBy": "API Sandbox Admin (api.sandbox+admin@thousandeyes.com)", "sslVersion": "Default", "apiLinks": [...] }, "pageLoad": [ { "countryId": "BR", "date": "2014-10-22 06:01:17", "agentName": "São Paulo, Brazil", "agentId": 16, "roundId": 1413957600, "responseTime": 2, "totalSize": 6405, "numObjects": 3, "numErrors": 0, "domLoadTime": 176, "pageLoadTime": 233, "permalink": "https://app.thousandeyes.com/web/page-load?__a=75&testId=35199&roundId=1413957600&agentId=16" }, ..., { "countryId": "HK", "date": "2014-10-22 10:03:04", "agentName": "Hong Kong", "agentId": 12, "roundId": 1413972000, "responseTime": 35, "totalSize": 7278, "numObjects": 4, "numErrors": 0, "domLoadTime": 171, "pageLoadTime": 205, "permalink": "https://app.thousandeyes.com/web/page-load?__a=75&testId=35199&roundId=1413972000&agentId=12" } ] }, "pages": { "current": 1 } }

© 2023 ThousandEyes. All rights reserved.