Endpoint agents

GET /v6/endpoint-agents Listing all agents

Returns a list of all endpoint agents in a given account group.

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
  • deleted=true|false specifies if deleted agents should be returned too. By default it is false - only non-deleted agents are returned
  • agentName={agent_name} returns only agents with a given name
  • computerName={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:

FieldData TypeNotes
agentIdstringunique ID of the Endpoint agent
agentNamestringdisplay name of the agent
computerNamestringdisplay name of the computer
osVersionstringversion of the OS computer is running
kernelVersionstringversion of the kernel computer is running
manufacturerstringcomputer hardware manufacturer
modelstringcomputer hardware model
totalMemorystringtotal memory (RAM) of the computer
lastSeendatetimelast time when agent checked-in
statusstringstatus of the Endpoint agent in ThousandEyes, set to “enabled” or “disabled”
deletedboolset to true if the Endpoint agent has been deleted, false otherwise
versionstringversion of the Endpoint agent
createdTimedatetimedate and time when the Endpoint agent was installed
numberOfClientsintegerthe number of user accounts associated with the machine where the Endpoint agent is installed
publicIPstringpublic IP of the Endpoint agent used for the most recent check-in
locationobjectlocation of the Endpoint agent resolved during last check-in, see location object below for details
clientsarraythe user accounts on the machine where the Endpoint agent is installed, see client below for details
agentTypestringtype of the Endpoint agent, valid values are “enterprise” for Endpoint agent Enterprise, and “enterprise-pulse” for an Endpoint agent Pulse
proxyIdintegerproxyId if the agent is configured to use a proxy server

Each client corresponds to one OS account and consists of the following fields:

FieldData TypeNotes
browserExtensionsarrayif installed, details about endpoint browser extensions, see browserExtensions object below
userProfileobjectuser profile containing a user name. The name is extracted from operating system account when endpoint agent is installed

location object:

FieldData TypeNotes
latitudedoubleapproximate GPS latitude of the Endpoint agent
longitudedoubleapproximate GPS longitude of the Endpoint agent
locationNamestringgeographic name of the Endpoint agent’s location

browserExtensions object:

FieldData TypeNotes
browserstringname of the browser where the extension is installed, “CHROME,” “EDGE” or “IE”
profilestringname of the browser profile where the extension is installed
versionstringendpoint agent browser extension version number
enabledboolflag indicating if the extension is “disabled” or “enabled” in the web browser
activeboolflag indicating if there is communication between the extension and ThousandEyes portal
errorstringany errors encountered while getting extension status

Example

$ curl https://api.thousandeyes.com/v6/endpoint-agents.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

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

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

GET /v6/endpoint-agents/{agent_id} Getting an agent by id

Returns information about the agent with a given id.

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

  • {agent_id} corresponds the unique ID of an endpoint agent, obtained from the /endpoint-agents endpoint
  • There is no request body for this request

Response

Returns information about the agent with a given id. See Listing all agents for details of each field.

Example

$ curl https://api.thousandeyes.com/v6/endpoint-agents/5d0764ac-7e42-4ec8-a0d4-39fc53edccba.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

{ "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", "lastSeen": "2020-02-20 23:56:43", "status": "enabled", "deleted": false, "version": "0.191.0", "createdTime": "2017-06-29 22:05:36", "numberOfClients": 3, "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" } ] }

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

POST /v6/endpoint-agents/{agent_id} Updating an agent

Updates a given agent with a new name.

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

  • {agent_id} corresponds the unique ID of an endpoint agent, obtained from the /endpoint-agents endpoint
  • Currently the only request body supported is to change the Agent Name, as follows:

{ "newAgentName":"new name" }

Response

Returns information about the updated agent. See Listing all agents for details of each field.

Example

$ curl https://api.thousandeyes.com/v6/endpoint-agents/5d0764ac-7e42-4ec8-a0d4-39fc53edccba.json \ -d '{"newAgentName":"new name"}' \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

HTTP/1.1 200 OK Server: nginx Date: Fri, 24 Apr 2020 15:59: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: 1587744000 Strict-Transport-Security: max-age=31536000 X-Content-Type-Options: nosniff X-Server-Name: 1-3

Body

{ "endpointAgents": [ { "agentId": "5d0764ac-7e42-4ec8-a0d4-39fc53edccba", "agentName": "new name", "computerName": "Windows machine", "osVersion": "Microsoft Windows 10 Enterprise", "kernelVersion": "10.0.18362", "manufacturer": "LENOVO", "model": "20HR000FUS", "lastSeen": "2020-02-20 23:56:43", "status": "enabled", "deleted": false, "version": "0.191.0", "createdTime": "2017-06-29 22:05:36", "numberOfClients": 3, "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" } ] }

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

POST /v6/endpoint-agents/{agent_id}/enable Enabling an agent

Enables an agent with a given id.

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

  • {agent_id} corresponds the unique ID of an endpoint agent, obtained from the /endpoint-agents endpoint
  • There is no request body for this request

Response

Sends back the enabled agent details. See Listing all agents for details of each field.

Example

$ curl https://api.thousandeyes.com/v6/endpoint-agents/5d0764ac-7e42-4ec8-a0d4-39fc53edccba/enable.json \ -d '' \ -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

{ "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", "lastSeen": "2020-02-20 23:56:43", "status": "enabled", "deleted": false, "version": "0.191.0", "createdTime": "2017-06-29 22:05:36", "numberOfClients": 3 } ] }

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

POST /v6/endpoint-agents/{agent_id}/disable Disabling an agent

Disables an agent with a given id.

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

  • {agent_id} corresponds the unique ID of an endpoint agent, obtained from the /endpoint-agents endpoint
  • There is no request body for this request

Response

Sends back the disabled agent details. See Listing all agents for details of each field.

Example

$ curl https://api.thousandeyes.com/v6/endpoint-agents/5d0764ac-7e42-4ec8-a0d4-39fc53edccba/disable.json \ -d '' \ -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

{ "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", "lastSeen": "2020-02-20 23:56:43", "status": "disabled", "deleted": false, "version": "0.191.0", "createdTime": "2017-06-29 22:05:36", "numberOfClients": 3 } ] }

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

POST /v6/endpoint-agents/transfer Transferring an agent

Triggers a process of transferring a list of agents.

Optional (Querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information

Request

The request’s body should contain a list of agents in CSV format with the following columns (comma delimited):

  • “machine_id” - agent id to be transferred
  • “from_aid” - account id where the agent needs to be transferred from
  • “to_aid” - account id where the agent needs to be transferred to

Example: machine_id,from_aid,to_aid 5d0764ac-7e42-4ec8-a0d4-39fc53edccba,111,222 5d0764ac-7e42-4ec8-a0d4-39fc53edccba,333,222

Sending the above body will transfer two agents (“5d0764ac-7e42-4ec8-a0d4-39fc53edccba”, “5d0764ac-7e42-4ec8-a0d4-39fc53edccba”) from accounts 111 and 333 into 222. The calling user needs to have ‘write’ permissions to all accounts submitted in the CSV.

The requests’ media type should be ‘text/csv’ or ‘text/plain’:

Content-Type: text/plain

Response

Returns an object confirming the number of agents to be transferred. Example:

{ "endpointAgentsTransfer": { "machineCount": 2 } }

Example

$ curl https://api.thousandeyes.com/v6/endpoint-agents/transfer.json \ -d $'machine_id,from_aid,to_aid\n5d0764ac-7e42-4ec8-a0d4-39fc53edccba,111,222\n5d0764ac-7e42-4ec8-a0d4-39fc53edccba,333,222' \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2 \ -H 'content-type: text/csv'

HTTP/1.1 200 OK Server: nginx Date: Fri, 18 Mar 2021 15:59:50 GMT Content-Type: text/plain;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 237EndpointAgentTransferServiceTest X-Organization-Rate-Limit-Reset: 1587744000 Strict-Transport-Security: max-age=31536000 X-Content-Type-Options: nosniff X-Server-Name: 1-3

Body

{ "endpointAgentsTransfer": { "machineCount": 2 } }

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