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.
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, like API transaction time, and completion rates, which help you spot slowdowns or failures.
No Browser Dependency: Unlike some other ThousandEyes test types, API tests don’t rely on a browser, though they do require the BrowserBot component on agents for execution.
Supported Endpoints
While you don’t need JavaScript expertise to get started, understanding your API’s specification (e.g., endpoints, expected responses) is key. The tests support any HTTP endpoint, but advanced features like variable processing are optimized for JSON responses. Note that API tests don’t automatically follow HTTP redirects that switch protocols (e.g., HTTP to HTTPS), so you’d need to account for that in your setup.
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.
Using API Tests with Enterprise Agents
API tests rely on the ThousandEyes BrowserBot component. If you want to run API tests from your own Enterprise Agents, those agents need to be installed on devices that can support BrowserBot. To find out if your devices support BrowserBot, see Enterprise Agent System Requirements and Cisco Devices Support Matrix.
API tests are not supported on Cisco devices, even with BrowserBot installed.
To use API tests, you will need to transition to a different deployment type.
Because API tests use BrowserBot, you can't select specific interfaces for Enterprise Agents when configuring API tests. For more information about interface selection, see Enterprise Agent interface selection. For more information about BrowserBot, see What Is BrowserBot?.
Additional Information
To create a basic API test see, Getting Started with API Tests.
For more detail about using the Step Builder, see Using the Step Builder.
If you want to add API calls into a transaction test, see Include API Calls in a Transaction Test.
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:
Other Included Tests
Agent-to-server test
BGP test
Manually Configure API Tests
To configure an API test:
In the ThousandEyes platform, navigate to Network & Synthetics > Test Settings.
Click the + button in the upper right corner of the screen.
Under the Web & API Tests section, select the card titled API Performance.
The configuration page is divided into the following sections: Basic Settings, Network and Security Settings, API Performance, and Additional Settings.
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.
API Test Basic Settings
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. For help, see 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.
Labels
Assign agent labels to this test for filtering and organization. The dropdown shows the number of selected labels out of the available.
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 each API call with the underlying network path, you can enable network measurements.
Perform Network Measurements
When this toggle is enabled, the test will run a concurrent agent-to-server network test for each API call (step) in the test. This captures essential network-layer metrics like packet loss, latency, and jitter for every request, allowing you to visualize the network path and BGP routing data for each step of the API workflow. Enabling this option is highly recommended for comprehensive root cause analysis, as it helps you determine if API failures or performance degradation are caused by API endpoint issues or by problems on the underlying network path.
Define which data to collect
Selects the types of network data to collect for each API call in the test.
Bandwidth: Measures available network bandwidth by sending a series of packet streams ("packet trains") to the server. The test is iterative: it starts with a small stream (100 packets) and may increase in size (up to 2000 packets) until a stable throughput measurement is calculated based on packet delay analysis. > Note: This option does not increase test unit consumption but does generate additional traffic, which may impact performance on resource-constrained networks. It is recommended to keep this option disabled for tests using agents on routers or switches.
Maximum Transmission Unit (MTU): Determines the Maximum Transmission Unit (MTU) size along the network path to identify issues related to packet fragmentation.
Collect BGP data: Correlates network data with BGP routing data. Tests with IPv4 targets use IPv4 BGP monitors, and tests with IPv6 targets use IPv6 BGP monitors.
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.
Prefer SACK: (Default) Uses a single TCP connection with Selective Acknowledgement (SACK) for efficient, low-overhead measurements.
Force SYN: Sends a stream of up to 50 SYN packets from unique source ports. Use this method if SACK is not supported or is blocked in the network path.
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 (3 to 10) performed for each API call (step) in the test. Increasing the number helps discover and visualize multiple or asymmetric network paths.
IPv6 Policy
Determines how the agent resolves domain names in dual-stack (IPv4/IPv6) environments for all domains accessed during the API test.
Agent's Policy: Uses the agent's local DNS resolution policy.
IPv4 only: Forces DNS resolution to IPv4 addresses.
Prefer IPv6: Attempts to resolve to an IPv6 address first, with a fallback to IPv4.
Force IPv6: Resolves only to IPv6 addresses.
Proxy settings
Defines how the test connects to target domains through a proxy server for the entire API test.
Direct: Connects directly to the target, bypassing any proxy.
Agent's Policy: Uses the proxy configuration defined on the Enterprise Agent.
Specific Proxy Config: Uses a specific proxy server defined in the test settings.
Perform network measurements to the proxy
When enabled, network measurements (loss, latency) are performed to the proxy server instead of the final target for each API call. Use this to isolate performance issues related to the proxy itself.
TLS SSL version
Selects the specific TLS/SSL protocol version for all HTTPS connections made during the API test. Auto (Default) negotiates the highest version supported.
Verify SSL Certificate
When enabled, the agent validates the SSL/TLS certificate for every HTTPS connection made during the API test. Disable this only for testing environments with self-signed or invalid certificates.
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.
Allow unsafe legacy renegotiation
Allows TLS renegotiation with older servers that do not support the secure renegotiation extension (RFC 5746). This setting applies to all connections made during the API test.
API Test API Performance Settings
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, adds an HTTP trace context header to all API calls made during the test. This allows the entire request sequence to be tracked across multiple backend services, which is essential for pinpointing performance bottlenecks in microservice architectures.
API Test Additional Settings
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.
Last updated