> For the complete documentation index, see [llms.txt](https://docs.thousandeyes.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-the-thousandeyes-api.md). # Getting Started with the ThousandEyes API ## Introduction The ThousandEyes API enables programmatic access to ThousandEyes features and data, allowing you to integrate ThousandEyes with third-party systems and to automate tasks such as creating and modifying tests or retrieving test data. The ThousandEyes API is a RESTful API that uses standard HTTP methods and response codes. In this guide, you learn the basics of using the ThousandEyes API, including authentication and permission requirements, the different available endpoints, and example use cases with implementations. More information on applicable terms and the complete developer reference is available at [ThousandEyes API v7 - Cisco DevNet.](https://developer.cisco.com/docs/thousandeyes/v7/) ### Prerequisites To get the most out of this guide, you need the following prerequisites: * A basic understanding of REST APIs and HTTP. * Some familiarity with programming concepts and a programming language of your choice; or an HTTP client such as curl or Postman. Because the ThousandEyes API enables you to interact with the entire ThousandEyes platform, we recommend that you complete the [Getting Started guides](https://docs.thousandeyes.com/product-documentation/getting-started) for the features and data you want to consume via the API. * Account Administration and Management * [Getting Started with Account Setup](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-account-setup) * Cloud and Enterprise Agents * [Getting Started with Enterprise Agents](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-enterprise-agents) * [Getting Started with Cloud and Enterprise Agent Tests](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-tests) * Endpoint Agents * [Introduction to Endpoint Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents) * Alerts * [Getting Started with Alerts](https://docs.thousandeyes.com/product-documentation/alerts) * Dashboards * [Getting Started with Dashboards](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-dashboards) ### API Credentials Before you authenticate requests, choose an API credential: * [API Key](https://docs.thousandeyes.com/product-documentation/user-management/authorization/api-keys): Use API Keys for production integrations and automation. API Keys use the permissions assigned when the key is created. * [OAuth bearer token](https://docs.thousandeyes.com/product-documentation/user-management/authorization/rb-access-control#user-api-tokens): Use OAuth bearer tokens for testing, exploration, and ad hoc requests. OAuth bearer tokens use the permissions assigned to the user. The credential must have the permissions required for the endpoint that you call. To authenticate requests with an OAuth bearer token, your user role must have the *API access* permission. The three built-in roles (Organization Admin, Account Admin, and Regular User) include this permission by default. To create or manage API Keys, your user role must have the *Manage own API Keys* permission or the *Manage all API Keys* permission. For more information, see [API Keys](https://docs.thousandeyes.com/product-documentation/user-management/authorization/api-keys). ### Authentication ThousandEyes API credentials use the HTTP bearer authentication scheme. Include your API credential in the `Authorization` header of your requests. The value of the header must be `Bearer `. {% hint style="info" %} The full value of an API Key or OAuth bearer token is shown only when ThousandEyes generates and displays a new value. Store your credential securely, such as in a password manager or secrets manager. You cannot view the same credential value again in the ThousandEyes platform. If you lose or forget a credential, replace it and update every integration that uses the previous value. {% endhint %} The following example shows bearer authentication with curl: ``` curl https://api.thousandeyes.com/v7/agents \ --header "Authorization: Bearer $BEARER_TOKEN" ``` To authenticate in Postman with an API credential: 1. In the **Authorization** tab, select the **Bearer token** type. 2. In the **Token** field, type your API credential. ![Postman screen for entering bearer token](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-1f8956525c8ebc358409a40166d279b75643f28f%2FPostman-Bearerauth.png?alt=media\&token=842ddeed-47ad-462f-8ade-cb01a2bca0b6) ## Making Requests To use the ThousandEyes API, send an HTTP request to an endpoint at api.thousandeyes.com. The URL for your request should be of the form `https://api.thousandeyes.com/[version]/[endpoint]`. The current production version of the API is v7. Before exploring the capabilities of the various endpoints, read the following sections on specifying an account group. ### Specifying an Account Group API requests are handled within the context of an account group. If your credential can access only one account group, you do not need to specify an account group in your requests. If your credential can access multiple account groups, the default account group context depends on the credential type. For an OAuth bearer token, ThousandEyes uses your [login account group](https://docs.thousandeyes.com/product-documentation/user-management/authorization/rb-access-control#login-account-group). For an API Key, ThousandEyes uses the default account group selected when the key was created. To access a different account group, specify the account group ID in your API request by using the `aid` URL query parameter. In the two example curl commands below, the first returns a list of all tests in the login account group, and the second returns a list of all tests in the account group with ID 123456. Note: For the sake of brevity, authentication is omitted from this example. ``` curl https://api.thousandeyes.com/v7/tests curl https://api.thousandeyes.com/v7/tests?aid=123456 ``` ## API Endpoints and Use Cases ### Administrative and Account Management One common use case of the ThousandEyes API is for managing your account groups and users. For example, you can easily create users in bulk, reassign users to different account groups, or programmatically create a new role and assign it to multiple users. | Action/Method | Account Groups | Users | Roles | | ----------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | Create (`POST`) | [/v7/account-groups](https://developer.cisco.com/docs/thousandeyes/v7/#!create-account-group) | [/v7/users](https://developer.cisco.com/docs/thousandeyes/v7/#!create-user) | [/v7/roles](https://developer.cisco.com/docs/thousandeyes/v7/#!create-role) | | List (`GET`) | [/v7/account-groups](https://developer.cisco.com/docs/thousandeyes/v7/#!list-account-groups) | [/v7/users](https://developer.cisco.com/docs/thousandeyes/v7/#!list-users) | [/v7/roles](https://developer.cisco.com/docs/thousandeyes/v7/#!list-roles) | | Details (`GET`) | [/v7/account-groups/{id}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-account-group) | [/v7/users/{id}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-user) | [/v7/roles/{id}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-role) | | Update (`PUT`) | [/v7/account-groups/{id}](https://developer.cisco.com/docs/thousandeyes/v7/#!update-account-group) | [/v7/users/{id}](https://developer.cisco.com/docs/thousandeyes/v7/#!update-user) | [/v7/roles/{id}](https://developer.cisco.com/docs/thousandeyes/v7/#!update-role) | | Delete (`DELETE`) | [/v7/account-groups/{id}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-account-group) | [/v7/users/{id}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-user) | [/v7/roles/{id}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-role) | ### Cloud and Enterprise Agents You can use the ThousandEyes API for managing your Cloud and Enterprise Agents and tests, and for retrieving test result data. #### Configuration and Management | Action/Method | Tests | Agents | | ----------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | Create (`POST`) | [/v7/tests/{testType}](https://developer.cisco.com/docs/thousandeyes/v7/#!create-agent-to-server-test) | | | List (`GET`) | [/v7/tests](https://developer.cisco.com/docs/thousandeyes/v7/#!list-configured-tests) | [/v7/agents](https://developer.cisco.com/docs/thousandeyes/v7/#!list-cloud-and-enterprise-agents) | | Details (`GET`) | [/v7/tests/{testType}/{testId}](https://developer.cisco.com/docs/thousandeyes/v7/#!get-agent-to-server-test) | [/v7/agents/{agentId}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-cloud-and-enterprise-agent) | | Update (`PUT`) | [/v7/tests/{testType}/{testId}](https://developer.cisco.com/docs/thousandeyes/v7/#!update-agent-to-server-test) | [/v7/agents/{agentId}](https://developer.cisco.com/docs/thousandeyes/v7/#!update-enterprise-agent) | | Delete (`DELETE`) | [/v7/tests/{testType}/{testId}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-agent-to-server-test) | [/v7/agents/{agentId}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-enterprise-agent) | #### Test Data As described in [Getting Started with Tests](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-tests), most Cloud and Enterprise Agent tests are composed of multiple layers. Using the API, you can retrieve test data from the individual layers that comprise the test. The complete list of endpoints for Cloud and Enterprise Agent test data is available in the [**Test Data**](https://developer.cisco.com/docs/thousandeyes/v7/#!test-results-api-overview) page of the developer reference. Using these endpoints, you can retrieve metrics from the following test layers: * **Routing - BGP**: BGP metrics, BGP routes * **Network**: End-to-end (“overview”), path visualization, and detailed path trace * **Web**: FTP server, HTTP server, page load and waterfall, transaction and waterfall * **DNS**: DNS server, DNS trace, DNSSEC * **Voice**: SIP server, RTP stream ### Endpoint Agents Use the Endpoint Agent APIs to manage your fleet of agents and configure your scheduled tests and dynamic tests. #### Configuration and Management | Action/Method | Endpoint Agents | Scheduled Tests | Dynamic Tests | | ----------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | Create (`POST`) | | [/v7/endpoint/tests/scheduled-tests/{testType}](https://developer.cisco.com/docs/thousandeyes/v7/#!creates-agent-to-server-endpoint-scheduled-test) | [/v7/endpoint/tests/dynamic-tests/agent-to-server](https://developer.cisco.com/docs/thousandeyes/v7/#!create-endpoint-dynamic-test) | | List (`GET`) | [/v7/endpoint/agents](https://developer.cisco.com/docs/thousandeyes/v7/#!list-endpoint-agents) | [/v7/endpoint/tests/scheduled-tests](https://developer.cisco.com/docs/thousandeyes/v7/#!list-endpoint-scheduled-tests-list-endpoint-scheduled-tests) | [/v7/endpoint/tests/dynamic-tests/agent-to-server](https://developer.cisco.com/docs/thousandeyes/v7/#!list-endpoint-dynamic-tests) | | Details (`GET`) | [/v7/endpoint/agents/{agentId}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-endpoint-agent) | [/v7/endpoint/tests/scheduled-tests/{testType}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-agent-to-server-endpoint-scheduled-test) | [/v7/endpoint/tests/dynamic-tests/agent-to-sever/{testId}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-endpoint-dynamic-test) | | Update (`PATCH`) | [/v7/endpoint/agents/{agentId}](https://developer.cisco.com/docs/thousandeyes/v7/#!update-endpoint-agent) | [/v7/endpoint/tests/scheduled-tests/{testType}/{testId}](https://developer.cisco.com/docs/thousandeyes/v7/#!update-agent-to-server-endpoint-scheduled-test) | [/v7/endpoint/tests/dynamic-tests/agent-to-sever/{testId}](https://developer.cisco.com/docs/thousandeyes/v7/#!update-agent-to-server-dynamic-test) | | Delete (`DELETE`) | [/v7/endpoint/agents/{agentId}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-endpoint-agent) | [/v7/endpoint/tests/scheduled-tests/{testType}/{testId}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-agent-to-server-scheduled-test) | [/v7/endpoint/tests/dynamic-tests/agent-to-sever/{testId}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-agent-to-server-dynamic-test) | #### Test, Network, and Session Data As described in the [Endpoint Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents) article, ThousandEyes Endpoint Agents collect measurements in multiple ways: scheduled synthetic tests, dynamic tests, real user tests sessions, and local network topology. You can use the ThousandEyes API to retrieve Endpoint Agent data from each of these areas; see the [**Endpoint Test Results**](https://developer.cisco.com/docs/thousandeyes/v7/#!endpoint-test-results-api-overview) page in the developer reference. * **Scheduled Test Data**: HTTP server, network end-to-end, path visualization, and detailed path trace * **Dynamic Test Data**: Network end-to-end, path visualization, and detailed path trace * **Real User Test Data**: Real user test list and details, visited page list and details, network sessions list * **Local Network Data**: Network topology list and details ### Alerts You can use the API to retrieve the list of all active alerts and the details for individual alerts. You can also manage your alert rules and alert suppression windows. | Action/Method | Alerts | Alert Rules | Alert Suppression Windows | | --------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | Create (`POST`) | | [/v7/alerts/rules](https://developer.cisco.com/docs/thousandeyes/v7/#!create-alert-rule) | [/v7/alert-suppression-windows](https://developer.cisco.com/docs/thousandeyes/v7/#!create-alert-suppression-window) | | List (`GET`) | [/v7/alerts](https://developer.cisco.com/docs/thousandeyes/list-alerts/) | [/v7/alerts/rules](https://developer.cisco.com/docs/thousandeyes/v7/#!list-alert-rules) | [/v7/alert-suppression-windows](https://developer.cisco.com/docs/thousandeyes/v7/#!list-alert-suppression-windows) | | Details (`GET`) | [/v7/alerts/{alertId}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-alert-details) | [/v7/alerts/rules/{ruleId}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-alert-rule) | [/v7/alert-suppression-windows/{windowId}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-alert-suppression-window) | | Update (`PUT`) | | [/v7/alerts/rules/{ruleId}](https://developer.cisco.com/docs/thousandeyes/v7/#!update-alert-rule) | [/v7/alert-suppression-windows/{windowId}](https://developer.cisco.com/docs/thousandeyes/v7/#!update-alert-suppression-window) | | Delete (`POST`) | | [/v7/alerts/rules/{ruleId}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-alert-rule) | [/v7/alert-suppression-windows/{windowId}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-alert-suppression-window) | ### Dashboards | Action/Method | Dashboard | Dashboard Snapshot | | ----------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Create (`POST`) | [/v7/dashboards](https://developer.cisco.com/docs/thousandeyes/v7/#!create-dashboard) | [/v7/dashboard-snapshots](https://developer.cisco.com/docs/thousandeyes/v7/#!create-dashboard-snapshot) | | List (`GET`) | [/v7/dashboards](https://developer.cisco.com/docs/thousandeyes/v7/#!list-dashboards) | [/v7/dashboard-snapshots](https://developer.cisco.com/docs/thousandeyes/v7/#!list-dashboard-snapshots) | | Details (`GET`) | [/v7/dashboards/{dashboardId}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-dashboard) | [/v7/dashboard-snapshots/{snapshotId}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-dashboard-snapshot) | | Update (`PUT`) | [/v7/dashboards/{dashboardId}](https://developer.cisco.com/docs/thousandeyes/v7/#!update-dashboard) | | | Delete (`DELETE`) | [/v7/dashboards/{dashboardId}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-dashboard) | [/v7/dashboard-snapshots/{snapshotId}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-dashboard-snapshot) | You can also retrieve the data for a dashboard widget using the [retrieve dashboard widget data](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-dashboard-widget-data) endpoint. ## Example Code Snippets One of the advantages of a RESTful API is its flexibility and versatility. A well-designed API allows developers to integrate it into their applications in many different ways, depending on their specific needs and requirements. This section provides a few examples of how you might use the ThousandEyes API, to give you an idea of its potential applications. The examples in this section are a small subset of the many ways you can use this API. Your use case might be different from the examples described here, but these examples help you understand the possibilities and create your own integrations. The code implementations in this section are examples and are not intended for production use. They might not follow best practices, and might not be optimized for performance or security. They show how you might interact with the ThousandEyes API in a particular context. With that in mind, let's dive into some examples of how you might use this ThousandEyes API in practice. ### Getting a List of Cloud Agent IPs for Automating Firewall Rules Cloud Agents are generally used to monitor public internet-facing web applications, but occasionally you might test a target that only allows traffic from explicitly allowed sources. In this case, add the Cloud Agents' IP addresses to your security rule access control list so test traffic can reach the target server. You can use the ThousandEyes API to retrieve the IP addresses for any Cloud Agents and add them to your allowlist. This example uses two CLI utilities, curl and [jq](https://stedolan.github.io/jq/), to request and parse the list of agents and their respective IP addresses. Additionally, this example demonstrates that you do not need programming knowledge to interact with the ThousandEyes API. First, use curl to make a request to the `/v7/agents` endpoint and write the response to a file: ```bash curl -o agents.json https://api.thousandeyes.com/v7/agents \ -H "Authorization: Bearer $BEARER_TOKEN" ``` This creates a file named **agents.json** in the current working directory where you ran the curl command. The file contains a JSON object with a key named `agents` mapped to a list of objects representing the agents, like the following excerpt: ```json { "agents": [ { "agentId": 3, "agentName": "Singapore", "agentType": "Cloud", "countryId": "SG", "targetOnly": 0, "ipAddresses": [ "64.29.136.162", "64.29.136.173", ... ] } ] } ``` Now that you have retrieved the agent data from the ThousandEyes API, you can parse or post-process it to meet your requirements. For example, you can use the jq utility to read the **agents.json** file and extract three fields: the agent ID, the agent name, and the agent’s IP addresses. ```bash jq -r '.agents[] | [.agentId, .agentName, .ipAddresses|tostring] ' agents.json ``` The output from the jq command should look something like this: ```json [ "3", "Singapore", "[\"64.29.136.162\",\"64.29.136.173\", ...]" ] ``` You can also use jq to filter the response. For example, you can include only specific agents in the output: ```bash jq -r '.agents[] | select (.agentName | IN("Singapore", "Boston, MA")) | [.agentId, .agentName, .ipAddresses|tostring] ' agents.json ``` Or, you can use jq to format the JSON as a CSV file, like so: ```bash jq -r '.agents[] | [.agentId, .agentName, .ipAddresses|tostring] | @csv ' agents.json > agents.csv ``` ### Exporting Test Data to a CSV File Retrieving test data is a common use case for the ThousandEyes API. For example, you might want to perform data analysis on test results in the tool of your choice, archive test data longer than the ThousandEyes platform data retention provides, or collect and aggregate all of your observability data in a centralized data store. The following code snippet shows how to request, parse, and output the network latency for all agents in a single test over the last one hour. This example uses the Python programming language and the open-source [`requests`](https://requests.readthedocs.io/en/latest/) package for making HTTP requests to the API server. You can use any language and HTTP client package that you prefer. ```python # Import standard modules import csv import json # Import third-party HTTP client package import requests ### Define HTTP request values TOKEN = "YOUR-API-CREDENTIAL-HERE" TEST_ID = 123456 # Make the HTTP request to the /v7/test-results/{testId}/network endpoint, including # the API credential and specifying that the response must be JSON format resp = requests.get( f"https://api.thousandeyes.com/v7/test-results/{TEST_ID}/network?window=60m", headers={"Authorization": f"Bearer {TOKEN}"}, ) resp_body = resp.json() # Parse the response JSON to store the metrics by test round so we can # later write each round as a row in the CSV file agent_names = set() data_by_round = {} metrics = resp_body["results"] for metric in metrics: if metric["roundId"] not in data_by_round: data_by_round[metric["roundId"]] = {} agent_names.add(metric["agent"]["agentName"]) data_by_round[metric["roundId"]][metric["agent"]["agentName"]] = metric["avgLatency"] # Write the data to a CSV file agent_names = list(agent_names) with open("test_data.csv", "w") as f: csv_file = csv.writer(f) csv_file.writerow(["Round ID", *agent_names]) for roundId, metrics in data_by_round.items(): csv_file.writerow([roundId, *[metrics[agent] for agent in agent_names]]) ``` ### Change the Interval of a Cloud and Enterprise Agent Test The test configuration endpoints are useful whenever you need to create or re-configure a large number of tests, or when you integrate ThousandEyes with an automation pipeline such as Continuous Integration / Continuous Delivery. This example demonstrates how to programmatically re-configure a Cloud and Enterprise Agent test using the JavaScript programming language and the open-source [`node-fetch`](https://www.npmjs.com/package/node-fetch) package for making HTTP requests. In the code snippet below, the testing interval of a given test is toggled between 10 minutes and 5 minutes. This could be useful for testing at different intervals at different times of day - for example, more frequently during business hours and less frequently during inactive times. It could also be used as the receiver of an alert rule webhook: if a given test triggers an alert, then increase the testing frequency to get more granular data. First, an API call is made to get a test’s current configuration. Then the configuration is modified to change the test interval. Finally, another API call is made to update the test to use the new configuration: ```javascript import fetch from 'node-fetch'; toggleTestInterval(); async function toggleTestInterval() { // Define HTTP request values const token = "YOUR-API-CREDENTIAL-HERE" const test_id = 123456; // Get the current test configuration let resp = await fetch(`https://api.thousandeyes.com/v7/tests/web-transactions/${test_id}`, { headers: {'Authorization': `Bearer ${token}`} }); let body = await resp.json(); let test_config = body; // Toggle the interval between 600 seconds and 300 seconds test_config['interval'] = test_config['interval'] == 600 ? 300 : 600; // Delete read-only fields from the test configuration before making the call to update delete test_config.testId; delete test_config.savedEvent; // Call the API to update the test configuration using the new interval resp = await fetch(`https://api.thousandeyes.com/v7/tests/${test_config['type']}/${test_id}`, { headers: { 'Authorization': `Bearer ${bearerToken}`, 'Content-Type': 'application/json'}, method: 'PUT', body: JSON.stringify(test_config) }); }; ``` ## Next Steps Review the [ThousandEyes API v7 Reference](https://developer.cisco.com/docs/thousandeyes/v7/#!account-group-context) for more details on API endpoints and request/response characteristics, such as: * Time spans * Pagination * Rate limiting Watch the [Short & Sweet into ThousandEyes API Suite](https://www.ciscolive.com/on-demand/on-demand-library.html?search=thousandeyes#/session/1675722384027001tnDb) on-demand breakout session from Cisco Live Amsterdam 2023. If you use Postman as your HTTP client, you should [import the ThousandEyes Postman Collection](https://www.postman.com/cisco/cisco-devnet-s-public-workspace/collection/v2ogbsf/cisco-thousandeyes-api-v7?ctx=documentation).