ThousandEyes.Api 7.0.104

dotnet add package ThousandEyes.Api --version 7.0.104
                    
NuGet\Install-Package ThousandEyes.Api -Version 7.0.104
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="ThousandEyes.Api" Version="7.0.104" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="ThousandEyes.Api" Version="7.0.104" />
                    
Directory.Packages.props
<PackageReference Include="ThousandEyes.Api" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add ThousandEyes.Api --version 7.0.104
                    
#r "nuget: ThousandEyes.Api, 7.0.104"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package ThousandEyes.Api@7.0.104
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=ThousandEyes.Api&version=7.0.104
                    
Install as a Cake Addin
#tool nuget:?package=ThousandEyes.Api&version=7.0.104
                    
Install as a Cake Tool

ThousandEyes API .NET Library

NuGet Version NuGet Downloads Build Status Codacy Badge License: MIT

Need help with APIs or .NET? Panoramic Data are experts in APIs and .NET, and we can help with your development. Contact us or see our software services.

A comprehensive, modern .NET library for interacting with the ThousandEyes API v7. This library provides complete coverage of core monitoring and alert management APIs with a clean, intuitive interface using modern C# patterns and best practices.

Supports .NET 11.0.

🎉 Major Release: Phase 3 Advanced APIs In Progress

🚀 ThousandEyes.Api now provides comprehensive monitoring, alerting, and reporting capabilities!

  • ✅ Complete Account Management - Users, roles, permissions, audit logs
  • ✅ Complete Test Management - All test types with full CRUD operations
  • ✅ Complete Agent Management - Cloud and Enterprise agent operations
  • ✅ Complete Test Results Access - Network, HTTP, and path visualization data
  • ✅ Complete Alert Management - Alert monitoring and rule configuration with notifications
  • 🚧 Advanced Dashboards & Reporting - Framework implemented, endpoint validation in progress
  • ✅ 94% Test Success Rate - 46/49 tests passing with real API integration
  • ✅ Production Ready - Zero warnings, modern .NET 11.0, comprehensive documentation

📚 Official Documentation

🎯 For the definitive and most up-to-date API documentation, always refer to:
https://developer.cisco.com/docs/thousandeyes/overview/

Additional Resources

Features

  • 🎯 Complete Monitoring Coverage - Full support for Tests, Agents, Test Results, and Alerts APIs
  • 🏛️ Complete Administrative Coverage - Full support for all ThousandEyes Administrative API v7 endpoints
  • 🚨 Complete Alert Management - Alert monitoring, rule configuration, and notification management
  • 📊 Advanced Reporting Framework - Dashboard and report models with modern architecture patterns
  • 🚀 Modern .NET 11.0 - Built with primary constructors, collection expressions, and latest C# features
  • 🏛️ Refit-Powered - Uses Refit for type-safe, declarative HTTP API definitions
  • 🔒 Type Safety - Strongly typed models and responses with comprehensive validation
  • 📝 Comprehensive Logging - Built-in logging and request/response interception
  • 🔄 Retry Logic - Automatic retry with exponential backoff for resilient operations
  • 📖 Rich Documentation - IntelliSense-friendly XML documentation
  • ✅ 94% Test Success Rate - 46 tests with 94% success rate and real API integration
  • ⚡ High Performance - Optimized for efficiency and low memory usage
  • 🔐 Bearer Token Authentication - Simple, secure token-based authentication
  • 🏗️ Modular Architecture - Organized API modules matching ThousandEyes structure

Installation

Install the package via NuGet Package Manager:

dotnet add package ThousandEyes.Api

Or via Package Manager Console:

Install-Package ThousandEyes.Api

Quick Start

1. Authentication Setup

ThousandEyes API uses Bearer Token authentication. You'll need:

  1. Bearer Token - Your API token from the ThousandEyes platform
Obtaining API Credentials in ThousandEyes
  1. Log into your ThousandEyes platform
  2. Navigate to Account Settings → Users and Roles → API Tokens
  3. Click Add New Token to create a new API token
  4. Configure the token settings:
    • Token Name: Your application name
    • Permissions: Select appropriate permissions for your use case (Account management, User management, etc.)
  5. Save the token to generate your Bearer Token
  6. Important: Store the token securely - it won't be displayed again
using ThousandEyes.Api;

// Modern .NET 11.0 approach with primary constructor
var options = new ThousandEyesClientOptions
{
    BearerToken = "your-bearer-token"
};

using var client = new ThousandEyesClient(options);

2. Account Management Examples

Working with Account Groups
// Use a CancellationToken for all async operations
using var cts = new CancellationTokenSource();
var cancellationToken = cts.Token;

// Get all account groups
var accountGroups = await client.AccountManagement.AccountGroups.GetAllAsync(cancellationToken);

foreach (var accountGroup in accountGroups.AccountGroupsList)
{
    Console.WriteLine($"Account Group: {accountGroup.AccountGroupName} (ID: {accountGroup.Aid})");
}

// Get a specific account group with details
var accountGroup = await client.AccountManagement.AccountGroups.GetByIdAsync("1234", null, cancellationToken);
Console.WriteLine($"Account Group: {accountGroup.AccountGroupName}");
Console.WriteLine($"Organization: {accountGroup.OrganizationName}");

// Create a new account group
var newAccountGroup = new AccountGroupRequest
{
    AccountGroupName = "New Account Group",
    Agents = ["105", "719"] // Enterprise agent IDs to assign
};

var createdAccountGroup = await client.AccountManagement.AccountGroups.CreateAsync(newAccountGroup, null, cancellationToken);
Console.WriteLine($"Created account group with ID: {createdAccountGroup.Aid}");
Working with Users
// Get all users
var users = await client.AccountManagement.Users.GetAllAsync(aid: null, cancellationToken);

foreach (var user in users.UsersList)
{
    Console.WriteLine($"User: {user.Name} ({user.Email})");
    Console.WriteLine($"Last Login: {user.LastLogin}");
}

// Get current user details (no ID required)
var currentUser = await client.AccountManagement.Users.GetCurrentAsync(cancellationToken);
Console.WriteLine($"Current User: {currentUser.Name} ({currentUser.Email})");

// Create a new user
var newUser = new UserRequest
{
    Name = "Jane Smith",
    Email = "jane.smith@example.com",
    LoginAccountGroupId = "691",
    AccountGroupRoles = 
    [
        new UserAccountGroupRole
        {
            AccountGroupId = "315",
            RoleIds = ["57", "1140"]
        }
    ]
};

var createdUser = await client.AccountManagement.Users.CreateAsync(newUser, aid: null, cancellationToken);
Console.WriteLine($"Created user with ID: {createdUser.Uid}");

3. Test Management Examples ✅

Working with Tests
// Get all tests in the account
var allTests = await client.Tests.Tests.GetAllAsync(aid: null, cancellationToken);

foreach (var test in allTests.TestsList)
{
    Console.WriteLine($"Test: {test.TestName} ({test.Type})");
    Console.WriteLine($"  ID: {test.TestId}");
    Console.WriteLine($"  Interval: {test.Interval} seconds");
    Console.WriteLine($"  Enabled: {test.Enabled}");
}

// Get test version history
var history = await client.Tests.Tests.GetVersionHistoryAsync(
    testId: "12345", 
    aid: null, 
    limit: 10, 
    cancellationToken);

foreach (var version in history.TestVersionHistory)
{
    Console.WriteLine($"Version: {version.VersionId} at {version.VersionTimestamp}");
    Console.WriteLine($"Created by: {version.CreatedBy}");
}
Working with HTTP Server Tests
// Get all HTTP Server tests
var httpTests = await client.Tests.HttpServerTests.GetAllAsync(aid: null, cancellationToken);

foreach (var test in httpTests.Tests)
{
    Console.WriteLine($"HTTP Test: {test.TestName}");
    Console.WriteLine($"  URL: {test.Url}");
    Console.WriteLine($"  Status Code: {test.DesiredStatusCode}");
    Console.WriteLine($"  Agents: {test.Agents.Length}");
}

// Create a new HTTP Server test
var newHttpTest = new HttpServerTestRequest
{
    TestName = "API Health Monitor",
    Url = "https://api.example.com/health",
    Interval = 300, // 5 minutes
    Enabled = true,
    DesiredStatusCode = "200",
    HttpTimeLimit = 10,
    FollowRedirects = true,
    VerifyCertificate = true,
    NetworkMeasurements = true,
    BgpMeasurements = true,
    Agents = [
        new TestAgentRequest { AgentId = "12345" },
        new TestAgentRequest { AgentId = "67890" }
    ]
};

var createdTest = await client.Tests.HttpServerTests.CreateAsync(
    newHttpTest, 
    aid: null, 
    expand: null, 
    cancellationToken);

Console.WriteLine($"Created HTTP test with ID: {createdTest.TestId}");

// Get test details
var testDetails = await client.Tests.HttpServerTests.GetByIdAsync(
    createdTest.TestId, 
    aid: null, 
    versionId: null, 
    expand: null, 
    cancellationToken);

// Update test
testDetails.Interval = 600; // Change to 10 minutes
var updatedTest = await client.Tests.HttpServerTests.UpdateAsync(
    testDetails.TestId, 
    testDetails, 
    aid: null, 
    expand: null, 
    cancellationToken);

// Delete test when no longer needed
await client.Tests.HttpServerTests.DeleteAsync(
    testDetails.TestId, 
    aid: null, 
    cancellationToken);
Working with Other Test Types
// Get DNS Server tests
var dnsTests = await client.Tests.DnsServerTests.GetAllAsync(aid: null, cancellationToken);
foreach (var test in dnsTests.Tests)
{
    Console.WriteLine($"DNS Test: {test.TestName} - {test.Domain}");
}

// Get BGP tests
var bgpTests = await client.Tests.BgpTests.GetAllAsync(aid: null, cancellationToken);
foreach (var test in bgpTests.Tests)
{
    Console.WriteLine($"BGP Test: {test.TestName} - {test.Prefix}");
}

// Get Page Load tests
var pageLoadTests = await client.Tests.PageLoadTests.GetAllAsync(aid: null, cancellationToken);
foreach (var test in pageLoadTests.Tests)
{
    Console.WriteLine($"Page Load Test: {test.TestName} - {test.Url}");
}

// Get Web Transaction tests
var webTransactionTests = await client.Tests.WebTransactionTests.GetAllAsync(aid: null, cancellationToken);
foreach (var test in webTransactionTests.Tests)
{
    Console.WriteLine($"Web Transaction Test: {test.TestName} - {test.Url}");
}

// Get Agent-to-Server tests
var agentToServerTests = await client.Tests.AgentToServerTests.GetAllAsync(aid: null, cancellationToken);
foreach (var test in agentToServerTests.Tests)
{
    Console.WriteLine($"Agent-to-Server Test: {test.TestName} - {test.Server}:{test.Port}");
}

// Get Agent-to-Agent tests
var agentToAgentTests = await client.Tests.AgentToAgentTests.GetAllAsync(aid: null, cancellationToken);
foreach (var test in agentToAgentTests.Tests)
{
    Console.WriteLine($"Agent-to-Agent Test: {test.TestName} - Target: {test.TargetAgentId}");
}

4. Agent Management Examples ✅

Working with Agents
// Get all agents (Cloud and Enterprise)
var agents = await client.Agents.Agents.GetAllAsync(aid: null, cancellationToken);

foreach (var agent in agents.AgentsList)
{
    Console.WriteLine($"Agent: {agent.AgentName} ({agent.AgentType})");
    Console.WriteLine($"  ID: {agent.AgentId}");
    Console.WriteLine($"  Location: {agent.Location}, {agent.CountryId}");
    Console.WriteLine($"  Status: {agent.AgentState}");
    Console.WriteLine($"  Last Seen: {agent.LastSeen}");
    Console.WriteLine($"  IPv6 Support: {agent.Ipv6Policy}");
    
    if (agent.IpAddresses?.Length > 0)
    {
        Console.WriteLine($"  IP Addresses: {string.Join(", ", agent.IpAddresses)}");
    }
}

// Get specific agent details
var agentDetails = await client.Agents.Agents.GetByIdAsync(
    agentId: "12345", 
    aid: null, 
    cancellationToken);

Console.WriteLine($"Agent Details:");
Console.WriteLine($"  Name: {agentDetails.AgentName}");
Console.WriteLine($"  Network: {agentDetails.Network}");
Console.WriteLine($"  AS Number: {agentDetails.AsNumber}");
Console.WriteLine($"  Utilization: {agentDetails.Utilization}%");
Console.WriteLine($"  Version: {agentDetails.Version}");

// Get supported test types for an agent
var supportedTests = await client.Agents.Agents.GetSupportedTestsAsync(
    agentId: "12345", 
    aid: null, 
    cancellationToken);

Console.WriteLine($"Supported test types: {string.Join(", ", supportedTests)}");

// Create a new Enterprise Agent
var newAgent = new AgentRequest
{
    AgentName = "New Enterprise Agent",
    Enabled = true,
    Ipv6Policy = true,
    TargetForTests = "agent-target.example.com"
};

var createdAgent = await client.Agents.Agents.CreateAsync(
    newAgent, 
    aid: null, 
    cancellationToken);

Console.WriteLine($"Created Enterprise Agent with ID: {createdAgent.AgentId}");

// Update agent configuration
var updateRequest = new AgentRequest
{
    AgentName = "Updated Agent Name",
    Enabled = true,
    Ipv6Policy = false
};

var updatedAgent = await client.Agents.Agents.UpdateAsync(
    agentId: createdAgent.AgentId, 
    updateRequest, 
    aid: null, 
    cancellationToken);

// Delete Enterprise Agent (Cloud agents cannot be deleted)
await client.Agents.Agents.DeleteAsync(
    agentId: createdAgent.AgentId, 
    aid: null, 
    cancellationToken);

5. Test Results Examples ✅

Retrieving Monitoring Data
// Get network test results for the last 24 hours
var networkResults = await client.TestResults.TestResults.GetNetworkResultsAsync(
    testId: "12345",
    fromDate: DateTime.UtcNow.AddHours(-24),
    toDate: DateTime.UtcNow,
    aid: null,
    cancellationToken);

foreach (var result in networkResults.Results)
{
    Console.WriteLine($"Network Result - Agent: {result.AgentName}");
    Console.WriteLine($"  Date: {result.Date}");
    Console.WriteLine($"  Loss: {result.Loss}%");
    Console.WriteLine($"  Latency: {result.Latency}ms");
    Console.WriteLine($"  Jitter: {result.Jitter}ms");
    
    if (result.PathVis?.Length > 0)
    {
        Console.WriteLine("  Path Trace:");
        foreach (var hop in result.PathVis)
        {
            Console.WriteLine($"    Hop {hop.HopNumber}: {hop.IpAddress} ({hop.ResponseTime}ms)");
        }
    }
}

// Get HTTP Server test results
var httpResults = await client.TestResults.TestResults.GetHttpServerResultsAsync(
    testId: "67890",
    fromDate: DateTime.UtcNow.AddHours(-24),
    toDate: DateTime.UtcNow,
    aid: null,
    cancellationToken);

foreach (var result in httpResults.Results)
{
    Console.WriteLine($"HTTP Result - Agent: {result.AgentName}");
    Console.WriteLine($"  Date: {result.Date}");
    Console.WriteLine($"  Response Code: {result.ResponseCode}");
    Console.WriteLine($"  Response Time: {result.ResponseTime}ms");
    Console.WriteLine($"  DNS Time: {result.DnsTime}ms");
    Console.WriteLine($"  Connect Time: {result.ConnectTime}ms");
    Console.WriteLine($"  SSL Time: {result.SslTime}ms");
    Console.WriteLine($"  Wait Time: {result.WaitTime}ms");
    Console.WriteLine($"  Receive Time: {result.ReceiveTime}ms");
    Console.WriteLine($"  Total Size: {result.TotalSize} bytes");
    
    if (result.Headers?.Count > 0)
    {
        Console.WriteLine("  Response Headers:");
        foreach (var header in result.Headers)
        {
            Console.WriteLine($"    {header.Key}: {header.Value}");
        }
    }
}

// Get path visualization results
var pathResults = await client.TestResults.TestResults.GetPathVisualizationResultsAsync(
    testId: "11111",
    fromDate: DateTime.UtcNow.AddHours(-6),
    toDate: DateTime.UtcNow,
    aid: null,
    cancellationToken);

foreach (var result in pathResults.Results)
{
    Console.WriteLine($"Path Visualization - Agent: {result.AgentName}");
    Console.WriteLine($"  Date: {result.Date}");
    
    if (result.PathVis?.Length > 0)
    {
        Console.WriteLine("  Network Path:");
        foreach (var hop in result.PathVis)
        {
            Console.WriteLine($"    Hop {hop.HopNumber}: {hop.IpAddress}");
            if (!string.IsNullOrEmpty(hop.Hostname))
                Console.WriteLine($"      Hostname: {hop.Hostname}");
            if (!string.IsNullOrEmpty(hop.Network))
                Console.WriteLine($"      Network: {hop.Network}");
            if (hop.AsNumber.HasValue)
                Console.WriteLine($"      AS: {hop.AsNumber}");
            if (hop.ResponseTime.HasValue)
                Console.WriteLine($"      Response Time: {hop.ResponseTime}ms");
        }
    }
}

6. Alert Management Examples ✅

Working with Alerts
// Get all alerts from the last 7 days
var alerts = await client.Alerts.Alerts.GetAllAsync(
    aid: null, 
    window: "7d", 
    fromDate: null, 
    toDate: null, 
    cancellationToken);

foreach (var alert in alerts.AlertsList)
{
    Console.WriteLine($"Alert: {alert.TestName} - {alert.Status} ({alert.Severity})");
    Console.WriteLine($"  Alert ID: {alert.AlertId}");
    Console.WriteLine($"  Started: {alert.DateStart}");
    Console.WriteLine($"  Type: {alert.Type}");
    
    if (alert.DateEnd.HasValue)
        Console.WriteLine($"  Ended: {alert.DateEnd}");
    
    if (alert.ViolationMetric != null)
    {
        Console.WriteLine($"  Violation: {alert.ViolationMetric}");
        Console.WriteLine($"  Threshold: {alert.ThresholdValue}, Actual: {alert.ActualValue}");
    }
}

// Get specific alert details
var alertDetails = await client.Alerts.Alerts.GetByIdAsync(
    alertId: "alert-123", 
    aid: null, 
    cancellationToken);

Console.WriteLine($"Alert Details:");
Console.WriteLine($"  Test: {alertDetails.TestName}");
Console.WriteLine($"  Agent: {alertDetails.AgentName}");
Console.WriteLine($"  Condition: {alertDetails.AlertCondition}");
Working with Alert Rules
// Get all alert rules
var alertRules = await client.Alerts.AlertRules.GetAllAsync(aid: null, cancellationToken);

foreach (var rule in alertRules.AlertRulesList)
{
    Console.WriteLine($"Alert Rule: {rule.RuleName}");
    Console.WriteLine($"  Rule ID: {rule.RuleId}");
    Console.WriteLine($"  Expression: {rule.Expression}");
    Console.WriteLine($"  Type: {rule.AlertType}");
    Console.WriteLine($"  Severity: {rule.Severity}");
    Console.WriteLine($"  Enabled: {rule.Enabled}");
    Console.WriteLine($"  Tests: {rule.Tests.Length}");
}

// Create a new alert rule
var newAlertRule = new AlertRuleRequest
{
    RuleName = "High Latency Alert",
    Description = "Trigger when response time exceeds 500ms",
    Expression = "((responseTime >= 500))",
    Enabled = true,
    AlertType = "test",
    Severity = "warning",
    MinimumSources = 2,
    MinimumSourcesPct = 75,
    RoundsBelowThreshold = 3,
    Tests = [
        new AlertRuleTest { TestId = "12345", TestName = "API Health Check" }
    ],
    Notifications = new AlertRuleNotifications
    {
        Emails = ["alerts@company.com", "devops@company.com"],
        Webhooks = [
            new AlertRuleWebhook 
            { 
                Url = "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK", 
                Method = "POST",
                Headers = { ["Content-Type"] = "application/json" }
            }
        ],
        Integrations = [
            new AlertRuleIntegration 
            { 
                Type = "pagerduty", 
                Target = "service-key-123" 
            }
        ]
    }
};

var createdRule = await client.Alerts.AlertRules.CreateAsync(
    newAlertRule, 
    aid: null, 
    cancellationToken);

Console.WriteLine($"Created alert rule with ID: {createdRule.RuleId}");

// Update an existing alert rule
var updateRequest = new AlertRuleRequest
{
    RuleName = "Updated High Latency Alert",
    Description = "Updated threshold to 600ms",
    Expression = "((responseTime >= 600))",
    Enabled = true,
    AlertType = "test",
    Severity = "critical", // Changed severity
    MinimumSources = 3,    // Increased minimum sources
    MinimumSourcesPct = 80,
    RoundsBelowThreshold = 2,
    Tests = createdRule.Tests,
    Notifications = createdRule.Notifications
};

var updatedRule = await client.Alerts.AlertRules.UpdateAsync(
    createdRule.RuleId, 
    updateRequest, 
    aid: null, 
    cancellationToken);

Console.WriteLine($"Updated alert rule: {updatedRule.RuleName}");

// Get specific alert rule details
var ruleDetails = await client.Alerts.AlertRules.GetByIdAsync(
    createdRule.RuleId, 
    aid: null, 
    cancellationToken);

Console.WriteLine($"Rule Details:");
Console.WriteLine($"  Name: {ruleDetails.RuleName}");
Console.WriteLine($"  Expression: {ruleDetails.Expression}");
Console.WriteLine($"  Created: {ruleDetails.CreatedDate}");
Console.WriteLine($"  Modified: {ruleDetails.ModifiedDate}");

// Delete alert rule when no longer needed
await client.Alerts.AlertRules.DeleteAsync(
    createdRule.RuleId, 
    aid: null, 
    cancellationToken);

7. Dashboard and Reporting Framework 🚧

The library includes a complete framework for dashboards and reporting with modern architectural patterns. This framework provides type-safe models for dashboard configuration, widget management, and report scheduling.

// Dashboard framework example (endpoint validation in progress)
var dashboardRequest = new DashboardRequest
{
    DashboardName = "Production Monitoring Dashboard",
    Description = "Real-time monitoring of production services",
    DashboardType = "shared",
    IsPrivate = false,
    Layout = new DashboardLayout
    {
        Type = "grid",
        Columns = 12,
        RowHeight = 150,
        IsResponsive = true
    },
    Widgets = [
        new DashboardWidget
        {
            WidgetId = "response-time-widget",
            Title = "Response Time Trends",
            Type = "timeseries",
            Position = new WidgetPosition { X = 0, Y = 0, Width = 6, Height = 3 },
            DataSource = new WidgetDataSource
            {
                Type = "test",
                TestIds = ["12345", "67890"],
                Metrics = ["responseTime", "availability"],
                Aggregation = "average"
            },
            Visualization = new WidgetVisualization
            {
                ChartType = "line",
                ShowLegend = true,
                ShowGrid = true
            }
        }
    ]
};


// Note: Endpoint validation in progress - graceful error handling implemented
try
{
    var dashboard = await client.Dashboards.Dashboards.CreateAsync(
        dashboardRequest, 
        aid: null, 
        cancellationToken);
}
catch (ValidationApiException ex) when (ex.StatusCode == System.Net.HttpStatusCode.NotFound)
{
    // Framework ready, awaiting endpoint specification confirmation
}

8. API Module Overview

The ThousandEyes API is organized into logical modules that match the official ThousandEyes API structure:

✅ Account Management (Phase 1 - COMPLETED)
// Access administrative functionality
client.AccountManagement.AccountGroups   // Account group management
client.AccountManagement.Users          // User management
client.AccountManagement.Roles          // Role management
client.AccountManagement.Permissions    // Permission queries
client.AccountManagement.UserEvents     // Audit logs
✅ Core Monitoring (Phase 2 - COMPLETED)
// Test management and monitoring data
client.Tests.Tests                   // General test operations
client.Tests.HttpServerTests         // HTTP Server tests (full CRUD)
client.Tests.DnsServerTests          // DNS Server tests
client.Tests.BgpTests                // BGP tests
client.Tests.PageLoadTests           // Page Load tests
client.Tests.WebTransactionTests     // Web Transaction tests
client.Tests.AgentToServerTests      // Agent to Server tests
client.Tests.AgentToAgentTests       // Agent to Agent tests

client.Agents.Agents                 // Agent management (Cloud + Enterprise)

client.TestResults.TestResults       // Monitoring data retrieval
✅ Alert Management (Phase 3 - COMPLETED)
// Alert monitoring and management
client.Alerts.Alerts                 // Alert monitoring and status
client.Alerts.AlertRules             // Alert rule configuration (full CRUD)
🚧 Advanced Reporting (Phase 3 - FRAMEWORK READY)
// Advanced monitoring capabilities (framework implemented)
client.Dashboards.Dashboards         // Dashboard management and configuration
client.Dashboards.Reports            // Report management and scheduling
🚧 Future Features (Phase 4+)
// Additional specialized monitoring capabilities (planned)
client.Snapshots     // Data preservation and sharing
client.BgpMonitors   // BGP monitoring and route analysis
// Additional modules: InternetInsights, EventDetection, etc.

9. Advanced Configuration

Custom HTTP Configuration
var options = new ThousandEyesClientOptions
{
    BearerToken = "your-bearer-token",
    
    // Custom timeout
    RequestTimeout = TimeSpan.FromSeconds(30),
    
    // Custom retry policy with exponential backoff
    MaxRetryAttempts = 3,
    RetryDelay = TimeSpan.FromSeconds(1),
    UseExponentialBackoff = true,
    MaxRetryDelay = TimeSpan.FromSeconds(30)
};

using var client = new ThousandEyesClient(options);
Logging Configuration
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.DependencyInjection;

// Create a service collection with logging
var services = new ServiceCollection();
services.AddLogging(builder => builder.AddConsole().SetMinimumLevel(LogLevel.Debug));

using var serviceProvider = services.BuildServiceProvider();
var logger = serviceProvider.GetRequiredService<ILogger<ThousandEyesClient>>();

var options = new ThousandEyesClientOptions
{
    BearerToken = "your-bearer-token",
    Logger = logger,
    EnableRequestLogging = true,
    EnableResponseLogging = true
};

using var client = new ThousandEyesClient(options);

10. Error Handling

try
{
    var user = await client.AccountManagement.Users.GetByIdAsync("99999", aid: null, cancellationToken);
}
catch (ThousandEyesNotFoundException ex)
{
    Console.WriteLine($"Resource not found: {ex.Message}");
    Console.WriteLine($"Resource Type: {ex.ResourceType}");
    Console.WriteLine($"Resource ID: {ex.ResourceId}");
}
catch (ThousandEyesAuthenticationException ex)
{
    Console.WriteLine($"Authentication failed: {ex.Message}");
    Console.WriteLine("Check your bearer token and permissions");
}
catch (ThousandEyesRateLimitException ex)
{
    Console.WriteLine($"Rate limit exceeded: {ex.Message}");
    Console.WriteLine($"Retry after: {ex.RetryAfterSeconds} seconds");
}
catch (ThousandEyesBadRequestException ex)
{
    Console.WriteLine($"Bad request: {ex.Message}");
    if (ex.ValidationErrors?.Count > 0)
    {
        Console.WriteLine("Validation errors:");
        foreach (var error in ex.ValidationErrors)
        {
            Console.WriteLine($"  - {error}");
        }
    }
}
catch (ThousandEyesApiException ex)
{
    Console.WriteLine($"API error: {ex.Message}");
    Console.WriteLine($"Status code: {ex.StatusCode}");
    Console.WriteLine($"Request URL: {ex.RequestUrl}");
}

API Coverage

This library provides comprehensive coverage of the ThousandEyes API ecosystem, organized into logical modules.

📖 For complete and up-to-date API endpoint documentation, always refer to:
https://developer.cisco.com/docs/thousandeyes/overview/

Available API Modules

Module Status Description
AccountManagement ✅ Completed Account groups, users, roles, permissions, audit logs
Tests ✅ Completed Test configuration and management for all test types
Agents ✅ Completed Cloud and Enterprise agent management
TestResults ✅ Completed Monitoring data retrieval and metrics
Alerts ✅ Completed Alert monitoring and rule management with notifications
Dashboards 🚧 Framework Ready Dashboard and reporting models implemented, endpoint validation in progress
Snapshots 🚧 Phase 3 Data preservation and sharing
BgpMonitors 🚧 Phase 4 BGP monitoring and route analysis

Administrative Module (✅ Completed)

Endpoint Operations Description
/account-groups GET, POST List and create account groups
/account-groups/{id} GET, PUT, DELETE Manage specific account groups
/users GET, POST List and create users
/users/{id} GET, PUT, DELETE Manage specific users
/users/current GET Get current user details
/roles GET, POST List and create roles
/roles/{id} GET, PUT, DELETE Manage specific roles
/permissions GET List assignable permissions
/audit-user-events GET Retrieve activity log events

Tests Module (✅ Completed)

Endpoint Operations Description
/tests GET List all tests
/tests/{testId}/history GET Get test version history
/tests/http-server GET, POST List and create HTTP Server tests
/tests/http-server/{testId} GET, PUT, DELETE Manage specific HTTP Server tests
/tests/dns-server GET List DNS Server tests
/tests/bgp GET List BGP tests
/tests/page-load GET List Page Load tests
/tests/web-transactions GET List Web Transaction tests
/tests/agent-to-server GET List Agent to Server tests
/tests/agent-to-agent GET List Agent to Agent tests

Agents Module (✅ Completed)

Endpoint Operations Description
/agents GET, POST List all agents and create Enterprise agents
/agents/{agentId} GET, PUT, DELETE Manage specific agents
/agents/{agentId}/supported-tests GET Get supported test types for agent

Test Results Module (✅ Completed)

Endpoint Operations Description
/test-results/{testId}/network GET Get network test results
/test-results/{testId}/http-server GET Get HTTP Server test results
/test-results/{testId}/path-vis GET Get path visualization results

Alerts Module (✅ Completed)

Endpoint Operations Description
/alerts GET List all alerts with filtering
/alerts/{alertId} GET Get specific alert details
/alert-rules GET, POST List and create alert rules
/alert-rules/{ruleId} GET, PUT, DELETE Manage specific alert rules

Dashboards Module (🚧 Framework Ready)

Endpoint Operations Description Status
/dashboards GET, POST List and create dashboards 🚧 Endpoint validation in progress
/dashboards/{dashboardId} GET, PUT, DELETE Manage specific dashboards 🚧 Endpoint validation in progress
/reports GET, POST List and create reports 🚧 Endpoint validation in progress
/reports/{reportId} GET, PUT, DELETE Manage specific reports 🚧 Endpoint validation in progress

Architecture

This library is built using modern .NET 11.0 patterns and follows industry best practices:

  • Modular Design - API endpoints organized into logical modules matching ThousandEyes structure
  • Refit-Powered APIs - Uses Refit for type-safe, declarative HTTP API definitions
  • Primary Constructors - Modern C# syntax throughout
  • Collection Expressions - Uses [] syntax for cleaner code
  • Required Properties - Enforces mandatory configuration at compile time
  • Comprehensive Exception Handling - Specific exception types for different API error scenarios
  • Handler Chain Pattern - Composable HTTP handlers for authentication, retry, logging, and error handling
  • Zero Warnings Policy - All code compiles without warnings
  • High Test Success Rate - Comprehensive testing with 46/49 tests passing (94% success rate)

Development Roadmap

For a complete implementation roadmap covering all ThousandEyes API modules, see Implementation Plan.

✅ Phase 1: COMPLETED

  • Account Management: Full administrative API coverage

✅ Phase 2: COMPLETED

  • Tests API: Complete test management functionality with full CRUD for HTTP Server tests
  • Agents API: Complete Cloud and Enterprise agent operations
  • Test Results API: Comprehensive monitoring data retrieval

✅ Phase 3: Advanced APIs - MAJOR PROGRESS

  • Alerts API: ✅ Complete alert monitoring and rule management with notifications
  • Dashboards API: 🚧 Framework implemented, endpoint validation in progress

🚧 Phase 3: Remaining (Next Priority)

  • Snapshots API: Data preservation and sharing
  • API Specification Review: Validate endpoints against official ThousandEyes API v7 documentation

🚧 Future Phases (Phase 4+)

  • Specialized monitoring (BGP Monitors, Internet Insights, Event Detection)
  • Integration APIs (Integrations, Credentials, Usage)
  • Specialized features (Emulation, Endpoint Agents, Tags, Templates)

Contributing

We welcome contributions from the community! Here's how you can help:

Development Setup

  1. Clone the repository:

    git clone https://github.com/panoramicdata/ThousandEyes.Api.git
    cd ThousandEyes.Api
    
  2. Install .NET 11.0 SDK: Download from dotnet.microsoft.com

  3. Set up User Secrets for testing:

    cd ThousandEyes.Api.Test
    dotnet user-secrets init
    dotnet user-secrets set "ThousandEyes:BearerToken" "your-test-bearer-token"
    
  4. Build and test:

    dotnet build
    dotnet test
    

Coding Standards

  • Follow the project's coding standards as defined in copilot-instructions.md
  • Use modern C# patterns (primary constructors, collection expressions, required properties)
  • Maintain zero warnings policy - all code must compile without warnings
  • Maintain high test success rate - currently 46/49 tests passing (94% success rate)
  • Write comprehensive tests - both unit and integration tests required
  • Document public APIs - use XML documentation comments
  • Always use explicit CancellationTokens - no optional parameters for async methods

Pull Request Process

  1. Fork the repository and create a feature branch
  2. Follow the implementation plan in Specification/ImplementationPlan.md
  3. Write tests first - TDD approach preferred
  4. Ensure high test success rate including integration tests
  5. Update documentation as needed
  6. Submit a pull request with a clear description of changes

Issue Reporting

When reporting issues:

  • Use the issue templates provided in the repository
  • Include minimal reproduction code when possible
  • Specify the library version and .NET version
  • Include relevant error messages and stack traces

Support

License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright © 2026 Panoramic Data Limited. All rights reserved.

Changelog

See CHANGELOG.md for a detailed history of changes and releases

Product Compatible and additional computed target framework versions.
.NET net11.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
7.0.104 43 11/17/2026
7.0.91 82 11/10/2026
7.0.29-alpha 229 10/7/2025