# 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 [Changelog](https://docs.thousandeyes.com/whats-new/changelog) for updates to our Cloud Agents. Consider [subscribing](https://docs.thousandeyes.com/product-documentation/getting-started/notification-of-upgrades-maintenance-and-outages) to the Changelog forum for automatic notification of new postings.

{% hint style="info" %}
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](https://status.thousandeyes.com/).

For more information, see [Obtaining a List of ThousandEyes Agent IP Addresses](https://docs.thousandeyes.com/product-documentation/api/obtaining-a-list-of-thousandeyes-agent-ip-addresses).
{% endhint %}

{% hint style="info" %}
To avoid being affected if the IP addresses change, you can filter traffic based on the `user agent string` in the request headers instead.
{% endhint %}

## 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](https://en.wikipedia.org/wiki/Wget) or [cURL](https://en.wikipedia.org/wiki/CURL), with a standard browser, or through a RESTful API client, such as [Postman](https://www.getpostman.com/).

The query is a simple HTTP GET request to

```
https://api.thousandeyes.com/v7/agents
```

for [XML](https://en.wikipedia.org/wiki/XML)-formatted output, or

```
https://api.thousandeyes.com/v7/agents
```

for [JSON](https://en.wikipedia.org/wiki/JSON)-formatted output.

To authenticate the request, you need an OAuth Bearer Token. To get your token, go to **Manage > Account Settings > Users and Roles**, then select the **Profile** tab. Your OAuth Bearer Token is listed in the **User API Tokens** section:

![](/files/-M5xtRAUFmpE0FxzMLPv)

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:

![](/files/-M5xtRAWmxo5Eh1GBwfV)

If you need to query a non-default Account Group you have access to, you will need to use the [Account Group context](https://developer.cisco.com/docs/thousandeyes/v7/#!account-group-context) parameter.

## Example

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

```
curl "https://api.thousandeyes.com/v7/agents" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

A section of the resulting output in XML format:

![](/files/-M5xtRAYnTGwgeyBLIZm)

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](http://www.freeformatter.com/xml-formatter.html) (or [format the JSON](https://jsonformatter.curiousconcept.com/) below) to present the output in a similar fashion as shown in the image above.

Alternatively, a similar curl command can be used to receive a JSON-formatted response:

```
curl "https://api.thousandeyes.com/v7/agents" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -H "Accept: application/json"
```

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

![](/files/-M5xtRAa1WL5KL38-59e)

For more information about querying the ThousandEyes API, see the [ThousandEyes API documentation](https://developer.cisco.com/docs/thousandeyes/v7/).

**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](https://docs.thousandeyes.com/product-documentation/global-vantage-points/obtaining-a-list-of-thousandeyes-agent-ip-addresses-with-te-iplist).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.thousandeyes.com/product-documentation/api/obtaining-a-list-of-thousandeyes-agent-ip-addresses.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.