ThousandEyes API v6
ThousandEyes API v6

List all Agents

ThousandEyes API v6 has been deprecated as of May 27, 2024. We strongly recommend that you migrate to ThousandEyes API v7 to ensure continued support and access to new features. For more information, see the deprecation notice.

GET /v6/agents

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

Parameters

Querystring

  • 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={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

  • no request body

Example

curl
Copy$ curl https://api.thousandeyes.com/v6/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
interfaceIpMapping array n/a array of objects containing the interface name and IP addresses.
groups array n/a array of label objects - see Labels for more information.
location string n/a location of the agent
errorDetails array n/a if an enterprise agent or a cluster member presents at least one error, the errors will be shown as an array of entries in the errorDetails field (Enterprise Agents and Enterprise Cluster members only)
hostname string n/a fully qualified domain name of the agent (Enterprise Agents only)
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)
createdDate dateTime n/a yyyy-MM-dd hh:mm:ss, expressed in UTC. For Enterprise Clusters, this equals to the createdDate value of the initial cluster member before the conversion to cluster was performed (Enterprise Agents and Enterprise Clusters 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)
keepBrowserCache boolean n/a 1 for enabled, 0 for disabled (Enterprise Agents and Enterprise Clusters only)
utilization integer percentage shows overall utilization percentage (online Enterprise Agents and Enterprise Clusters only)
ipv6Policy string n/a IP version policy, can be FORCE_IPV4, PREFER_IPV6 or FORCE_IPV6 (Enterprise Agents and Enterprise Clusters only)
targetForTests string n/a target IP address or domain name representing test destination when agent is acting as a test target in an agent-to-agent test (Enterprise Agents only)
localResolutionPrefixes array n/a To perform rDNS lookups for public IP ranges, this field represents the public IP ranges. The range must be in CIDR notation; for example, 10.1.1.0/24. Maximum of 5 prefixes allowed (Enterprise Agents and Enterprise Agent clusters 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
memberId integer n/a unique ID of the cluster member
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 Online, Offline or Disabled
utilization integer percentage shows overall utilization percentage of a cluster member
targetForTests string n/a target IP address or domain name representing test destination when agent is acting as a test target in an agent-to-agent test

If an Enterprise Agent or a Cluster Member presents at least one error, an errorDetails field will be available, which is an array of errorDetail objects, containing the following fields:

Field Data Type Units Notes
code string n/a AGENT_VERSION_OUTDATED, APPLIANCE_VERSION_OUTDATED, BROWSERBOT_VERSION_OUTDATED, CLOCK_OFFSET, NAT_TRAVERSAL_ERROR, OS_END_OF_INSTALLATION_SUPPORT, OS_END_OF_SUPPORT, or OS_END_OF_LIFE
description string n/a detailed explanation of the error code
Code Snippet
CopyHTTP/1.1 200 OK
Server: nginx
Date: Mon, 09 May 2016 16:04:24 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: 229
X-Organization-Rate-Limit-Reset: 1493294160
Strict-Transport-Security: max-age=31536000
X-Server-Name: 1-2

Body

json
Copy{
    "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",
            "createdDate": "2015-02-05 21:23:33",
            "prefix": "38.0.0.0/8",
            "ipAddresses": [
                "10.100.50.25",
                "10.12.0.31"
            ],
            "interfaceIpMapping": [
                {
                  "interfaceName": "eth0"
                  "ipAddresses": [
                    "10.100.50.25",
                    "10.12.0.31"
                  ]
                }
            ],
            "publicIpAddresses": [
                "38.122.6.66"
            ],
            "network": "Cogent Communications (AS 174)",
            "agentType": "Enterprise",
            "lastSeen": "2015-02-05 23:23:33",
            "agentState": "Online",
            "targetForTests": "1.1.1.1",
            "localResolutionPrefixes": [
                "10.2.3.3/24"
            ]
        },
        {
            "agentId": 1975,
            "agentName": "Duke cluster",
            "location": "San Francisco Bay Area",
            "countryId": "US",
            "createdDate": "2015-02-05 21:23:33",
            "enabled": 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",
                  "memberId": 1235,
                  "targetForTests": "2.2.2.2"
                },
            [...]
            ],
            "agentType": "Enterprise Cluster",
            "utilization": 1,
            "ipv6Policy": "FORCE_IPV4"
        }
    ]
}

For error responses, see the response status codes documentation.

Next