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

Endpoint Scheduled Tests

GET /v6/endpoint-tests Scheduled Test List

Returns a list of all endpoint scheduled tests configured in ThousandEyes. This list does not contain saved events.

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 endpoint tests. See Scheduled Endpoint Test Metadata page for information on fields returned by this endpoint.

Example

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

Header

HTTP/1.1 200 OK Server: nginx Date: Sat, 25 Aug 2018 17:03:50 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 237 X-Organization-Rate-Limit-Reset: 1535216640 Strict-Transport-Security: max-age=31536000 X-Content-Type-Options: nosniff X-Server-Name: 1-3

Body

{ "endpointTest": [ { "alertsEnabled": 0, "apiLinks": [...], "bandwidthMeasurements": 0, "bgpMeasurements": 0, "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "createdDate": "2018-08-25 16:56:50", "enabled": 1, "interval": 60, "agentSelectorConfig": { "agentIds": [], "agentSelectorType": "LIST_OF_LABELS", "labelIds": [10581, 12461], "maxMachines": 25 }, "modifiedBy": "API Sandbox User (noreply@thousandeyes.com)", "modifiedDate": "2018-08-25 16:57:59", "mtuMeasurements": 0, "networkMeasurements": 1, "port": -1, "protocol": "ICMP", "savedEvent": 0, "server": "www.thousandeyes.com", "testId": 282, "testName": "ThousandeEyes", "type": "agent-to-server", "usePublicBgp": 0 }, ... ] }

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

GET /v6/endpoint-tests/{testType} Scheduled Test List by Type

Returns a list of all endpoint scheduled tests of the type specified, configured in ThousandEyes. The list does not contain saved events.

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
    • http-server
  • There is no request body for this request.

Example

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

Response

Sends back an array of tests matching the requested test type. See Scheduled Endpoint Test Metadata page for information on fields returned by this endpoint.

Header

HTTP/1.1 200 OK Server: nginx Date: Sat, 25 Aug 2018 17:03:54 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: 238 X-Organization-Rate-Limit-Reset: 1535216640 Strict-Transport-Security: max-age=31536000 X-Content-Type-Options: nosniff X-Server-Name: 1-1

Body

{ "endpointTest": [ { "alertsEnabled": 0, "apiLinks": [...], "authType": "NONE", "bandwidthMeasurements": 0, "bgpMeasurements": 0, "createdBy": "API Sandbox User (noprely@thousandeyes.com)", "createdDate": "2018-08-18 18:33:23", "enabled": 1, "followRedirects": 1, "httpTargetTime": 1000, "httpTimeLimit": 5000, "httpVersion": 1, "interval": 60, "agentSelectorConfig": { "agentIds": ["LAPTOP-MAC-AGENT", "PC-WINDOWS-AGENT"], "agentSelectorType": "SPECIFIC_AGENTS", "labelIds": [], "maxMachines": 25 }, "modifiedBy": "API Sandbox User (noreply@thousandeyes.com)", "modifiedDate": "2018-08-25 17:22:54", "mtuMeasurements": 0, "networkMeasurements": 1, "port": 443, "protocol": "TCP", "savedEvent": 0, "server": "developer.thousandeyes.com", "sslVersion": "Auto", "sslVersionId": 0, "testId": 273, "testName": "Developer Reference", "type": "http-server", "url": "https://developer.thousandeyes.com/", "useNtlm": 0, "usePublicBgp": 0, "username": "", "verifyCertificate": 1 }, ... ] }

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

GET /v6/endpoint-tests/{testId} Scheduled Test Details

Returns details for an endpoint scheduled test, including test type, name, intervals, targets and alert rules.

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 endpoint scheduled test you wish to retrieve
  • There is no request body for this request.

Response

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

Example

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

Header

HTTP/1.1 200 OK Server: nginx Date: Sat, 25 Aug 2018 17:03:57 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 235 X-Organization-Rate-Limit-Reset: 1535216640 Strict-Transport-Security: max-age=31536000 X-Content-Type-Options: nosniff X-Server-Name: 1-5

Body

{ "endpointTest": [ { "alertsEnabled": 0, "apiLinks": [...], "bandwidthMeasurements": 0, "bgpMeasurements": 0, "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "createdDate": "2018-08-25 16:56:50", "enabled": 1, "interval": 60, "agentSelectorConfig": { "agentIds": [], "agentSelectorType": "ANY_AGENT", "labelIds": [], "maxMachines": 25 }, "modifiedBy": "API Sandbox User (noreply@thousandeyes.com)", "modifiedDate": "2018-08-25 16:57:59", "mtuMeasurements": 0, "networkMeasurements": 1, "port": -1, "protocol": "ICMP", "savedEvent": 0, "server": "www.thousandeyes.com", "testId": 282, "testName": "ThousandeEyes", "type": "agent-to-server", "usePublicBgp": 0 } ] }

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

Scheduled Test Metadata

Endpoint test fields are shown in the table below.

Fields are listed alphabetically by test type below.

These fields are system-generated and read only, and displayed as part of test metadata.

Test TypeFieldData TypeAcceptable ValuesNotes
(all)alertsEnabledinteger0 or 11 to enable alerts, or 0 to disable alerts
(all)apiLinksarray of apiLinks objectsArray of apiLink objects, showing rel and href elementsSelf links to endpoint to pull test metadata, and data links to endpoint for test data
(all)bandwidthMeasurementsinteger0 or 11 to measure bandwidth
(all)bgpMeasurementsinteger0 or 11 to enable bgp measurements
(all)createdBystringUsername (email@company.com)User’s email
(all)createdDatestringYYYY-MM-DD HH:mm:ss formatted dateShown in UTC
(all)enabledinteger0 or 11 to enable the test, 0 to disable the test
(all)intervalinteger[60, 120, 300, 600, 900, 1800, 3600]Value in seconds
(all)agentSelectorConfigobject{agentIds: array of strings, agentSelectorType: enum value, labelIds: array of longs, maxMachines: [1-10000]}Agent selection object
(all)agentSelectorConfig.agentIdsarray of stringssee notesList of agent ids. Must be set if agentSelectorType == SPECIFIC_AGENTS
(all)agentSelectorConfig.agentSelectorTypestringANY_AGENT, SPECIFIC_AGENTS, LIST_OF_LABELSAgent selection type: either all agents available, or list of agents, of list of agent labels
(all)agentSelectorConfig.labelIdsarray of longssee notesList of label ids. Must be set if agentSelectorType == LIST_OF_LABELS
(all)agentSelectorConfig.maxMachinesinteger[1-10000]Upper limit of machines for the test
(all)modifiedBystringUsername (email@company.com)User’s email
(all)modifiedDatestringYYYY-MM-DD HH:mm:ss formatted dateShown in UTC
(all)mtuMeasurementsinteger0 or 11 to measure MTU sizes on network tests
(all)networkMeasurementsinteger0 or 11 to perform network tests
(all)portinteger(1..65535)TCP port used to perform the test; if ICMP is selected, -1 is returned
(all)protocolstringTCP or ICMPProtocol used to perform the test
(all)savedEventinteger0 or 1Indicates 1 for a saved event, 0 for a normal test
(all)serverstring(any)Target domain name or IP address
(all)testIdintegerunique ID of testEach test is assigned a unique ID; this is used to access test data from other endpoints
(all)testNamestring(any)Test name must be unique
(all)typestringtype of test being queriedTest type is implicit in the test creation url
(all)usePublicBgpinteger0 or 1Use all the public BGP montiors
HTTP ServerauthTypestring“NONE”, “BASIC”, or “NTLM”Type of authentication for the test
HTTP ServercontentRegexstringRegular ExpressionsThis field does not require escaping
HTTP ServerfollowRedirectsinteger0 or 10 to not follow HTTP/301 or HTTP/302 redirect directives.
HTTP ServerhttpTargetTimeinteger(100..5000)Target time for HTTP server completion; specified in milliseconds
HTTP ServerhttpTimeLimitinteger(5000..60000)Target time for HTTP Server timeout; specified in milliseconds
HTTP ServerhttpVersioninteger[1,2]2 for prefer HTTP/2, 1 for HTTP/1.1 only
HTTP ServerpostBodystringsee notesIf the post body is set to something other than empty, the requestMethod will be set to POST
HTTP ServersslVersionstringcorresponds to sslVersionIdReflects the verbose ssl protocol version used by a test
HTTP ServersslVersionIdinteger[0,3,4,5,6]0 for default (Auto), 6 for TLS1.2, 5 for TLS1.1, 4 for TLS1.0, 3 for SSLv3
HTTP Serverurlstringsee notesTarget for the test
HTTP ServeruseNtlminteger0 or 11 for NTLM, 0 for Basic Authentication. Requires username/password to be set
HTTP ServeruserAgentstringsee notesuser-agent string to be provided during the test
HTTP Serverusernamestringsee notesusername to be used for Basic/NTLM authentication
HTTP SerververifyCertificateinteger0 or 10 to ignore certificate errors

POST /v6/endpoint-tests/{testType}/new Creating a Scheduled Test

Creates a new Endpoint 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.

Request

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

    • agent-to-server - endpoint network test
    • http-server - endpoint http test
  • Request body should contain fields to be set during creation.

Example - http test

$ curl -i https://api.thousandeyes.com/v6/endpoint-tests/http-server/new.json \ -d '{ "authType": "NONE", "flagPing": true, "flagTraceroute": true, "agentSelectorType": "ANY_AGENT", "httpTimeLimit": 5000, "maxMachines": 5, "interval" : 3600, "sslVersion": 0, "targetResponseTime": 5000, "testName": "HTTP test", "url": "www.example.com", "verifyCertHostname": true }' \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -u {email}:{authToken}

FieldData TypeUnitsNotes
agentIdsarray of stringsn/aList of agent ids. Must be set if agentSelectorType == SPECIFIC_AGENTS
agentSelectorTypestringANY_AGENT, SPECIFIC_AGENTS, LIST_OF_LABELSAgent selection type: either all agents available, or list of agents, of list of agent labels
authTypestringn/aAuthentication type: NONE, BASIC or NTLM
flagPingbooleann/aOptional flag indicating if test should run ping. If not specified, true is used by default
flagTraceroutebooleann/aOptional flag indicating if test should run traceroute. If not specified, true is used by default
groupIdintegern/a(Deprecated) Unique ID of the label, which can be retrieved or created by Labels API. Should be substituted by combination of agentSelectorType, agentIds and labelIds
httpTimeLimitintegermillisecondsMaximum amount of time in milliseconds the agents wait before a request times out
intervalinteger[120, 300, 600, 900, 1800, 3600]Interval in seconds that the test will execute on
labelIdsarray of longsn/aList of label ids. Must be set if agentSelectorType == LIST_OF_LABELS
maxMachinesinteger[1-100000]Upper limit of machines which can execute this test
networkProtocolStringn/aICMP or TCP, default ICMP
passwordstringn/aPassword if authentication was specified to BASIC or NTLM
pathtraceInSessionStringn/aFirst initiates a TCP session with the target server and sends path trace packets within that TCP session. Applicable only if TCP is selected as a network protocol
portintegern/aPort number, if not specified, the port is selected based on a protocol (HTTP 80, HTTPS 443)
sslVersionintegern/aSsl protocol version (0 - AUTO, 3 - SSL v3, 4 - TLS v1.0, 5 - TLS 1.1, 6 - TLS 1.2)
targetResponseTimeintegermillisecondsAffects the colours of agents and legends on the view page. The value is compared with actual response time in order to determine the color scale (from green to red)
testNamestringn/aName of the test
tcpProbeModeStringn/aTCP mode: AUTO, SYN or SACK. Applicable only if TCP is selected as a network protocol,
urlstringn/aTest target URL, for example “www.example.com”. Optionally, it can specify a protocol (http or https). If the protocol is not specified, “https” is used by default
usernamestringn/aUser name if authentication was specified to BASIC or NTLM
verifyCertHostnamebooleann/aFlag indicating if a certificate should be verified

Example - network test

$ curl -i https://api.thousandeyes.com/v6/endpoint-tests/agent-to-server/new.json \ -d '{ "flagPing": true, "flagTraceroute": true, "interval" : 3600, "agentSelectorType": "ANY_AGENT", "agentIds": ["LAPTOP-MAC-AGENT", "PC-WINDOWS-AGENT"], "maxMachines": 5, "serverName": "www.example.com", "port": 80, "testName": "Network test" }' \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -u {email}:{authToken}

FieldData TypeUnitsNotes
agentIdsarray of stringsn/aList of agent ids. Must be set if agentSelectorType == SPECIFIC_AGENTS
flagPingbooleann/aOptional flag indicating if test should run ping. If not specified, true is used by default
flagTraceroutebooleann/aOptional flag indicating if test should run traceroute. If not specified, true is used by default
groupIdintegern/a(Deprecated) Unique ID of the label, which can be retrieved or created by Labels API. Should be substituted by combination of agentSelectorType, agentIds and labelIds
intervalinteger[120, 300, 600, 900, 1800, 3600]Interval in seconds that the test will execute on
labelIdsarray of longsn/aList of label ids. Must be set if agentSelectorType == LIST_OF_LABELS
maxMachinesinteger[1-100000]Maximum number of agents which can execute this test
agentSelectorTypestringANY_AGENT, SPECIFIC_AGENTS, LIST_OF_LABELSAgent selection type: either all agents available, or list of agents, of list of agent labels
portintegern/aPort number, if not specified, it’s set to 80 by default
serverNamestringn/aA server address without a protocol (for example “www.example.com”) or IP address
testNamestringn/aName of the test

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.

Response does not include the results of the test. Once the test has been run, results can be retrieved using Endpoint Test Data endpoints. API test data endpoints URLs are provided in test definition output upon test creation. See the example below.

Header

HTTP/1.1 201 Created Server: nginx Date: Mon, 17 Feb 2020 13:41:02 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 600 X-Organization-Rate-Limit-Remaining: 599 X-Organization-Rate-Limit-Reset: 1490622120 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

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

Body

{ "endpointTest": [ { "alertsEnabled": 0, "apiLinks": [ { "href": "https://api.thousandeyes.com/v6/endpoint-data/tests/net/metrics/9902783", "rel": "data" }, { "href": "https://api.thousandeyes.com/v6/endpoint-data/tests/net/path-vis/9902783", "rel": "data" }, { "href": "https://api.thousandeyes.com/v6/endpoint-data/tests/web/http-server/9902783", "rel": "data" }, { "href": "https://api.thousandeyes.com/v6/endpoint-tests/9902783", "rel": "self" } ], "authType": "NONE", "bandwidthMeasurements": 0, "bgpMeasurements": 0, "createdBy": "API User (noprely@thousandeyes.com)", "createdDate": "2020-02-17 11:11:19", "enabled": 1, "followRedirects": 1, "httpTargetTime": 5000, "httpTimeLimit": 5000, "httpVersion": 1, "interval": 60, "agentSelectorConfig": { "agentIds": [], "agentSelectorType": "LIST_OF_LABELS", "labelIds": [10581, 12461], "maxMachines": 25 }, "modifiedBy": "API User (noprely@thousandeyes.com)", "modifiedDate": "2020-02-17 11:11:19", "mtuMeasurements": 0, "networkMeasurements": 1, "port": 443, "protocol": "TCP", "savedEvent": 0, "server": "www.example.com", "sslVersion": "Auto", "sslVersionId": 0, "testId": 9902783, "testName": "HTTP test", "type": "http-server", "url": "https://www.example.com", "useNtlm": 0, "usePublicBgp": 0, "username": "", "verifyCertificate": 1 } ] }

GET /v6/endpoint-automated-session-tests Automated Session Test List

Returns a list of all endpoint automated session tests configured in ThousandEyes. This list does not contain saved events.

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 endpoint automated session tests. See Endpoint Automated Session Test Metadata page for information on fields returned by this endpoint.

Example

$ curl https://api.thousandeyes.com/v6/endpoint-automated-session-tests.json \ -u {email}:{authToken}

Header

HTTP/1.1 200 OK Server: nginx Date: Sat, 25 Aug 2018 17:03:50 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 237 X-Organization-Rate-Limit-Reset: 1535216640 Strict-Transport-Security: max-age=31536000 X-Content-Type-Options: nosniff X-Server-Name: 1-3

Body

{ "automatedSessionTests": [ { "alertsEnabled": 0, "apiLinks": [...], "bandwidthMeasurements": 0, "bgpMeasurements": 0, "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "createdDate": "2018-08-25 16:56:50", "enabled": 1, "interval": 60, "application": "WEBEX", "modifiedBy": "API Sandbox User (noreply@thousandeyes.com)", "modifiedDate": "2018-08-25 16:57:59", "mtuMeasurements": 0, "networkMeasurements": 1, "port": -1, "protocol": "ICMP", "savedEvent": 0, "server": "www.thousandeyes.com", "testId": 282, "testName": "ThousandeEyes", "type": "agent-to-server", "usePublicBgp": 0 }, ... ] }

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

GET /v6/endpoint-automated-session-tests/{testId} Automated Session Test Details

Returns details for an endpoint automated session test, including test type, name, intervals, targets.

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 endpoint scheduled test you wish to retrieve
  • There is no request body for this request.

Response

Sends back all metadata for the requested endpoint automated session test. See Endpoint Automated Session Test Metadata page for more information on fields returned by this endpoint.

Example

$ curl https://api.thousandeyes.com/v6/endpoint-automated-session-tests/282.json \ -u {email}:{authToken}

Header

HTTP/1.1 200 OK Server: nginx Date: Sat, 25 Aug 2018 17:03:57 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 235 X-Organization-Rate-Limit-Reset: 1535216640 Strict-Transport-Security: max-age=31536000 X-Content-Type-Options: nosniff X-Server-Name: 1-5

Body

{ "automatedSessionTests": [ { "alertsEnabled": 0, "apiLinks": [...], "bandwidthMeasurements": 0, "bgpMeasurements": 0, "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "createdDate": "2018-08-25 16:56:50", "enabled": 1, "interval": 60, "application": "WEBEX", "modifiedBy": "API Sandbox User (noreply@thousandeyes.com)", "modifiedDate": "2018-08-25 16:57:59", "mtuMeasurements": 0, "networkMeasurements": 1, "port": -1, "protocol": "ICMP", "savedEvent": 0, "server": "www.thousandeyes.com", "testId": 282, "testName": "ThousandeEyes", "type": "agent-to-server", "usePublicBgp": 0 } ] }

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

Automated Session Test Metadata

Endpoint Automated Session Test fields are shown in the table below.

Fields are listed alphabetically by test type below.

These fields are system-generated and read only, and displayed as part of test metadata.

FieldData TypeAcceptable ValuesNotes
alertsEnabledinteger0 or 11 to enable alerts, or 0 to disable alerts
apiLinksarray of apiLinks objectsArray of apiLink objects, showing rel and href elementsSelf links to endpoint to pull test metadata, and data links to endpoint for test data
bandwidthMeasurementsinteger0 or 11 to measure bandwidth
bgpMeasurementsinteger0 or 11 to enable bgp measurements
createdBystringUsername (email@company.com)User’s email
createdDatestringYYYY-MM-DD HH:mm:ss formatted dateShown in UTC
enabledinteger0 or 11 to enable the test, 0 to disable the test
intervalinteger[60, 120, 300, 600, 900, 1800, 3600]Value in seconds
modifiedBystringUsername (email@company.com)User’s email
modifiedDatestringYYYY-MM-DD HH:mm:ss formatted dateShown in UTC
mtuMeasurementsinteger0 or 11 to measure MTU sizes on network tests
networkMeasurementsinteger0 or 11 to perform network tests
portinteger(1..65535)TCP port used to perform the test; if ICMP is selected, -1 is returned
protocolstringTCP or ICMPProtocol used to perform the test
savedEventinteger0 or 1Indicates 1 for a saved event, 0 for a normal test
serverstring(any)Target domain name or IP address
testIdintegerUnique ID of testEach test is assigned a unique ID; this is used to access test data from other endpoints
testNamestring(any)Test name must be unique
typestringType of test being queriedTest type is implicit in the test creation url
usePublicBgpinteger0 or 1Use all the public BGP monitors
applicationstringWEBEX,MSTEAMS,ZOOMWhich supported application to monitor

POST /v6/endpoint-automated-session-tests/new Creating an Automated Session Test

Creates a new Endpoint Automated Session 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.

Request

  • Request body should contain fields to be set during creation.

Example - AST test

$ curl -i https://api.thousandeyes.com/v6/endpoint-automated-session-tests/new.json \ -d '{ "flagPing": true, "flagTraceroute": true, "interval" : 3600, "maxMachines": 5, "application": "WEBEX", "labelIds": [1, 2, 3], "testName": "Network test" }' \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -u {email}:{authToken}

FieldData TypeUnitsNotes
agentIdsarray of stringsn/aList of agent ids. Must be set if agentSelectorType == SPECIFIC_AGENTS
flagPingbooleann/aOptional flag indicating if test should run ping. If not specified, true is used by default
flagTraceroutebooleann/aOptional flag indicating if test should run traceroute. If not specified, true is used by default
intervalinteger[120, 300, 600, 900, 1800, 3600]Interval in seconds that the test will execute on
labelIdsarray of longsn/aList of label ids. Must be set if agentSelectorType == LIST_OF_LABELS
maxMachinesinteger[1-100000]Maximum number of agents which can execute this test
testNamestringn/aName of the test
applicationstringn/amonitored application, can be one of WEBEX, ZOOM, MSTEAMS

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.

Response does not include the results of the test. Once the test has been run, results can be retrieved using Endpoint Test Data endpoints. API test data endpoints URLs are provided in test definition output upon test creation. See the example below.

Header

HTTP/1.1 201 Created Server: nginx Date: Mon, 17 Feb 2020 13:41:02 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 600 X-Organization-Rate-Limit-Remaining: 599 X-Organization-Rate-Limit-Reset: 1490622120 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

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

Body

{ "automatedSessionTests": [ { "createdDate": "2022-05-06 09:20:27", "modifiedDate": "2022-05-06 09:20:27", "createdBy": "API User (noprely@thousandeyes.com)", "modifiedBy": "API User (noprely@thousandeyes.com)", "enabled": 1, "savedEvent": 0, "testId": 9918128, "testName": " . . .. . . .. ", "interval": 60, "subinterval": -1, "port": 443, "protocol": "ICMP", "networkMeasurements": 1, "mtuMeasurements": 0, "bandwidthMeasurements": 0, "bgpMeasurements": 0, "usePublicBgp": 0, "application": "WEBEX", "apiLinks": [ { "rel": "self", "href": "https://api.stg.thousandeyes.com/v6/endpoint-automated-session-tests/9918128" }, { "rel": "data", "href": "https://api.stg.thousandeyes.com/v6/endpoint-data/automated-session-tests/net/metrics/9918128" }, { "rel": "data", "href": "https://api.stg.thousandeyes.com/v6/endpoint-data/automated-session-tests/net/path-vis/9918128" } ] } ] }

© 2023 ThousandEyes. All rights reserved.