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.

For more information, see Obtaining a List of ThousandEyes Agent IP Addresses.

To avoid being affected if the IP addresses change, you can filter traffic based on the user agent string in the request headers instead.

Querying the API

To list the IP addresses of all Agents available to your Account Group, query the /agents endpoint of the ThousandEyes API. The query can be sent by a command-line tool such as Wget or cURL, with a standard browser, or through a RESTful API client, such as Postman.

The query is a simple HTTP GET request to

https://api.thousandeyes.com/agents

for XML-formatted output, or

https://api.thousandeyes.com/agents.json

for JSON-formatted output.

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:

https://username:[e-mail]/agents

Your API token can be found in the User API Token section of the Profile tab of the Account Settings page:

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:

If you need to query a non-default Account Group you have access to, you will need to use the Account Group context parameter.

Example

Here is an example curl command for querying the /agents API endpoint:

curl "https://api.thousandeyes.com/agents" -u [e-mail]:g351mw5xqhvkmh1vq6zfm51c62wyzib2

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:

curl "https://api.thousandeyes.com/agents.json" -u [e-mail]:g351mw5xqhvkmh1vq6zfm51c62wyzib2

The command above will generate output in JSON format, which is (arguably) easier to read for humans:

For more information on querying the ThousandEyes API, consult the documentation available at https://developer.thousandeyes.com.

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.

Obtaining a List of ThousandEyes Agent IP Addresses with the te-iplist Tool

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.