> 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/tests/api-tests.md). # API Tests ThousandEyes API tests offer a powerful tool for monitoring and analyzing the performance of web API endpoints within your application ecosystem. These tests are designed to provide visibility into how your APIs are performing from the perspective of ThousandEyes Cloud or Enterprise Agents, which are strategically deployed vantage points around the globe or within your own infrastructure. ## Related Videos ### Configuring API Tests Watch this video for a walkthrough of configuring API tests. {% embed url="" %} The core idea behind ThousandEyes API tests is to simulate API calls to your critical endpoints and measure their availability, response times, and functional performance. You can configure these tests to make single or multiple API calls in a sequence, with the ability to pass data (like variables) from one call to the next. This is facilitated by an intuitive feature called the Step Builder, which guides you through setting up these calls without requiring deep programming knowledge—though some familiarity with JSON syntax and API specifications can be helpful for more complex setups. Key features include: * Multi-Step Testing: You can chain multiple API requests together, mimicking real-world workflows, such as authentication followed by data retrieval. * Assertions: You can set rules to validate API responses, ensuring they meet expected standards (e.g., an HTTP status code of 200 for success). * Proxy Support: Tests can be configured to use either agent-level or test-specific proxy settings, with options for static or PAC proxies, though network measurements to the proxy are off by default. * Performance Metrics: The tests capture detailed timing data per step, overall API transaction time, and completion rates, which help you spot slowdowns or failures. ### Supported Endpoints While you don’t need JavaScript expertise to get started, understanding your API’s specification (for example, endpoints and expected responses) is key. The tests support any HTTP endpoint, but advanced features like variable processing are optimized for JSON responses. After an agent is updated to version 1.242.0 or later and receives the rollout, the core Agent follows HTTP redirects, including HTTP-to-HTTPS, HTTPS-to-HTTP, and cross-origin redirects. During the staged rollout, older or not-yet-migrated Enterprise Agents still use BrowserBot, so this redirect behavior does not apply. The core Agent reapplies the configured method, headers, body, proxy, TLS verification, and client certificate on each redirect, so review redirect destinations before using sensitive request values. ### Authentication The API test type supports both client certificate authentication and disable SSL verification. * Add client certificates under **Test Settings**, in the TLS section in the **Advanced Settings** section. This setting applies to the entire API test and all steps within it. * Disabling SSL verification for each API call can be configured in the **Authentication** tab of the API Step Builder. This setting applies to a single step (API call) of the API test. ### Proxy Settings Proxy settings for your API test can use either Enterprise Agent proxy settings, or use a test-level proxy setting that overrides the agent setting. The feature works with both static and PAC proxies. Network measurements to the proxy are off by default, but can be enabled. For more information about proxy metrics, see [Collecting Proxy Metrics](https://docs.thousandeyes.com/product-documentation/tests/http-server-tests/proxy-metrics). ## Using API Tests with Enterprise Agents {% hint style="info" %} Any Enterprise Agent that has not been updated to version 1.242.0, or is not yet included in the staged rollout, requires BrowserBot to execute API tests. {% endhint %} {% hint style="warning" %} API tests do not yet support [Enterprise Agent interface selection](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/enterprise-agent-interface-selection). The core API engine receives the IPv6 policy, proxy settings, and client certificate, but it does not receive a selected network interface. {% endhint %} {% hint style="info" %} API tests run on a separate queue from general tests, which can affect the number of Enterprise Agents you need to run your testing suite. {% endhint %} ### Additional Information * To create a basic API test, see [Getting Started with API Tests](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-api-tests). * For more detail about using the Step Builder, see [Using the Step Builder](https://docs.thousandeyes.com/product-documentation/api-test/using-the-step-builder). * If you want to add API calls into a transaction test, see [Include API Calls in a Transaction Test](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/use-cases/api-monitoring). ## Typical Use Cases In practice, you’d configure an API test via the ThousandEyes platform, selecting agents to run it from, defining the endpoints to hit, and setting how often it runs. Results are then viewable in detailed dashboards, showing transaction times, response codes, and even response bodies for troubleshooting. This makes it a go-to solution for proactive API monitoring at scale. API tests are particularly useful for IT teams, network engineers, and developers who need to monitor both their own APIs and third-party dependencies. They help correlate API performance with network conditions, exposing issues that might affect user experience. For example, you might use an API test to check the health of a payment gateway or a cloud service your app relies on. Use API Tests to: * Monitor both your own APIs and third-party dependencies * Identify and diagnose API performance degradation * Correlate API performance with network conditions ## Example API Test Results Here is the API view for a test monitoring the MBTA API: ![API View for an API Test](https://1112912342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M4QARF6s57qxMrOHDTZ%2Fuploads%2Fgit-blob-5798858358011a9eb6d855159850b0ad8af9d37a%2Fapi-test-output.png?alt=media) ## Other Included Tests * Agent-to-server test * BGP test ## Manually Configure API Tests To configure an API test: 1. In the ThousandEyes platform, navigate to **Network & App Synthetics > Test Settings**. 2. Hover over the **Add New Test** button in the upper right corner of the screen. 3. Under the **Additional test types** section, select the card titled **API**. 4. The configuration page is divided into the following sections: Basic Settings, Network and Security Settings, API Performance, and Additional Settings. 5. Click **Next** to configure API steps using the Step Builder. For more information about the Step Builder for API tests, see: [API Tests: Using the Step Builder](https://docs.thousandeyes.com/product-documentation/tests/api-tests/using-the-step-builder). ### API Test Basic Settings | Setting | Description | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **URL** | The base URL for the API being tested. Individual test steps will use this as the foundation for their specific endpoint paths. | | **How often the test runs** | The frequency at which the test runs. Options are 1, 2, 5, 10, 15, 30, or 60 minutes. Adjusted this based on the criticality of the API. | | **Where the test runs from** | Select one or more ThousandEyes Cloud or Enterprise Agents to run the test from. Any Enterprise Agent that has not been updated to version 1.242.0, or is not yet included in the staged rollout, requires BrowserBot to execute API tests. For help, see [Using the Agent Selector](https://docs.thousandeyes.com/product-documentation/tests/network-tests#using-the-agent-selector). | | **Alerts** | Enable or disable alerts for this test and assign one or more alert rules. The dropdown shows the number of selected rules out of the total available. | | **Tags** | Assign tags to this test for filtering and organization. | | **Test Name** | A descriptive name for the test. For example, "Payment Gateway API Check" or "User Authentication Endpoint". | ### API Test Network and Security Settings By default, an API test focuses on HTTP response metrics like availability and response time for a sequence of API calls. To gain deeper insight and correlate the performance of the configured network target with the underlying network path, you can enable network measurements. | Setting | Description | | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Perform Network Measurements** |

When this toggle is enabled, the Agent runs one concurrent agent-to-server network measurement for the configured network target during each test round. It captures packet loss, latency, jitter, and the network path for that measurement. If you also select Collect BGP data, it correlates the measurement with BGP routing data. It does not create a separate network measurement for every API step.

Enabling this option helps you determine whether API failures or performance problems come from the API endpoint or the underlying network path.

| | **Define which data to collect** |

Selects the types of network data to collect for each round of the test.

| | **Protocol** | The transport layer protocol (TCP or ICMP) used for the accompanying network measurements (loss, latency, jitter). | | **Path trace mode** |

When In Session is selected, the path trace is performed within an established TCP session.

> Note: This mode is designed for environments where stateful firewalls (e.g., Palo Alto Networks, Juniper SRX) might otherwise block standard path trace packets.

| | **Probing mode** |

Defines the TCP probing method used for network measurements. This setting is available only when the Protocol is set to TCP.

| | **Transmission rate** | Controls the rate at which packets are sent for network measurements. Use this to simulate network load or validate Quality of Service (QoS) policies. | | **Number of path traces** | Sets the number of path traces requested for the test’s network measurement. Increasing the number helps discover and visualize multiple or asymmetric network paths. | | **Proxy settings** |

Defines how the test connects to target domains through a proxy server for the entire API test.

| | **Perform network measurements to the proxy** | When enabled, the network measurement target changes from the configured URL to the selected proxy server. The measurement runs once during each test round, so you can isolate proxy-path performance without creating a measurement for every API step. | | **Add client certificate** | Enables mutual TLS (mTLS) authentication by providing a client-side certificate. The certificate will be presented to any server in the API test that requests it. For more information about adding a client certificate, see [Adding a Client Certificate to HTTP Server Test Settings](https://docs.thousandeyes.com/product-documentation/tests/http-server-tests). | ### API Test API Performance Settings | Setting | Description | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **API Transaction Timeout** | Defines the maximum total time (default 5s) allowed for the entire sequence of API calls (steps) to complete. If the total duration exceeds this value, the test fails. | | **API Target Time for View** | Sets a visual performance benchmark (default 3s) for the total transaction time. In the dashboard, results exceeding this target are color-coded, helping you quickly identify tests that are not meeting performance expectations. This setting does not trigger alerts. | | **Enable distributed tracing** | When enabled, the Agent adds an HTTP trace-context header to each API request in the test. This lets backend services track the request sequence across multiple services. | ### API Test Additional Settings | Setting | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Description** | An optional, user-defined description for the test. Use this field to add context, change history, or other notes for fellow users. | | **Alert suppression window** | Temporarily disables all alerts for this test for a defined period. Use this feature for planned maintenance windows to prevent false-positive alerts. |