Endpoint Scheduled Tests

GET /v6/endpoint-tests Endpoint 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 noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

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, "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} Endpoint 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 noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

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.

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, "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} Endpoint 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 noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

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

Endpoint test metadata

Endpoint test fields are shown in the table below. Endpoint tests can’t be created or updated using the API.

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)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 an Endpoint 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, "groupId": 42, "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 noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

FieldData TypeUnitsNotes
testNamestringn/aName of the test
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
maxMachinesinteger[1-5000]maximal number of agents which can execute this test
intervalinteger[120, 300, 600, 900, 1800, 3600]interval in seconds that the test will execute on
groupIdintegern/aunique ID of the label, which can be retrieved or created by Labels API
sslVersionintegern/assl protocol version (0 - AUTO, 3 - SSL v3, 4 - TSL v1.0, 5 - TSL 1.1, 6 - TSL 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)
verifyCertHostnamebooleann/aflag indicating if a certificate should be verified
authTypestringn/aauthentication type: NONE, BASIC or NTLM
usernamestringn/auser name if authentication was specified to BASIC or NTLM
passwordstringn/apassword if authentication was specified to BASIC or NTLM
httpTimeLimitintegermillisecondsmaximum amount of time in milliseconds the agents wait before a request times out
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
portintegern/aport number, if not specified, the port is selected based on a protocol (HTTP 80, HTTPS 443)
networkProtocolStringn/aICMP or TCP, default ICMP
tcpProbeModeStringn/aTCP mode: AUTO, SYN or SACK. Applicable only if TCP is selected as a network protocol,
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

Example - network test

$ curl -i https://api.thousandeyes.com/v6/endpoint-tests/agent-to-server/new.json \ -d '{ "flagPing": true, "flagTraceroute": true, "interval" : 3600, "groupId": "23020", "maxMachines": 5, "serverName": "www.example.com", "port": 80, "testName": "Network test" }' \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

FieldData TypeUnitsNotes
testNamestringn/aName of the test
serverNamestringn/aa server address without a protocol (for example “www.example.com”) or IP address
maxMachinesinteger[1-5000]maximal number of agents which can execute this test
intervalinteger[120, 300, 600, 900, 1800, 3600]interval in seconds that the test will execute on
groupIdintegern/aunique ID of the label, which can be retrieved or created by Labels API
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
portintegern/aport number, if not specified, it’s set to 80 by default

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.

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, "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 } ] }