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
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}
| Field | Data Type | Units | Notes |
|---|
| agentIds | array of strings | n/a | List of agent ids. Must be set if agentSelectorType == SPECIFIC_AGENTS |
| agentSelectorType | string | ANY_AGENT, SPECIFIC_AGENTS, LIST_OF_LABELS | Agent selection type: either all agents available, or list of agents, of list of agent labels |
| authType | string | n/a | Authentication type: NONE, BASIC or NTLM |
| flagPing | boolean | n/a | Optional flag indicating if test should run ping. If not specified, true is used by default |
| flagTraceroute | boolean | n/a | Optional flag indicating if test should run traceroute. If not specified, true is used by default |
| groupId | integer | n/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 |
| httpTimeLimit | integer | milliseconds | Maximum amount of time in milliseconds the agents wait before a request times out |
| interval | integer | [120, 300, 600, 900, 1800, 3600] | Interval in seconds that the test will execute on |
| labelIds | array of longs | n/a | List of label ids. Must be set if agentSelectorType == LIST_OF_LABELS |
| maxMachines | integer | [1-100000] | Upper limit of machines which can execute this test |
| networkProtocol | String | n/a | ICMP or TCP, default ICMP |
| password | string | n/a | Password if authentication was specified to BASIC or NTLM |
| pathtraceInSession | String | n/a | First 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 |
| port | integer | n/a | Port number, if not specified, the port is selected based on a protocol (HTTP 80, HTTPS 443) |
| sslVersion | integer | n/a | Ssl protocol version (0 - AUTO, 3 - SSL v3, 4 - TLS v1.0, 5 - TLS 1.1, 6 - TLS 1.2) |
| targetResponseTime | integer | milliseconds | Affects 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) |
| testName | string | n/a | Name of the test |
| tcpProbeMode | String | n/a | TCP mode: AUTO, SYN or SACK. Applicable only if TCP is selected as a network protocol, |
| url | string | n/a | Test 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 |
| username | string | n/a | User name if authentication was specified to BASIC or NTLM |
| verifyCertHostname | boolean | n/a | Flag 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}
| Field | Data Type | Units | Notes |
|---|
| agentIds | array of strings | n/a | List of agent ids. Must be set if agentSelectorType == SPECIFIC_AGENTS |
| flagPing | boolean | n/a | Optional flag indicating if test should run ping. If not specified, true is used by default |
| flagTraceroute | boolean | n/a | Optional flag indicating if test should run traceroute. If not specified, true is used by default |
| groupId | integer | n/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 |
| interval | integer | [120, 300, 600, 900, 1800, 3600] | Interval in seconds that the test will execute on |
| labelIds | array of longs | n/a | List of label ids. Must be set if agentSelectorType == LIST_OF_LABELS |
| maxMachines | integer | [1-100000] | Maximum number of agents which can execute this test |
| agentSelectorType | string | ANY_AGENT, SPECIFIC_AGENTS, LIST_OF_LABELS | Agent selection type: either all agents available, or list of agents, of list of agent labels |
| port | integer | n/a | Port number, if not specified, it’s set to 80 by default |
| serverName | string | n/a | A server address without a protocol (for example “www.example.com”) or IP address |
| testName | string | n/a | Name 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.
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
}
]
}