Obtaining a List of ThousandEyes Agent IP Addresses
Customers may need the IP addresses of ThousandEyes Agents in order to construct firewall rules or similar filters. The ThousandEyes application program interface (API) provides the IP addresses of both Cloud Agents assigned to your organization and Enterprise Agents assigned to your Account Group.
Note that for Cloud Agents, the IP address assignment is relatively constant but subject to change without notice. ThousandEyes periodically adds Cloud Agent locations, adds instances of Agents to increase capacity in a given geographic location (all Cloud Agent locations have multiple instances of actual hosts running the Agent software), changes providers in a given geographic location due to reliability issues, or makes changes for other reasons. We recommend that you check the listing periodically for changes, and review our Release Notes for updates to our Cloud Agents. Consider subscribing to the Release Notes forum for automatic notification of new postings.
While the list of all ThousandEyes IP addresses can be found via our API, there is no guarantee that a single consistent IP address will be assigned to any ThousandEyes agent. This is because most virtual agents have multiple underlying agents that use different IPs, and tests can be moved between those agents for a number of performance reasons.
When a virtual agent is going to switch to a completely new set of IPs (such as during a provider migration), customers are informed one week in advance via a maintenance announcement on ThousandEyes Status.
To avoid being affected if the IP addresses change, you can filter traffic based on the
user agent stringin the request headers instead.
The query is a simple HTTP GET request to
In addition, you will need to supply your ThousandEyes username (email address) and API token as the HTTP Basic Authentication username and password, respectively. If you issue one of the above requests in a browser, your browser should prompt you for your ThousandEyes username and API token. Alternatively, you may include the username and API token in the URL, in the following form:
For users with access to multiple Account Groups, be sure to use to the correct Account Group context to obtain the correct set of results from the API. The current context is displayed in the menu bar to the right of the User icon. For example, the current context in the example below is the "Support" Account Group:
Here is an example curl command for querying the /agents API endpoint:
A section of the resulting output in XML format:
The image above shows a portion of the response listing some of the Singapore Cloud Agent IP addresses. The "agentType" parameter identifies them as type "Cloud". Enterprise Agents will be identified as type "Enterprise". If your output's format is missing the whitespace and/or line termination, you can use any publicly available web-based tool to format the XML (or format the JSON below) to present the output in a similar fashion as shown in the image above.
Alternatively, similar curl command can be used to receive a JSON-formatted response. The only adjustment that is needed is the addition of the .json suffix to the API endpoint URL:
The command above will generate output in JSON format, which is (arguably) easier to read for humans:
NOTE: ThousandEyes does not provide and does not recommend using CIDR blocks as a shortcut to enumerating each of the Agent IP addresses. Most user interfaces of filtering devices provide the capacity to create groups of objects such as a "ThousandEyes Cloud Agents" group. Once created, the effort required to maintain such a list is minimal. In contrast, attempting to use whois information or assuming a CIDR mask that fits the existing IP addresses of an Agent is liable to be error-prone as Agent IP addresses are updated, and is less secure.
In addition to querying ThousandEyes API directly, we provide a command-line interface (CLI) utility called te-iplist. This utility abstracts away raw API queries and provides a simpler method for exporting agent IP addresses in various formats. It is available for Linux, MacOS and Windows OS. For more information, here are the instructions on how to use te-iplist.