GET
/v6/endpoint-agents
Listing all agents
Returns a list of all endpoint agents in a given account group.
Optional (Querystring) Parameters
format=json|xmloptional, specifies the format of output requested. See Output Formats for more informationaid={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-groupsendpoint. Specifying this parameter without the user being assigned to the target account will result in an error response. See Account group context for more informationdeleted=true|falsespecifies if deleted agents should be returned too. By default it is false - only non-deleted agents are returnedagentName={agent_name}returns only agents with a given namecomputerName={computer_name}returns only agents with a given computer name
Request
- There is no request body for this request.
Response
Sends back an array of endpoint agents. Account groups with a larger number of agents will have the response paginated - details about response pagination can be found here.
Each endpoint agent consists of the following fields:
| Field | Data Type | Notes |
|---|---|---|
| agentId | string | unique ID of the Endpoint agent |
| agentName | string | display name of the agent |
| computerName | string | display name of the computer |
| osVersion | string | version of the OS computer is running |
| kernelVersion | string | version of the kernel computer is running |
| manufacturer | string | computer hardware manufacturer |
| model | string | computer hardware model |
| totalMemory | string | total memory (RAM) of the computer |
| lastSeen | datetime | last time when agent checked-in |
| status | string | status of the Endpoint agent in ThousandEyes, set to “enabled” or “disabled” |
| deleted | bool | set to true if the Endpoint agent has been deleted, false otherwise |
| version | string | version of the Endpoint agent |
| createdTime | datetime | date and time when the Endpoint agent was installed |
| numberOfClients | integer | the number of user accounts associated with the machine where the Endpoint agent is installed |
| publicIP | string | public IP of the Endpoint agent used for the most recent check-in |
| location | object | location of the Endpoint agent resolved during last check-in, see location object below for details |
| clients | array | the user accounts on the machine where the Endpoint agent is installed, see client below for details |
| agentType | string | type of the Endpoint agent, valid values are “enterprise” for Endpoint agent Enterprise, and “enterprise-pulse” for an Endpoint agent Pulse |
| proxyId | integer | proxyId if the agent is configured to use a proxy server |
| vpnProfiles | array | list of VPNs that the Endpoint Agent detected in its last checkin. See vpnProfile below for details |
| networkInterfaceProfiles | array | list of network interfaces. See interfaceProfile below for details |
Each client corresponds to one OS account and consists of the following fields:
| Field | Data Type | Notes |
|---|---|---|
| browserExtensions | array | if installed, details about endpoint browser extensions, see browserExtensions object below |
| userProfile | object | user profile containing a user name. The name is extracted from operating system account when endpoint agent is installed |
location object:
| Field | Data Type | Notes |
|---|---|---|
| latitude | double | approximate GPS latitude of the Endpoint agent |
| longitude | double | approximate GPS longitude of the Endpoint agent |
| locationName | string | geographic name of the Endpoint agent’s location |
browserExtensions object:
| Field | Data Type | Notes |
|---|---|---|
| browser | string | name of the browser where the extension is installed, “CHROME,” “EDGE” or “IE” |
| profile | string | name of the browser profile where the extension is installed |
| version | string | endpoint agent browser extension version number |
| enabled | bool | flag indicating if the extension is “disabled” or “enabled” in the web browser |
| active | bool | flag indicating if there is communication between the extension and ThousandEyes portal |
| error | string | any errors encountered while getting extension status |
vpnProfile object:
| Field | Data Type | Notes |
|---|---|---|
| interfaceName | string | interface name associated with interfaceProfile. See interfaceProfile object below |
| vpnType | string | name of the VPN provider. For example, “CiscoAnyConnect” or “ZscalerInternet” |
| vpnGatewayAddress | string | IP address of the VPN gateway |
| vpnClientAddresses | array | list of private IP addresses that the VPN server assigned to the device |
| vpnClientNetworkRange | array | list of private networks that the VPN server assigned to the device |
interfaceProfile object:
| Field | Data Type | Notes |
|---|---|---|
| interfaceName | string | name of the network interface |
| addressProfiles | array | an array of address profiles. See addressProfile object below |
| hardwareType | enum | name of hardware type - WIRELESS, ETHERNET, MODEM, VIRTUAL, OTHER or UNKNOWN. |
| ethernetProfile | object | this field is present only if the hardware type of this interface is determined to be ETHERNET. See ethernetProfile object below |
| wirelessProfile | object | this field is present only if the hardware type of this interface is determined to be WIRELESS. See wirelessProfile object below |
addressProfile object:
| Field | Data Type | Notes |
|---|---|---|
| addressType | enum | the address type. Can be UNIQUE_LOCAL (an address that is routable only in the scope of a private network) or UNIQUE_GLOBAL (an address that is globally routable) |
| ipAddress | string | IP address of this interface in the network it’s currently connected to |
| prefixLength | string | the number of bits representing the network part of ipAddress |
| gateway | string | default gateway for this interface. |
| routerHardwareAddress | string | router’s MAC address resolved from an ARP request |
ethernetProfile object:
| Field | Data Type | Notes |
|---|---|---|
| linkSpeed | integer | link speed in Mbps |
wirelessProfile object:
| Field | Data Type | Notes |
|---|---|---|
| bssid | string | basic service set identifier (MAC) |
| ssid | string | service set identifier (name) |
| rssi | integer | received signal strength indicator |
| channel | integer | wireless network channel |
| phyMode | string | physical mode, for example 802.11ac |
Example
$ curl https://api.thousandeyes.com/v6/endpoint-agents.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
{
"pages": {
"next": "https://api.thousandeyes.com/v6/endpoint-agents?pageId=cd9cf945-f66f-4945-b5fe-f7a9a2a97896"
},
"endpointAgents": [
{
"agentId": "5d0764ac-7e42-4ec8-a0d4-39fc53edccba",
"agentName": "test-agent-1",
"computerName": "windows machine",
"osVersion": "Microsoft Windows 10 Enterprise",
"kernelVersion": "10.0.18362",
"manufacturer": "LENOVO",
"model": "20HR000FUS",
"status": "enabled",
"deleted": false,
"createdTime": "2017-06-29 22:05:36",
"lastSeen": "2020-02-20 23:56:43",
"version": "0.191.0",
"publicIP": "13.227.74.44",
"location": {
"latitude": 51.51130676269531,
"longitude": -0.271392822265625,
"locationName": "London, England, UK"
},
"clients": [
{
"userProfile": {
"userName": "pzielinski"
},
"browserExtensions": [
{
"browser": "CHROME",
"profile": "Profile 1",
"version": "1.11.0",
"installed": true,
"enabled": true,
"active": true
}
]
}
],
"totalMemory": "16384 MB",
"agentType": "enterprise",
"vpnProfiles": [
{
"vpnGatewayAddress": "18.64.79.52",
"vpnType": "CiscoAnyConnect",
"vpnClientAddresses": ["10.136.56.58"],
"vpnClientNetworkRange": ["10.136.32.0/19"]
}
]
},
{
"agentId": "36ebc26d-19fe-443d-a9bd-cf4ae8f021f0",
"agentName": "test-agent-2",
"computerName": "mac os",
"osVersion": "Version 10.15.2 (Build 19C57)",
"kernelVersion": "Darwin 19.2.0",
"manufacturer": "Apple, Inc.",
"model": "MacBookAir7,2",
"status": "enabled",
"deleted": false,
"createdTime": "2017-06-29 22:05:36",
"lastSeen": "2020-02-20 23:56:43",
"version": "0.191.0",
"publicIP": "13.227.74.43",
"location": {
"latitude": 51.51130676269531,
"longitude": -0.271392822265625,
"locationName": "London, England, UK"
},
"clients": [
{
"userProfile": {
"userName": "pzielinski"
},
"browserExtensions": [
{
"browser": "CHROME",
"profile": "Profile 1",
"version": "1.11.0",
"installed": true,
"enabled": true,
"active": true
}
]
}
],
"totalMemory": "16384 MB",
"agentType": "enterprise",
"vpnProfiles": [
{
"vpnGatewayAddress": "18.64.79.52",
"vpnType": "CiscoAnyConnect",
"vpnClientAddresses": ["10.136.56.58"],
"vpnClientNetworkRange": ["10.136.32.0/19"]
}
],
"networkInterfaceProfiles": [
{
"interfaceName": "en0",
"addressProfiles": [
{
"addressType": "UNIQUE_LOCAL",
"ipAddress": "192.168.1.64",
"prefixLength": 24,
"gateway": "192.168.1.254",
"routerHardwareAddress": "5c:b1:3e:46:1c:84"
}
],
"hardwareType": "WIRELESS",
"wirelessProfile": {
"bssid": "5c:b1:3e:46:1c:87",
"ssid": "PLUSNET-2CNJ-5ghz",
"rssi": -56,
"channel": 48,
"phyMode": "802.11ac"
}
},
{
"interfaceName": "utun4",
"addressProfiles": [
{
"addressType": "UNIQUE_GLOBAL",
"ipAddress": "2a01:4b00:bd04:d000:1c63:3302:4092:220d",
"prefixLength": 64,
"gateway": "fe80::6620:9fff:fe11:58f6",
"routerHardwareAddress": "64:20:9f:11:58:f6"
},
],
"hardwareType": "VIRTUAL"
}]
},
},
...
]
}
For more information on our response status codes, see the response status codes documentation.