Getting Started

The following sections introduce you to the ThousandEyes API v7 resources and provide instructions to make your first API request. Learn how to retrieve a list of agents and create a network test. Examples will be shown using the command line with cURL.

Standard REST methods are supported on the API, which include POST, GET, and DELETE operations through HTTPS. All payloads to and from the REST interface must be in JSON format.

Below is high-level description of the API resources:

• Account Management - Manage users, accounts, and account groups in the ThousandEyes platform.
• Agents - Manage all agents available to your ThousandEyes account.
• Alerts - Manage all alerts, alert rules and alert suppression windows.
• BGP Monitors - Retrieve information about BGP monitors available to your ThousandEyes account.
• Credentials - Create, retrieve, update and delete credentials for transaction tests.
• Dashboards - Manage ThousandEyes Dashboards, Widgets and Dashboard snapshots.
• Emulation - Retrieve user-agent strings for HTTP, pageload, and transaction tests, and add emulated devices for pageload and transaction tests.
• Endpoint Agents - Create, retrieve, update and delete, transfer, enable, and disable ThousandEyes Endpoint Agents.
• Endpoint Instant Scheduled Tests - Create and execute a new endpoint instant scheduled test within ThousandEyes.
• Endpoint Labels - Manage labels applied to endpoint agents.
• Endpoint Tests - Manage endpoint agent dynamic and scheduled tests.
• Endpoint Test Results - Retrieve results for scheduled and dynamic tests on endpoint agents.
• Instant Tests - Create and run new instant tests.
• Internet Insights - Retrieve catalog providers and retrieve network and application outages.
• Snapshots - Create a new test snapshot in ThousandEyes.
• Tags - Create, retrieve, update and delete tags.
• Tests - Create, retrieve, update and delete Cloud and Enterprise Agent (CEA) tests.
• Templates - Create a set of tests, alert rules, dashboards, and labels from a single template configuration file.
• Test Results - Get test result metrics for Cloud and Enterprise Agent tests.
• ThousandEyes for OpenTelemetry - Export ThousandEyes telemetry data in OTel format.
• Usage - Retrieve usage details.

API User Requirements

To use the ThousandEyes API, you must have the following:

• 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.

• You must have a user API token generated by the ThousandEyes platform to authenticate your requests.

Base URI

Every API request will begin with the following Base URI.

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

1. Authorization

In addition to the path URL, an Authorization header must be added to every API request with the following format.

Authorization: Bearer $BEARER_TOKEN

Read more about authenticating, including generating an access token here.

2. Obtain a List of Agents

To create a test, an agent is required. To check which agents are available:

Request

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

Response

{ 
    [
        {
        "agentId": 12345,
        "agentName": "Tests",
        "agentType": "Cloud",
        "countryId": "US",
        "targetOnly": 0,
        "ipAddresses": [
            "128.0.0.1"
        ],
        "location": "San Francisco Area",
        "createdDate": "2023-01-25 22:01:45"
        },
        ...
    ]
}

3. Create a Test

From the list of available agents, select one Cloud Agent and use its agentId to create a test:

Request

curl -i -XPOST https://api.thousandeyes.com/v7/tests/agent-to-server/ -H "Authorization: Bearer $BEARER_TOKEN" -d '{
        "interval": 60,
        "agents": [
        {"agentId": 12345}
        ],
        "testName": "Sample Test",
        "server": "www.thousandeyes.com",
        "port": 80,
        "alertsEnabled": 0
    }'

Response

{
"test": [
    {
    "enabled": 1,
    "testId": 987654,
    "testName": "Sample Test",
    "type": "agent-to-server"
    ...
    }]
}

Try It Out Using Postman Collections

Prefer to use Postman rather than code or the command line? Check out our Postman Collections.