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 group context
    • Response formats
    • Time ranges
    • Response status codes
    • Rate limits
    • Pagination
    • Change policy
    • API change summary
  • Instant tests

    • Instant test
    • Instant test rerun
  • Tests

    • Test list
    • Test list by type
    • Test details
    • Test metadata
    • Creating a test
    • Updating a test
    • Deleting a test
    • Saved events
    • Path vis interface group list
    • Creating path vis interface group
    • Updating path vis interface group
    • Deleting path vis interface group
  • 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) Web Transactions
    • (Web) Web Transaction detail
    • (Web) Web Transaction component detail
    • (Web) FTP server
    • (DNS) Domain trace
    • (DNS) Server metrics
    • (DNS) DNSSEC
    • (Voice) SIP server
    • (Voice) RTP stream
  • Credentials

    • Credential list
    • Credential details
    • Creating a credential
    • Updating a credential
    • Deleting a credential
  • Endpoint Agents

    • Listing all agents
    • Getting an agent by id
    • Updating an agent
    • Enabling an agent
    • Disabling an agent
    • Transferring an agent
    • Deleting an agent
  • Endpoint Data

    • Endpoint user session list
    • Endpoint user session details
    • Endpoint web pages list
    • Endpoint web page details
    • Endpoint network sessions list
    • Endpoint network topology list
    • Endpoint network topology details
    • Endpoint data filtering
    • Endpoint networks
  • Endpoint Tests

    • Scheduled Test List
    • Scheduled Test List by Type
    • Scheduled Test Details
    • Scheduled Test Metadata
    • Creating a Scheduled Test
    • Automated Session Test List
    • Automated Session Test Details
    • Automated Session Test Metadata
    • Creating an Automated Session Test
  • Endpoint Instant Tests

    • Creating instant test
    • Rerunning instant test
  • Endpoint Test Data

    • Scheduled Tests (Network) End-to-End metrics
    • Scheduled Tests (Network) Path visualization
    • Scheduled Tests (Network) Detailed path trace
    • Scheduled Tests (Web) HTTP server
    • Automated Session Tests End-to-End metrics
    • Automated Session Tests Path visualization
    • Automated Session Tests Detailed path trace
  • Snapshots

    • Create a new snapshot
  • Agents & Monitors

    • Agent list
    • Agent detail
    • Updating an agent
    • Deleting an Agent
    • Agent cluster - Creating
    • Agent cluster - Adding members
    • Agent cluster - Removing members
    • Agent cluster - Converting to an agent
    • BGP Monitor list
    • Agent Notification Rules
    • Agent Notification Rule Detail
  • Alerts & Notifications

    • Active alerts
    • Alert detail
    • Alert rules
    • Alert rule detail
    • Alert rule metadata
    • Creating an alert rule
    • Updating an alert rule
    • Deleting an alert rule
    • Alert notification integrations
    • Alert suppression windows
    • Alert suppression window detail
    • Creating an alert suppression window
    • Updating an alert suppression window
    • Deleting an alert suppression window
    • Creating an advanced Alert Rule
  • Labels

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

    • Reports list
    • Report detail
    • Report data
    • Deleting a report
    • Report snapshots list
    • Report snapshot detail
    • Report snapshot data
    • Deleting a report snapshot
  • Dashboards

    • Dashboards list
    • Dashboards detail
    • Dashboard data
    • Deleting a dashboard
    • Dashboard snapshots list
    • Dashboards snapshot detail
    • Dashboard snapshot data
    • Deleting a dashboard snapshot
  • Administrative endpoints

    • Account group list
    • Account group detail
    • Creating an account group
    • Updating an account group
    • Deleting an account group
    • User list
    • User detail
    • Adding a user
    • Updating a user
    • Deleting a user
    • Role list
    • Role detail
    • Creating a role
    • Updating a role
    • Permission list
    • Activity log
    • Obtaining usage quota
    • Updating usage quotas
  • Usage

    • Obtaining usage details
    • Usage metadata

  • Showing APIv6  |  APIv7 (preview)

  • Product Documentation
  • Customer Success Center
  • Public GitHub Repository

Try ThousandEyes Now! Sign Up

Tests

GET /v6/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 (Querystring) Parameters

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

Request

  • There is no request body for this request.

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/v6/tests.json \ -u {email}:{authToken}

Header

HTTP/1.1 200 OK Server: nginx Date: Wed, 19 Apr 2017 13:18:03 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: 234 X-Organization-Rate-Limit-Reset: 1492607940 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-1

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 /v6/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 (Querystring) Parameters

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

Request

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

    • agent-to-server
    • agent-to-agent
    • bgp
    • http-server
    • page-load
    • web-transactions
    • ftp-server
    • dns-trace
    • dns-server
    • dns-dnssec
    • sip-server
    • voice (RTP Stream)
  • There is no request body for this request.

Example

$ curl https://api.thousandeyes.com/v6/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 Server: nginx Date: Wed, 19 Apr 2017 13:29:40 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: 228 X-Organization-Rate-Limit-Reset: 1492608600 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-5

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 /v6/tests/{testId} Test details

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

Optional (Querystring) Parameters

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

Request

  • {testId} the ID of the test you wish to retrieve
  • There is no request body for this request.

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/v6/tests/817.json \ -u {email}:{authToken}

Header

HTTP/1.1 200 OK Server: nginx Date: Wed, 19 Apr 2017 13:30:42 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: 228 X-Organization-Rate-Limit-Reset: 1492608660 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

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 tables below, organized by test 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.

All Test Types

FieldTest CreationTest UpdateData TypeAcceptable ValuesNotes
alertsEnabledOptionalOptionalinteger0 or 1choose 1 to enable alerts, or 0 to disable alerts. Defaults to 1
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.
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
createdByn/an/astringUsername (email@company.com)read only
createdDaten/an/astringYYYY-MM-DD HH:mm:ss formatted dateread only; shown in UTC
descriptionOptionalOptionalstring(any)defaults to empty string
enabledn/aOptionalinteger0 or 1choose 1 to enable the test, 0 to disable the test
groupsOptionalOptionalarray of label objects ("groups": [ { "name": "groupName", "groupId": groupId, "builtIn": 0}])see notesget groupId from /groupsendpoint.
liveSharen/an/ainteger0 or 1read only; indicates 1 for a test shared with your account group, 0 for a normal test
modifiedByn/an/astringUsername (email@company.com)read only
modifiedDaten/an/astringYYYY-MM-DD HH:mm:ss formatted dateread only; shown in UTC
savedEventn/an/ainteger0 or 1read only; indicates 1 for a saved event, 0 for a normal test
sharedWithAccountsOptionalOptionalarray of account group objects ("sharedWithAccounts": [{"aid": aid, "name": "AccountGroupName"}])see notesTest is shared with the listed accout groups. Get aid and name from account-groups endpoint.
testIdn/an/aintegerunique ID of testread only; each test is assigned a unique ID; this is used to access test data from other endpoints.
testNameOptionalOptionalstring(any)Test name must be unique
typen/an/astringtype of test being queriedThis is a read only value, as test type is implicit in the test creation url.

Routing

BGP (bgp)

FieldTest CreationTest UpdateData TypeAcceptable ValuesNotes
bgpMonitorsOptionalOptionalarray 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.
includeCoveredPrefixesOptionalOptionalinteger0 or 1set to 1 to include queries for subprefixes detected under this prefix
prefixRequiredn/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
usePublicBgpOptionalOptionalinteger0 or 1set to 1 to automatically add all available Public BGP Monitors

Network

Agent to Server (agent-to-server)

FieldTest CreationTest UpdateData TypeAcceptable ValuesNotes
agentsRequiredOptionalarray of agent objects {“agentId”: agentId}see notesget agentId from /agents endpoint.
agents.sourceIpAddressOptionalOptionalstringsee notesIP address from ipAddresses of Agent Details for interface selection.
bandwidthMeasurementsOptionalOptionalinteger0 or 1set to 1 to measure bandwidth. Only applies to Enterprise Agents assigned to the test
bgpMeasurementsOptionalOptionalinteger0 or 1choose 1 to enable bgp measurements, 0 to disable; defaults to 1
bgpMonitorsOptionalOptionalarray of BGP Monitor objects {“monitorId”: monitorId}see notesget monitorId from /bgp-monitors endpoint.
continuousModeOptionalOptionalinteger0 or 1choose 1 to enable continuous monitoring. If enabled, the fixedPacketRate will be enforced, bandwidthMeasurements will be disabled, and probeMode will be set to SYN if protocol is TCP.
fixedPacketRateOptionalOptionalinteger[0, 1] or (10…100)if continuousMode is 0, set the fixedPacketRate to a value between 10-100. If continuousMode is 1, set the fixedPacketRate to 1
intervalRequiredOptionalinteger[120, 300, 600, 900, 1800, 3600]value in seconds
mtuMeasurementsOptionalOptionalinteger0 or 1set to 1 to measure MTU sizes on network from agents to the target
numPathTracesOptionalOptionalinteger(3..10)defaults to 3
pathTraceModeOptionalOptionalstringclassic or inSessionchoose inSession to perform the path trace within a TCP session; defaults to classic
portOptionaln/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.
probeModeOptionalOptionalstringAUTO, SACK or SYNprobe mode used by End-to-end Network Test; only valid if protocol is set to TCP; defaults to AUTO
protocolOptionaln/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
serverRequiredn/astring(any)target name or IP address

Agent to Agent (agent-to-agent)

FieldTest CreationTest UpdateData TypeAcceptable ValuesNotes
agentsRequiredOptionalarray of agent objects {“agentId”: agentId}see notesget agentId from /agents endpoint.
agents.sourceIpAddressOptionalOptionalstringsee notesIP address from ipAddresses of Agent Details for interface selection.
bgpMeasurementsOptionalOptionalinteger0 or 1choose 1 to enable bgp measurements, 0 to disable; defaults to 1
bgpMonitorsOptionalOptionalarray of BGP Monitor objects {“monitorId”: monitorId}see notesget monitorId from /bgp-monitors endpoint.
directionOptionalOptionalstring[TO_TARGET, FROM_TARGET, BIDIRECTIONAL]Direction of the test (affects how results are shown); defaults to TO_TARGET
dscp  n/aRead OnlystringDSCP listdscp label
dscpIdOptionalOptionalintegerDSCP listsee list for acceptable values; defaults to 0
intervalRequiredOptionalinteger[120, 300, 600, 900, 1800, 3600]value in seconds
mssOptionalOptionalinteger(30..1400)Maximum Segment Size, in bytes.
numPathTracesOptionalOptionalinteger(3..10)defaults to 3
pathTraceModeOptionalOptionalstringclassic or inSessionchoose inSession to perform the path trace within a TCP session; defaults to classic
portOptionalOptionalinteger(1..65535)defaults to port 49153
protocolOptionalOptionalstringTCP or UDPdefaults to TCP
targetAgentIdRequiredOptionalintegerpull from /agents endpointagentId of the target agent for the test
throughputMeasurementsOptionalOptionalinteger0 or 1defaults to 0 (disabled), not allowed when source (or target) of the test is a cloud agent
throughputDurationOptionalOptionalinteger(5000..30000)defaults to 10000
throughputRateOptionalOptionalinteger(0..1000)for UDP only

DNS

DNS Server (dns-server)

FieldTest CreationTest UpdateData TypeAcceptable ValuesNotes
agentsRequiredOptionalarray of agent objects {“agentId”: agentId}see notesget agentId from /agents endpoint
bandwidthMeasurementsOptionalOptionalinteger0 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
bgpMeasurementsOptionalOptionalinteger0 or 1choose 1 to enable bgp measurements, 0 to disable; defaults to 1 when networkMeasurements is set
bgpMonitorsOptionalOptionalarray of BGP Monitor objects {“monitorId”: monitorId}see notesget monitorId from /bgp-monitors endpoint.
dnsServersRequiredOptionalarray of DNS Server objects {“serverName”: “fqdn of server”}
dnsTransportProtocolOptionalOptionalstringUDP or TCPtransport protocol used for DNS requests; defaults to UDP
domainRequiredn/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.
intervalRequiredOptionalinteger[300, 600, 900, 1800, 3600]value in seconds
mtuMeasurementsOptionalOptionalinteger0 or 1set to 1 to measure MTU sizes on network from agents to the target
networkMeasurementsOptionalOptionalinteger0 or 1choose 1 to enable network measurements, 0 to disable; defaults to 1
numPathTracesOptionalOptionalinteger(1..10)defaults to 1
pathTraceModeOptionalOptionalstringclassic or inSessionchoose inSession to perform the path trace within a TCP session; defaults to classic
probeModeOptionalOptionalstringAUTO, SACK or SYNprobe mode used by End-to-end Network Test; only valid if protocol is set to TCP; defaults to AUTO
protocolOptionalOptionalstringTCP or ICMPprotocol used by dependent Network tests (End-to-end, Path Trace, PMTUD); defaults to TCP
recursiveQueriesOptionalOptionalinteger0 or 1set to 1 to run query with RD (recursion desired) flag enabled

DNS Trace (dns-trace)

FieldTest CreationTest UpdateData TypeAcceptable ValuesNotes
agentsRequiredOptionalarray of agent objects {“agentId”: agentId}see notesget agentId from /agents endpoint
dnsTransportProtocolOptionalOptionalstringUDP or TCPtransport protocol used for DNS requests; defaults to UDP
domainRequiredn/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.
intervalRequiredOptionalinteger[300, 600, 900, 1800, 3600]value in seconds

DNSSEC (dns-dnssec)

FieldTest CreationTest UpdateData TypeAcceptable ValuesNotes
agentsRequiredOptionalarray of agent objects {“agentId”: agentId}see notesget agentId from /agents endpoint.
domainRequiredn/astringsee notestarget record for test, followed by record type (ie, www.thousandeyes.com A)
intervalRequiredOptionalinteger[300, 600, 900, 1800, 3600]value in seconds

Web

HTTP Server (http-server)

FieldTest CreationTest UpdateData TypeAcceptable ValuesNotes
agentsRequiredOptionalarray of agent objects {“agentId”: agentId}see notesget agentId from /agents endpoint.
agents.sourceIpAddressOptionalOptionalstringsee notesIP address from ipAddresses of Agent Details for interface selection.
authTypeOptionalOptionalstringNONE, BASIC, NTLM, KERBEROSHTTP Authentication type; defaults to NONE
bandwidthMeasurementsOptionalOptionalinteger0 or 1set to 1 to measure bandwidth. Only applies to Enterprise Agents assigned to the test, and requires that networkMeasurements is set.
bgpMeasurementsOptionalOptionalinteger0 or 1choose 1 to enable bgp measurements, 0 to disable; defaults to 1 when networkMeasurements is set
bgpMonitorsOptionalOptionalarray of BGP Monitor objects {“monitorId”: monitorId}see notesget monitorId from /bgp-monitors endpoint.
clientCertificateOptionalOptionalstringsee notesString representation (containing newline characters) of client certificate, if used
contentRegexOptionalOptionalstringRegular ExpressionsThis field does not require escaping
customHeadersOptionalOptionalobject containing header objects "customHeaders": {"root": {"header1": "value1"},"domains": {"domain1.com": {"header2": "value2"}},"all": {"header3": "value3"}}anyuse HTTP header values in this object
customHeaders.allOptionalOptionalobject containing headers "all":{"header1":"value1","header2":"value2"}anyuse these HTTP headers for all domains
customHeaders.domainsOptionalOptionalobject containing domains mapped to header objects "domains":{"example.com":{"header1":"value1","header2":"value2"}}anyuse these HTTP headers for the specified domain(s)
customHeaders.rootOptionalOptionalobject containing headers "root":{"header1":"value1","header2":"value2"}anyuse these HTTP headers for root server request
desiredStatusCodeOptionalOptionalstringA valid HTTP response codeSet to the value you’re interested in retrieving.
downloadLimitOptionalOptionalintegeranyspecify maximum number of bytes to download from the target object
dnsOverrideOptionalOptionalstringIP addressIP address to use for DNS override
followRedirectsOptionalOptionalinteger0 or 1set to 0 to not follow HTTP/301 or HTTP/302 redirect directives. Default is 1
headersOptionalOptionalarray of header strings [“header: value”, “header2: value”]anyuse HTTP header values in this list
httpVersionOptionalOptionalinteger[1,2]2 for default (prefer HTTP/2), 1 for HTTP/1.1 only
httpTargetTimeOptionalOptionalinteger(100..5000)target time for HTTP server completion; specified in milliseconds
httpTimeLimitOptionalOptionalinteger(5..60)defaults to 5 seconds
intervalRequiredOptionalinteger[120, 300, 600, 900, 1800, 3600]value in seconds
mtuMeasurementsOptionalOptionalinteger0 or 1set to 1 to measure MTU sizes on network from agents to the target
networkMeasurementsOptionalOptionalinteger0 or 1choose 1 to enable network measurements, 0 to disable; defaults to 1
numPathTracesOptionalOptionalinteger(3..10)defaults to 3
passwordOptionalOptionalstringsee notespassword to be used for Basic/NTLM authentication
pathTraceModeOptionalOptionalstringclassic or inSessionchoose inSession to perform the path trace within a TCP session; defaults to classic
postBodyOptionalOptionalstringsee 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.
probeModeOptionalOptionalstringAUTO, SACK or SYNprobe mode used by End-to-end Network Test; only valid if protocol is set to TCP; defaults to AUTO
protocolOptionalOptionalstringTCP or ICMPprotocol used by dependent Network tests (End-to-end, Path Trace, PMTUD); defaults to TCP
sslVersionRead onlyRead Onlystringcorresponds to sslVersionIdReflects the verbose ssl protocol version used by a test
sslVersionIdOptionalOptionalinteger[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
urlRequiredn/astringsee notestarget for the test
useNtlmOptionalOptionalinteger0 or 1choose 1 to use NTLM, 0 to use Basic Authentication. Requires username/password to be set
userAgentOptionalOptionalstringsee notesuser-agent string to be provided during the test
usernameOptionalOptionalstringsee notesusername to be used for Basic/NTLM authentication
verifyCertificateOptionalOptionalinteger0 or 1set to 0 to ignore certificate errors (defaults to 1)

Page Load (page-load)

FieldTest CreationTest UpdateData TypeAcceptable ValuesNotes
agentsRequiredOptionalarray of agent objects {“agentId”: agentId}see notesget agentId from /agents endpoint
authTypeOptionalOptionalstringNONE, BASIC, NTLM, KERBEROSHTTP Authentication type; defaults to NONE
bandwidthMeasurementsOptionalOptionalinteger0 or 1set to 1 to measure bandwidth. Only applies to Enterprise Agents assigned to the test, and requires that networkMeasurements is set
bgpMeasurementsOptionalOptionalinteger0 or 1choose 1 to enable bgp measurements, 0 to disable; defaults to 1 when networkMeasurements is set
bgpMonitorsOptionalOptionalarray of BGP Monitor objects {“monitorId”: monitorId}see notesget monitorId from /bgp-monitors endpoint.
customHeadersOptionalOptionalobject containing header objects "customHeaders": {"root": {"header1": "value1"},"domains": {"domain1.com": {"header2": "value2"}},"all": {"header3": "value3"}}anyuse HTTP header values in this object
customHeaders.allOptionalOptionalobject containing headers "all":{"header1":"value1","header2":"value2"}anyuse these HTTP headers for all domains
customHeaders.domainsOptionalOptionalobject containing domains mapped to header objects "domains":{"example.com":{"header1":"value1","header2":"value2"}}anyuse these HTTP headers for the specified domain(s)
customHeaders.rootOptionalOptionalobject containing headers "root":{"header1":"value1","header2":"value2"}anyuse these HTTP headers for root server request
httpIntervalRequiredOptionalinteger[120, 300, 600, 900, 1800, 3600]Cannot be larger than the interval value; defaults to the same value as interval
httpTargetTimeOptionalOptionalinteger(100..5000)target time for HTTP server completion; specified in milliseconds
httpTimeLimitOptionalOptionalinteger(5..60)defaults to 5 seconds
httpVersionOptionalOptionalinteger[1,2]2 for default (prefer HTTP/2), 1 for HTTP/1.1 only
includeHeadersOptionalOptionalinteger0 or 1set to 1 to capture response headers for objects loaded by the test. Default is 1.
intervalRequiredOptionalinteger[120, 300, 600, 900, 1800, 3600]value in seconds
mtuMeasurementsOptionalOptionalinteger0 or 1set to 1 to measure MTU sizes on network from agents to the target
networkMeasurementsOptionalOptionalinteger0 or 1choose 1 to enable network measurements, 0 to disable; defaults to 1
numPathTracesOptionalOptionalinteger(3..10)defaults to 3
pageLoadTargetTimeOptionalOptionalinteger(1..30)target time for Page Load completion; specified in seconds; cannot exceed pageLoadTimeLimit value
pageLoadTimeLimitOptionalOptionalinteger(5..MIN(0.25 * interval, 60)must be larger than httpTimeLimit; defaults to 10 seconds
passwordOptionalOptionalstringsee notespassword to be used for Basic/NTLM authentication
pathTraceModeOptionalOptionalstringclassic or inSessionchoose inSession to perform the path trace within a TCP session; defaults to classic
probeModeOptionalOptionalstringAUTO, SACK or SYNprobe mode used by End-to-end Network Test; only valid if protocol is set to TCP; defaults to AUTO
protocolOptionalOptionalstringTCP or ICMPprotocol used by dependent Network tests (End-to-end, Path Trace, PMTUD); defaults to TCP
sslVersionRead onlyRead Onlystringcorresponds to sslVersionIdReflects the verbose ssl protocol version used by a test
sslVersionIdOptionalOptionalinteger[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
subintervalOptionalOptionalinteger[60, 120, 300, 600, 900, 1200, 1800, 3600] or nullsubinterval for round-robin testing (in seconds). Must be less than or equal to interval and must evenly divide interval; default is null, which disables round-robin
urlRequiredn/astringsee notestarget for the test
useNtlmOptionalOptionalinteger0 or 1choose 1 to use NTLM, 0 to use Basic Authentication. Requires username/password to be set
userAgentOptionalOptionalstringsee notesuser-agent string to be provided during the test
usernameOptionalOptionalstringsee notesusername to be used for Basic/NTLM authentication
verifyCertificateOptionalOptionalinteger0 or 1set to 0 to ignore certificate errors (defaults to 1)
blockDomainsOptionalOptionalstringsee notesdomains or full object URLs to be excluded from metrics and waterfall data for page load tests.
disableScreenshotOptionalOptionalinteger0 or 1choose 1 to not capture screenshots. 0 to allow screenshots to be taken.
allowMicAndCameraOptionalOptionalinteger0 or 1choose 1 to allow the use of a fake mic and camera in the browser. 0 to block the mic and camera.
allowGeolocationOptionalOptionalinteger0 or 1choose 1 to use the agent’s geolocation by the web page. 0 to block the geolocation in the web page.
browserLanguageOptionalOptionalstringsee notesSelect one of the available browserlanguage that you want to use to configure the browser.
pageLoadingStrategyOptionalOptionalstringnormal, eager or nonenormal Wait for the entire page to load, meaning that HTML content and all resources have been downloaded and parsed before moving to the next action in the transaction test script. eager Wait for the DOMContentLoaded event, meaning that HTML content is downloaded and parsed, and the document readiness state is “interactive”, before moving to the next action in the test script. none Wait only for HTML content to download. Once the HTML is downloaded, the test proceeds to the next action in the transaction test script. (default is normal).

Web Transaction (web-transactions)

FieldTest CreationTest UpdateData TypeAcceptable ValuesNotes
agentsRequiredOptionalarray of agent objects {“agentId”: agentId}see notesget agentId from /agents endpoint.
authTypeOptionalOptionalstringNONE, BASIC, KERBEROS, NTLMHTTP Authentication type; defaults to NONE
bandwidthMeasurementsOptionalOptionalinteger0 or 1set to 1 to measure bandwidth; defaults to 0. Only applies to Enterprise Agents assigned to the test, and requires that networkMeasurements is set.
contentRegexOptionalOptionalstringRegular ExpressionsVerify content using a regular expression. This field does not require escaping
credentialsOptionalOptionalarray of credentialId integers {"credentials":[credentialId1,credentialId2,...]}see notesget credentialId from /credentials endpoint
customHeadersOptionalOptionalobject containing header objects "customHeaders": {"root": {"header1": "value1"},"domains": {"domain1.com": {"header2": "value2"}},"all": {"header3": "value3"}}anyuse HTTP header values in this object
customHeaders.allOptionalOptionalobject containing headers "all":{"header1":"value1","header2":"value2"}anyuse these HTTP headers for all domains
customHeaders.domainsOptionalOptionalobject containing domains mapped to header objects "domains":{"example.com":{"header1":"value1","header2":"value2"}}anyuse these HTTP headers for the specified domain(s)
customHeaders.rootOptionalOptionalobject containing headers "root":{"header1":"value1","header2":"value2"}anyuse these HTTP headers for root server request
desiredStatusCodeOptionalOptionalstringA valid HTTP response codeSet to the value you’re interested in retrieving.
followRedirectsOptionalOptionalinteger0 or 1set to 0 to not follow HTTP/301 or HTTP/302 redirect directives. Default is 1
httpTargetTimeOptionalOptionalinteger(100..5000)target time for HTTP server completion; specified in milliseconds
httpTimeLimitOptionalOptionalinteger(5..60)defaults to 5 seconds
httpVersionOptionalOptionalinteger[1,2]2 for default (prefer HTTP/2), 1 for HTTP/1.1 only
includeHeadersOptionalOptionalinteger0 or 1set to 1 to capture response headers for objects loaded by the test. Default is 1.
intervalRequiredOptionalinteger[300, 600, 900, 1800, 3600]value in seconds
mtuMeasurementsOptionalOptionalinteger0 or 1set to 1 to measure MTU sizes on network from agents to the target
networkMeasurementsOptionalOptionalinteger0 or 1choose 1 to enable network measurements, 0 to disable; defaults to 1
numPathTracesOptionalOptionalinteger(3..10)defaults to 3
passwordOptionalOptionalstringsee notespassword to be used for NTLM or Basic authentication
pathTraceModeOptionalOptionalstringclassic or inSessionchoose inSession to perform the path trace within a TCP session; defaults to classic
probeModeOptionalOptionalstringAUTO, SACK or SYNprobe mode used by End-to-end Network Test; only valid if protocol is set to TCP; defaults to AUTO
protocolOptionalOptionalstringTCP or ICMPprotocol used by dependent Network tests (End-to-end, Path Trace, PMTUD); defaults to TCP
sslVersionIdOptionalOptionalinteger[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
subintervalOptionalOptionalinteger[60, 120, 300, 600, 900, 1200, 1800, 3600] or nullsubinterval for round-robin testing (in seconds). Must be less than or equal to interval and must evenly divide interval; default is null, which disables round-robin
targetTimeOptionalOptionalinteger(1..60)target time for completion, defaults to 50% of time limit; specified in seconds
timeLimitOptionalOptionalinteger(5..MIN(0.25 * interval, 180))time limit for transaction; defaults to 30s
transactionScriptRequiredOptional (see notes)stringsee notesJavaScript of a web transaction test. Quotes must be escaped (precede " characters with \ ).
urlRequiredRead Onlystringsee notestarget for the test
useNtlmOptionalOptionalinteger0 or 1choose 1 to use NTLM Authentication, or choose 0 to use Basic Authentication. Requires username and password to be set. If authType is specified, it will override this setting.
userAgentOptionalOptionalstringsee notesuser-agent string to be provided during the test
usernameOptionalOptionalstringsee notesusername to be used for NTLM or Basic authentication
verifyCertificateOptionalOptionalinteger0 or 1set to 0 to ignore certificate errors (defaults to 1)
blockDomainsOptionalOptionalstringsee notesdomains or full object URLs to be excluded from metrics and waterfall data for transaction tests.
disableScreenshotOptionalOptionalinteger0 or 1choose 1 to not capture screenshots. 0 to allow screenshots to be taken.
allowMicAndCameraOptionalOptionalinteger0 or 1choose 1 to allow the use of a fake mic and camera in the browser. 0 to block the mic and camera.
allowGeolocationOptionalOptionalinteger0 or 1choose 1 to use the agent’s geolocation by the web page. 0 to block the geolocation in the web page.
browserLanguageOptionalOptionalstringsee notesSelect one of the available browserlanguage that you want to use to configure the browser.
pageLoadingStrategyOptionalOptionalstringnormal, eager or nonenormal Wait for the entire page to load, meaning that HTML content and all resources have been downloaded and parsed before moving to the next action in the transaction test script. eager Wait for the DOMContentLoaded event, meaning that HTML content is downloaded and parsed, and the document readiness state is “interactive”, before moving to the next action in the test script. none Wait only for HTML content to download. Once the HTML is downloaded, the test proceeds to the next action in the transaction test script. (default is normal).

FTP Server (ftp-server)

FieldTest CreationTest UpdateData TypeAcceptable ValuesNotes
agentsRequiredOptionalarray of agent objects {"agentId": agentId}see notesget agentId from /agents endpoint.
agents.sourceIpAddressOptionalOptionalstringsee notesIP address from ipAddresses of Agent Details for interface selection.
bgpMeasurementsOptionalOptionalinteger0 or 1choose 1 to enable bgp measurements, 0 to disable; defaults to 1 when networkMeasurements is set
downloadLimitOptionalOptionalintegeranyspecify maximum number of bytes to download from the target object
ftpTargetTimeOptionalOptionalinteger(1000..6000)target time for operation completion; specified in milliseconds.
ftpTimeLimitOptionalOptionalinteger(10..60)Set the time limit for the test (in seconds). FTP tests default to 10s.
intervalRequiredOptionalinteger[300, 600, 900, 1800, 3600]value in seconds.
mtuMeasurementsOptionalOptionalinteger0 or 1set to 1 to measure MTU sizes on network from agents to the target
networkMeasurementsOptionalOptionalinteger0 or 1choose 1 to enable network measurements, 0 to disable; defaults to 1
numPathTracesOptionalOptionalinteger(3..10)defaults to 3
passwordRequiredOptionalstringsee notespassword to be used to authenticate with the destination server.
pathTraceModeOptionalOptionalstringclassic or inSessionchoose inSession to perform the path trace within a TCP session; defaults to classic
probeModeOptionalOptionalstringAUTO, SACK or SYNprobe mode used by End-to-end Network Test; only valid if protocol is set to TCP; defaults to AUTO
protocolOptionalOptionalstringTCP or ICMPprotocol used by dependent Network tests (End-to-end, Path Trace, PMTUD); defaults to TCP
requestTypeRequiredOptionalstring[Download, Upload, List]Set the type of activity for the test.
urlRequiredOptionalstringsee notesurl of site being tested. Based on the request type, may be a fully qualified domain + file name (for download), a path on an FTP Server (for list and upload types)
useActiveFtpOptionalOptional0 or 1see notesexplicitly set the flag to use active FTP. Tests are set to use passive FTP by default
useExplicitFtpsOptionalOptional0 or 1see notesuse explicit FTPS (ftp over SSL). By default, tests will autodetect when it is appropriate to use FTPS.
usernameRequiredOptionalstringsee notesusername to be used to authenticate with the destination server

Voice

SIP Server (sip-server)

FieldTest CreationTest UpdateData TypeAcceptable ValuesNotes
agentsRequiredOptionalarray of agent objects {"agentId": agentId}see notesget agentId from /agents endpoint.
agents.sourceIpAddressOptionalOptionalstringsee notesIP address from ipAddresses of Agent Details for interface selection.
authUserOptionalOptionalstringsee notesusername for authentication with SIP server
bgpMeasurementsOptionalOptionalinteger0 or 1choose 1 to enable bgp measurements, 0 to disable; defaults to 1 when networkMeasurements is set
mtuMeasurementsOptionalOptionalinteger0 or 1set to 1 to measure MTU sizes on network from agents to the target
networkMeasurementsOptionalOptionalinteger0 or 1choose 1 to enable network measurements, 0 to disable; defaults to 1
optionsRegexOptionalOptionalstringRegular Expressionsthis field does not require escaping
passwordOptionalOptionalstringsee notespassword for authentication with SIP server
pathTraceModeOptionalOptionalstringclassic or inSessionchoose inSession to perform the path trace within a TCP session; defaults to classic
portRequiredOptionalinteger(1024..65535)port number for the chosen protocol
protocolOptionalOptionalstringTCP, TLS or UDPtransport layer for SIP communication, defaults to TCP
registerEnabledOptionalOptionalinteger0 or 11 to perform SIP registration on the test target with the SIP REGISTER command, defaults to 0
sipRegistrarRequiredOptionalstringsee notesSIP server to be tested, specified by domain name or IP address
sipTargetTimeOptionalOptionalinteger(100..5000)target time for test completion; specified in milliseconds
sipTimeLimitOptionalOptionalinteger(5..10)defaults to 5 seconds
targetSipCredentialsRequiredOptionalobjectsee notestarget SIP server parameters
targetSipCredentials.authUserOptionalOptionalstringsee notesusername for authentication with SIP server
targetSipCredentials.passwordOptionalOptionalstringsee notespassword for authentication with SIP server
targetSipCredentials.portRequiredOptionalinteger(1024..65535)port number for the chosen protocol
targetSipCredentials.protocolOptionalOptionalstringTCP, TLS or UDPtransport layer for SIP communication, defaults to TCP
targetSipCredentials.sipRegistrarRequiredOptionalstringsee notesSIP server to be tested, specified by domain name or IP address
targetSipCredentials.userOptionalOptionalstringsee notesusername for SIP registration; should be unique within a ThousandEyes Account Group
userOptionalOptionalstringsee notesusername for SIP registration; should be unique within a ThousandEyes Account Group

RTP Stream (voice)

FieldTest CreationTest UpdateData TypeAcceptable ValuesNotes
agentsRequiredOptionalarray of agent objects {"agentId": agentId}see notesget agentId from /agents endpoint.
agents.sourceIpAddressOptionalOptionalstringsee notesIP address from ipAddresses of Agent Details for interface selection.
bgpMeasurementsOptionalOptionalinteger0 or 1choose 0 to disable bgp measurements; defaults to 1
codecn/aRead Onlystringsee notescodec label
codecIdOptionalOptionalintegerVoice codec listsee list for acceptable values; defaults to 0
dscpn/aRead Onlystringsee notesdscp label
dscpIdOptionalOptionalintegerDSCP listsee list for acceptable values; defaults to 46
durationOptionalOptionalinteger(5..30)duration of the test (in seconds); defaults to 5
intervalRequiredOptionalinteger[300, 600, 900, 1800, 3600]value in seconds
jitterBufferOptionalOptionalinteger(0..150)de-jitter buffer size (in seconds); defaults to 40
numPathTracesOptionalOptionalinteger(3..10)defaults to 3
portOptionalOptionalinteger(1024..65535)defaults to port 49152
targetAgentIdRequiredOptionalintegerpull from /agents endpointagentId of the target agent for the test

POST /v6/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 (Querystring) Parameters

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

Request

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

    • agent-to-server
    • agent-to-agent
    • bgp
    • http-server
    • page-load
    • web-transactions
    • ftp-server
    • dns-trace
    • dns-server
    • dns-dnssec
    • sip-server
    • voice (RTP Stream)
  • Request body should contain fields to be set during creation. 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/v6/tests/agent-to-server/new.json \ -d '{ "interval": 300, "agents": [ {"agentId": 113} ], "testName": "API agent-to-server test addition for www.thousandeyes.com", "server": "www.thousandeyes.com", "port": 80, "alertsEnabled": 0 }' \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -u {email}:{authToken}

Header

HTTP/1.1 201 CREATED Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 228 X-Organization-Rate-Limit-Reset: 1492608660 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

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

POST /v6/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 (Querystring) Parameters

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

Request

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

    • bgp
    • agent-to-server
    • agent-to-agent
    • http-server
    • page-load
    • web-transactions
    • ftp-server
    • dns-trace
    • dns-server
    • dns-dnssec
    • sip-server
    • voice (RTP Stream)
  • {testId} corresponds to a testId of the type specified by {testType}, see the test list endpoint for a listing of tests

  • Request body should contain fields to be set during creation. See the Test Metadata page for fields available during test creation

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/v6/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 Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 227 X-Organization-Rate-Limit-Reset: 1492608660 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

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

POST /v6/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 (Querystring) Parameters

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

Request

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

    • bgp
    • agent-to-server
    • agent-to-agent
    • http-server
    • page-load
    • web-transactions
    • ftp-server
    • dns-trace
    • dns-server
    • dns-dnssec
    • sip-server
    • voice (RTP Stream)
  • {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 provided, 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/v6/tests/agent-to-server/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 Connection: keep-alive X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 224 X-Organization-Rate-Limit-Reset: 1492608660 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

Body

  • The body of a delete request will be empty.

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.
  • aid={aid} optional and requires the user to be assigned to the target account group, specifies the account group context of the request, obtained from the /account-groups endpoint. Specifying this parameter without the user being assigned to the target account will result in an error response. See Account group context for more information

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/v6/web/page-load/35199.json \ -u {email}:{authToken}

{ "web": { "test": { "createdDate": "2014-10-28 16:15:10", "createdBy": "API Sandbox Admin (api.sandbox+admin@thousandeyes.com)", "enabled": 1, "savedEvent": 1, "testId": 35199, "testName": "Google Event", "type": "page-load", "interval": 900, "httpInterval": 900, "url": "http://www.google.com", "protocol": "TCP", "networkMeasurements": 1, "mtuMeasurements": 1, "bandwidthMeasurements": 0, "bgpMeasurements": 1, "usePublicBgp": 1, "alertsEnabled": 0, "liveShare": 0, "httpTimeLimit": 5, "httpTargetTime": 1000, "httpVersion": 2, "pageLoadTimeLimit": 30, "pageLoadTargetTime": 2, "followRedirects": 1, "includeHeaders": 0, "sslVersionId": 0, "sslVersion": "Auto", "verifyCertificate": 1, "useNtlm": 0, "authType": "NONE", "contentRegex": "", "probeMode": "AUTO", "apiLinks": [...] }, "pageLoad": [ { "agentName": "Kwai Chung, Hong Kong", "countryId": "HK", "date": "2014-10-22 10:03:04", "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/v6/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 06:00:00", "to": "2014-10-22 10:00:00", "web": { "test": { "createdDate": "2014-10-28 16:15:10", "createdBy": "API Sandbox Admin (api.sandbox+admin@thousandeyes.com)", "enabled": 1, "savedEvent": 1, "testId": 35199, "testName": "Google Event", "type": "page-load", "interval": 900, "httpInterval": 900, "url": "http://www.google.com", "protocol": "TCP", "networkMeasurements": 1, "mtuMeasurements": 1, "bandwidthMeasurements": 0, "bgpMeasurements": 1, "usePublicBgp": 1, "alertsEnabled": 0, "liveShare": 0, "httpTimeLimit": 5, "httpTargetTime": 1000, "httpVersion": 2, "pageLoadTimeLimit": 30, "pageLoadTargetTime": 2, "followRedirects": 1, "includeHeaders": 0, "sslVersionId": 0, "sslVersion": "Auto", "verifyCertificate": 1, "useNtlm": 0, "authType": "NONE", "contentRegex": "", "probeMode": "AUTO", "apiLinks": [...] }, "pageLoad": [ { "agentName": "Kwai Chung, Hong Kong", "countryId": "HK", "date": "2014-10-22 06:01:00", "agentId": 12, "roundId": 1413957600, "responseTime": 37, "totalSize": 7281, "numObjects": 4, "numErrors": 0, "domLoadTime": 341, "pageLoadTime": 384, "permalink": "https://app.thousandeyes.com/web/page-load?__a=75&testId=35199&roundId=1413957600&agentId=12" }, ... ] }, "pages": { "current": 1 } }

GET /v6/net/path-vis/interface-groups Path vis interface group list

Returns a list of all path visualization interface groups in ThousandEyes.

Optional (Querystring) Parameters

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

Request

  • There is no request body for this request.

Response

Sends back an array of path visualization interface groups.

Example

$ curl https://api.thousandeyes.com/v6/net/path-vis/interface-groups.json \ -u {email}:{authToken}

Header

HTTP/1.1 200 OK Server: nginx Date: Wed, 19 Apr 2017 13:18:03 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: 234 X-Organization-Rate-Limit-Reset: 1492607940 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-1

Body

{ "net": { "pathVisInterfaceGroups": [ { "groupId": 1, "groupName": "Interface group", "ipAddresses": [ "192.168.1.1", "192.168.1.2" ] }, ... ] } }

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

POST /v6/net/path-vis/interface-groups Creating path vis interface group

Creates a new path visualization interface group in ThousandEyes, based on properties provided in the POST data.

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

Optional (Querystring) Parameters

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

Request

  • {name} the name of the path visualization interface group
  • {ipAddresses} the array of IP addresses associated with the interface group

Response

If a path visualization interface group is successfully created, an HTTP/201 CREATED response 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/v6/net/path-vis/interface-groups.json \ -d '{ "groupName": "Interface group", "ipAddresses": [ "192.168.1.1", "192.168.1.2" ] }' \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -u {email}:{authToken}

Header

HTTP/1.1 201 CREATED Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 228 X-Organization-Rate-Limit-Reset: 1492608660 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

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

PUT /v6/net/path-vis/interface-groups/{groupId} Updating path vis interface group

Deletes an existing path visualization interface group in ThousandEyes, based on the path visualization interface group id provided in the API request.

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

Optional (Querystring) Parameters

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

Request

  • {name} the name of the path visualization interface group
  • {ipAddresses} the array of IP addresses associated with the interface group

Response

If a path visualization interface group is successfully updated, an HTTP/200 OK 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 -X PUT -i https://api.thousandeyes.com/v6/net/path-vis/interface-groups/1.json \ -d '{ "groupId: 1 "groupName": "Interface group", "ipAddresses": [ "192.168.1.1", "192.168.1.2" ] }' \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -u {email}:{authToken}

Header

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 228 X-Organization-Rate-Limit-Reset: 1492608660 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

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

DELETE /v6/net/path-vis/interface-groups/{groupId} Deleting path vis interface group

Updates an existing path visualization interface group in ThousandEyes, based on the path visualization interface group id provided in the API request.

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

Optional (Querystring) Parameters

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

Request

  • There is no request body for this request.

Response

If a path visualization interface group 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 -X DELETE -i https://api.thousandeyes.com/v6/net/path-vis/interface-groups/1.json \ -d '' \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -u {email}:{authToken}

Header

HTTP/1.1 204 NO CONTENT Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 228 X-Organization-Rate-Limit-Reset: 1492608660 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-2

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

© 2023 ThousandEyes. All rights reserved.