Agents & Monitors

`GET /v5/agents` Agent List

Returns a list of all agents available to your account in ThousandEyes, including both Enterprise and Cloud agents.

Optional Parameters

agentTypes=CLOUD|ENTERPRISE|ENTERPRISE_CLUSTER optional, specifies the type of agents requested. Accepts either a single allowed value or a comma-separated list of allowed values
format=json|xml optional, specifies the format of output requested. See Output Formats for more information
aid={accountId} optional and requires the user to be assigned to the target account, specifies the account context of the request, obtained from the /accounts endpoint. Specifying this parameter without the user to be assigned to the target account will result in an error response. See Account Context for more information

Request

no request body

Example

$curl https://api.thousandeyes.com/v5/agents.json \ -u {email}:{authToken}

Response

Sends back an array of agents, specifying agentId, which can be used by other areas of the API. The agent’s public IP addresses will be shown, along with last. If an agent is an Enterprise agent, the agent’s public and private IP addresses will be shown, as well as the public network in which the agent is located.

Field	Data Type	Units	Notes
agentId	integer	n/a	unique ID of agent
agentName	string	n/a	display name of the agent
agentType	string	n/a	Cloud, Enterprise or Enterprise Cluster, shows the type of agent
countryId	string	n/a	ISO-3166-1 alpha-2 country code of the agent
clusterMembers	array	n/a	if an enterprise agent is clustered, detailed information about each cluster member will be shown as array entries in the clusterMembers field. This field is not shown for Enterprise Agents in standalone mode, or for Cloud Agents.
ipAddresses	array	n/a	array of ipAddress entries
groups	array	n/a	array of label objects - see Labels for more information.
location	string	n/a	location of the agent
prefix	string	n/a	Network prefix, expressed in CIDR format (Enterprise Agents only)
enabled	boolean	n/a	1 for enabled, 0 for disabled (Enterprise Agents only)
network	string	n/a	name of the autonomous system in which the Agent is found (Enterprise Agents only)
lastSeen	dateTime	n/a	yyyy-MM-dd hh:mm:ss, expressed in UTC (Enterprise Agents only)
agentState	string	n/a	`Online`, `Offline` or `Disabled` (standalone Enterprise Agents only)
verifySslCertificates	boolean	n/a	1 for enabled, 0 for disabled (Enterprise Agents only)
keepBrowserCache	boolean	n/a	1 for enabled, 0 for disabled (Enterprise Agents only)
utilization	integer	percentage	shows overall utilization percentage (online Enterprise Agents only)

if the AgentType is Enterprise Cluster, a clusterMembers field will be available, which is an array of clusterMember objects, containing the following fields:

Field	Data Type	Units	Notes
name	string	n/a	name of the cluster member
ipAddresses	array	n/a	array of ipAddress entries
publicIpAddresses	array	n/a	array of ipAddress entries
prefix	string	n/a	Network prefix, expressed in CIDR format (Enterprise Agents only)
network	string	n/a	name of the autonomous system in which the Agent is found (Enterprise Agents only)
lastSeen	dateTime	n/a	yyyy-MM-dd hh:mm:ss, expressed in UTC (Enterprise Agents only)
agentState	string	n/a	either Online or Offline
utilization	integer	percentage	shows overall utilization percentage

HTTP/1.1 200 OK Date: Thu, 07 Nov 2013 07:32:48 GMT Server: Apache/2.2.22 (Ubuntu) Transfer-Encoding: chunked Content-Type: application/json

Body

{ "agents": [ { "agentId": 6, "agentName": "Fremont, CA (v6)", "agentType": "Cloud", "countryId": "US", "ipAddresses": [ "2600:3c01::f03c:91ff:feae:4f96" ], "location": "San Francisco Area" }, { "agentId": 11, "agentName": "London, UK", "agentType": "Cloud", "countryId": "GB", "ipAddresses": [ "176.58.99.46", "178.79.138.106" ], "location": "City of London, United Kingdom" }, { "agentId": 29, "agentName": "Sample Enterprise Agent", "location": "United States", "countryId": "US", "prefix": "38.0.0.0/8", "ipAddresses": [ "10.100.50.25" ], "publicIpAddresses": [ "38.122.6.66" ], "network": "Cogent Communications (AS 174)", "agentType": "Enterprise", "lastSeen": "2015-02-05 23:23:33", "agentState": "Online" }, { "agentId": 1975, "agentName": "Duke cluster", "location": "San Francisco Bay Area", "countryId": "US", "enabled": 1, "verifySslCertificates": 1, "keepBrowserCache": 0, "clusterMembers": [ { "name": "duke_agent3.thousandeyes.net", "ipAddresses": [ "172.17.0.2" ], "publicIpAddresses": [ "38.122.6.66" ], "prefix": "38.0.0.0/8", "utilization": 1, "network": "Cogent Communications (AS 174)", "lastSeen": "2015-07-15 17:16:11", "agentState": "Online" }, [...] ], "agentType": "Enterprise Cluster" } ] }

For error responses, see the response status codes documentation.

`GET /v5/agents/{agentId}` Agent Details

Returns details for an agent, including assigned tests. Enterprise agents show utilization data and assigned accounts.

Optional Parameters

format=json|xml optional, specifies the format of output requested. See Output Formats for more information
aid={accountId} optional and requires the user to be assigned to the target account, specifies the account context of the request, obtained from the /accounts endpoint. Specifying this parameter without the user to be assigned to the target account will result in an error response. See Account Context for more information

Request

no request body

Example

$curl https://api.thousandeyes.com/v5/agents/966.json \ -u {email}:{authToken}

Response

Sends back agent details for an agent. For Enterprise Agents, additional details, including a list of accounts to which the agent is assigned, and utilization details will be shown. Metadata is shown below:

Field	Data Type	Units	Notes
agentId	integer	n/a	unique ID of agent
agentName	string	n/a	display name of the agent
location	string	n/a	location of the agent
countryId	string	n/a	ISO-3166-1 alpha-2 country code of the agent
prefix	string	n/a	Network prefix, expressed in CIDR format (Enterprise Agents only)
utilization	integer	percentage	shows overall utilization percentage
ipAddresses	array	n/a	array of ipAddress entries
groups	array	n/a	array of label objects - see Labels for more information.
enabled	boolean	n/a	1 for enabled, 0 for disabled
accounts	array	n/a	list of accounts to which the agent is assigned, showing aid and accountName fields
tests	array	n/a	list of tests assigned to the agent, expressed in the same format as `/tests` endpoint
network	string	n/a	name of the autonomous system in which the Agent is found
agentType	string	n/a	either Cloud, Enterprise, or Enterprise Cluster, shows the type of agent
lastSeen	dateTime	n/a	yyyy-MM-dd hh:mm:ss, expressed in UTC (Enterprise Agents only)
agentState	string	n/a	`Online`, `Offline` or `Disabled` (standalone Enterprise Agents only)

HTTP/1.1 200 OK Date: Thu, 07 Nov 2013 07:32:48 GMT Server: Apache/2.2.22 (Ubuntu) Transfer-Encoding: chunked Content-Type: application/json

Body

{ "agents": [ { "agentId": 966, "agentName": "ubuntu1404-x64", "location": "San Francisco Bay Area", "countryId": "US", "prefix": "50.128.0.0/9", "utilization": 1, "ipAddresses": [ "192.168.1.223" ], "publicIpAddresses": [ "50.184.189.59" ], "enabled": 1, "accounts": [ { "aid": 315, "accountName": "Documentation" }, { "aid": 362, "accountName": "Enterprise Agents Dashboard" } ], "tests": [ { "createdDate": "2015-02-03 21:55:13", "modifiedDate": "2015-05-05 00:21:10", "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "modifiedBy": "API Sandbox User (noreply@thousandeyes.com)", "enabled": 1, "savedEvent": 0, "testId": 12065, "testName": "My Google DNS test", "type": "dns-server", "interval": 300, "domain": "google.com A", "networkMeasurements": 1, "mtuMeasurements": 1, "bandwidthMeasurements": 0, "bgpMeasurements": 1, "alertsEnabled": 0, "liveShare": 0, "recursiveQueries": 0, "dnsServers": [ { "serverId": 130, "serverName": "ns2.google.com." } ], "apiLinks": [...] }, ... ], "network": "Comcast Cable Communications, Inc. (AS 7922)", "agentType": "Enterprise", "lastSeen": "2015-05-10 18:41:00", "agentState": "Online" } ] }

For error responses, see the response status codes documentation.

`POST /v5/agents/{agentId}/update` Updating an Agent

Updates Enterprise Agent details. Users can update the agent display name, as well as change test and account assignments.

This endpoint can only be used for Enterprise Agents, and only for users in a role that permits modification of Enterprise Agents.

Important notes related to agent modification on tests:

if an agent is removed from a test, the modification date for tests using that agent at the time it was removed will be changed.
If an agent is removed from an entire account, then all tests using this agent in the removed account will be updated to reflect the removed agent.
If a removed agent is the final remaining agent on a test, then the test will be disabled when the agent is removed.

Optional Parameters

format=json|xml optional, specifies the format of output requested. See Output Formats for more information
aid={accountId} optional and requires the user to be assigned to the target account, specifies the account context of the request, obtained from the /accounts endpoint. Specifying this parameter without the user to be assigned to the target account will result in an error response. See Account Context for more information

Request

{agentId} corresponds the unique ID of an enterprise agent, obtained from the /agents endpoint

Post Data

When POSTing data to the /agents/{agentId}/update endpoint, users can update the following fields:

agentName string representation of an agent. No two agents can have the same display name.
accounts an array of account objects containing only an aid value, in the format { aid: integer }. See /accounts to pull a list of account IDs
tests an array of test objects containing only a testId value in the format { testId: integer }. See /tests to pull a list of tests available in the current account context.

Example

$curl https://api.thousandeyes.com/v5/agents/966/update \ -d '{ "agentName": "my updated agent name", \ "accounts": [\ {"aid": 315}, {"aid": 362} ], "tests": [\ {"testId": 12065} {"testId": 817}, }' \ -H "Content-Type: application/json" \ -u {email}:{authToken}

Response

If an agent is successfully edited, an HTTP/200 OK response will be returned, and the agent’s assigned accounts / tests will change; the newly updated agent data will be returned. See the example below:

Field	Data Type	Units	Notes
agentId	integer	n/a	unique ID of agent
agentName	string	n/a	display name of the agent
location	string	n/a	location of the agent
countryId	string	n/a	ISO-3166-1 alpha-2 country code of the agent
prefix	string	n/a	Network prefix, expressed in CIDR format
utilization	float	percentage	utilization of the agent, expressed in decimal format, where 0 = 0% and 1 = 100% utilization
ipAddresses	array	n/a	array of ipAddress entries
groups	array	n/a	array of label objects - see Labels for more information.
enabled	boolean	n/a	1 for enabled, 0 for disabled
accounts	array	n/a	list of accounts to which the agent is assigned, expressed in the same format as `/accounts` endpoint
tests	array	n/a	list of tests assigned to the agent, expressed in the same format as `/tests` endpoint
network	string	n/a	name of the autonomous system in which the Agent is found
agentType	string	n/a	either Cloud or Enterprise, shows the type of agent
lastSeen	dateTime	n/a	yyyy-MM-dd hh:mm:ss, expressed in UTC
agentState	string	n/a	either Online or Offline

HTTP/1.1 200 OK Date: Thu, 14 May 2015 23:18:04 GMT Server: Apache Vary: Accept-Encoding Strict-Transport-Security: max-age=31536000 X-Frame-Options: sameorigin Transfer-Encoding: chunked Content-Type: text/xml

Body

{ "agents": [ { "agentId": 966, "agentName": "ubuntu1404-x64", "location": "San Francisco Bay Area", "countryId": "US", "prefix": "50.128.0.0/9", "utilization": 1, "ipAddresses": [ "192.168.1.223" ], "publicIpAddresses": [ "50.184.189.59" ], "enabled": 1, "accounts": [ { "aid": 315, "accountName": "Documentation" }, { "aid": 362, "accountName": "Enterprise Agents Dashboard" } ], "tests": [ { "createdDate": "2015-02-03 21:55:13", "modifiedDate": "2015-05-14 23:18:03", "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "modifiedBy": "API Sandbox User (noreply@thousandeyes.com)", "enabled": 1, "savedEvent": 0, "testId": 12065, "testName": "My Google DNS test", "type": "dns-server", "interval": 300, "domain": "google.com A", "networkMeasurements": 1, "mtuMeasurements": 1, "bandwidthMeasurements": 0, "bgpMeasurements": 1, "alertsEnabled": 0, "liveShare": 0, "recursiveQueries": 0, "dnsServers": [ { "serverId": 130, "serverName": "ns2.google.com." } ], "apiLinks": [...] }, { "enabled": 1, "testId": 817, "savedEvent": 0, "liveShare": 0, "testName": "http://www.thousandeyes.com", "type": "http-server", "interval": 900, "url": "http://www.thousandeyes.com", "networkMeasurements": 1, "createdBy": "API Sandbox User (noreply@thousandeyes.com)", "modifiedBy": "API Sandbox User (noreply@thousandeyes.com)", "createdDate": "2012-06-28 19:33:12", "modifiedDate": "2015-05-14 23:18:03", "apiLinks": [...] } ], "network": "Comcast Cable Communications, Inc. (AS 7922)", "agentType": "Enterprise", "lastSeen": "2015-05-14 23:18:00", "agentState": "Online" } ] }

For error responses, see the response status codes documentation.

`POST /v5/agents/{agentId}/delete` Deleting an Agent

Deletes an Enterprise Agent from ThousandEyes. Note: this feature can only be used on Enterprise Agents.

Important notes related to agent removal:

if an agent is deleted, the modification date for tests using that agent at the time it was deleted will be changed.
If a deleted agent is the final remaining agent on a test, then the test will be disabled when the agent is removed.

Important note: if an agent is removed, it must be re-initialized to use the same machine again in different context. Virtual Appliances can be updated using the Reset State button in the Advanced tab of the agent management interface. Users running packaged versions of Linux will need to remove /var/lib/te-agent/\*.sqlite in order to reinitialize an agent.

Optional Parameters

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

Request

{agentId} corresponds the unique ID of an enterprise agent, obtained from the /agents endpoint

Post Data

When POSTing data to the /agents/{agentId}/delete endpoint, users should specify an empty POST body.

Example

$curl https://api.thousandeyes.com/v5/agents/966/delete \ -d '' \ -H "Content-Type: application/json" \ -u {email}:{authToken}

Response

If an agent is successfully deleted, an HTTP/204 No Content response will be returned, and an empty JSON response will be in the body of the response.

HTTP/1.1 206 No Content Date: Thu, 14 May 2015 23:18:04 GMT Server: Apache Vary: Accept-Encoding Strict-Transport-Security: max-age=31536000 X-Frame-Options: sameorigin Transfer-Encoding: chunked Content-Type: text/xml

Body

For error responses, see the response status codes documentation.

`GET /v5/bgp-monitors` BGP Monitor List

Returns a list of all BGP monitors available to your account in ThousandEyes, including both public and private feeds.

Optional Parameters

format=json|xml optional, specifies the format of output requested. See Output Formats for more information
aid={accountId} optional and requires the user to be assigned to the target account, specifies the account context of the request, obtained from the /accounts 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

no request body

Example

$curl https://api.thousandeyes.com/v5/bgp-monitors.json \ -u {email}:{authToken}

Response

Sends back an array of BGP monitors, including monitorId, which can be used by other areas of the API. The example below shows both a public and private BGP monitor.

Field	Data Type	Units	Notes
monitorId	integer	n/a	unique ID of BGP monitor
ipAddress	string	n/a	IP address of the BGP monitor
network	string	n/a	name of the autonomous system in which the monitor is found
monitorType	string	n/a	either Public or Private, shows the type of monitor
monitorName	string	n/a	display name of the BGP monitor

HTTP/1.1 200 OK Date: Thu, 07 Nov 2013 07:32:48 GMT Server: Apache/2.2.22 (Ubuntu) Transfer-Encoding: chunked Content-Type: application/json

Body

{ "bgpMonitors": [ { "monitorId": 1, "ipAddress": "4.69.184.193", "network": "Level 3 Communications, Inc. (AS 3356)", "monitorType": "Public", "monitorName": "Seattle, WA" }, ..., { "monitorId": 76, "ipAddress": "166.78.186.62", "network": "AS 65314", "monitorType": "Private", "monitorName": "Private Test Peer - ThousandEyes (bgp-peering-dev, AS 65314)" } ] }

For error responses, see the response status codes documentation.

Your Privacy

Strictly Necessary Cookies

Performance Cookies

Targeting Cookies

Functional Cookies

DEVELOPER REFERENCE

Search Results

Overview

Tests

Test Data

Agents & Monitors

Alerts

Labels

User Management

Agents & Monitors

GET /v5/agents Agent List

Optional Parameters

Request

Example

Response

Header

Body

GET /v5/agents/{agentId} Agent Details

Optional Parameters

Request

Example

Response

Header

Body

POST /v5/agents/{agentId}/update Updating an Agent

Optional Parameters

Request

Post Data

Example

Response

Header

Body

POST /v5/agents/{agentId}/delete Deleting an Agent

Optional Parameters

Request

Post Data

Example

Response

Header

Body

GET /v5/bgp-monitors BGP Monitor List

Optional Parameters

Request

Example

Response

Header

Body

`GET /v5/agents` Agent List

`GET /v5/agents/{agentId}` Agent Details

`POST /v5/agents/{agentId}/update` Updating an Agent

`POST /v5/agents/{agentId}/delete` Deleting an Agent

`GET /v5/bgp-monitors` BGP Monitor List