Building Custom Dashboards with the Server Scout API

Why Build Custom Dashboards?

The Server Scout dashboard at app.serverscout.ie provides comprehensive monitoring capabilities for most use cases, with multi-user access, dark/light themes, and PWA functionality. However, certain scenarios benefit from custom dashboard implementations:

  • NOC displays showing only specific servers or critical metrics on large screens
  • Client-facing status pages displaying uptime and performance for customer servers
  • Integration with internal tools combining Server Scout data with other business systems
  • Specialised views tailored to specific workflows or organisational requirements

Custom dashboards allow you to present exactly the data you need in formats that match your operational requirements.

API Endpoints for Dashboard Data

Server Scout's API provides three primary endpoints for building custom dashboards:

Server List Endpoint

Retrieves your complete server fleet for enumeration and filtering:

GET /api/servers

Current Metrics Endpoint

Fetches live data from the Fast (5s) collection tier for real-time displays:

GET /api/servers/{server_id}/metrics/current

Historical Metrics Endpoint

Retrieves time-series data for charts and trend analysis:

GET /api/servers/{server_id}/metrics/historical?start={timestamp}&end={timestamp}&metrics={metric_names}

Authentication for Custom Dashboards

For custom dashboard access, you have two authentication options:

Session-Based Authentication

Suitable for dashboards accessed by users who log into Server Scout:

// Uses existing session cookies from app.serverscout.ie
fetch('/api/servers', {
    credentials: 'include'
})

Dedicated API Key

Recommended for automated systems and embedded displays:

fetch('/api/servers', {
    headers: {
        'Authorization': 'Bearer your-api-key-here'
    }
})

Always ensure your custom dashboard uses HTTPS to protect authentication credentials and sensitive server data.

Polling Best Practices

Implement sensible polling patterns to maintain performance:

  • Current data: Poll no more frequently than every 5-10 seconds, matching Server Scout's Fast collection tier
  • Historical data: Use appropriate time ranges (hourly for daily views, daily for weekly views)
  • Client-side caching: Store fetched data temporarily to reduce API load
  • Error handling: Implement exponential backoff for failed requests
// Example polling with caching
let cachedData = null;
let lastFetch = 0;
const CACHE_DURATION = 10000; // 10 seconds

async function getCurrentMetrics(serverId) {
    const now = Date.now();
    if (cachedData && (now - lastFetch) < CACHE_DURATION) {
        return cachedData;
    }
    
    cachedData = await fetch(`/api/servers/${serverId}/metrics/current`);
    lastFetch = now;
    return cachedData;
}

Building Blocks for Custom Dashboards

Fleet Overview

Start by fetching your server list to create navigation and overview displays:

const servers = await fetch('/api/servers').then(r => r.json());
servers.forEach(server => {
    // Create server status cards
});

Live Monitoring

Fetch current metrics for real-time status displays:

for (const server of servers) {
    const metrics = await fetch(`/api/servers/${server.id}/metrics/current`)
        .then(r => r.json());
    updateServerCard(server.id, metrics);
}

Historical Charts

Retrieve time-series data for trend visualisation:

const chartData = await fetch(
    `/api/servers/${serverId}/metrics/historical?start=${startTime}&end=${endTime}&metrics=cpu,memory`
).then(r => r.json());

Front-End Technology Options

Server Scout's API works with any technology capable of making HTTPS requests:

  • Vanilla JavaScript for simple, lightweight dashboards
  • React/Vue/Angular for complex interactive interfaces
  • Python scripts for automated reporting and alerts
  • PowerBI/Grafana for advanced analytics integration

Example Architecture

Here's a simple custom dashboard structure:

<!DOCTYPE html>
<html>
<head>
    <title>NOC Dashboard</title>
</head>
<body>
    <div id="server-grid"></div>
    <script>
        async function updateDashboard() {
            const servers = await fetch('/api/servers').then(r => r.json());
            const grid = document.getElementById('server-grid');
            grid.innerHTML = '';
            
            for (const server of servers) {
                const metrics = await fetch(`/api/servers/${server.id}/metrics/current`)
                    .then(r => r.json());
                
                const card = document.createElement('div');
                card.innerHTML = `
                    <h3>${server.name}</h3>
                    <p>CPU: ${metrics.cpu}%</p>
                    <p>Memory: ${metrics.memory}%</p>
                    <p>Status: ${server.status}</p>
                `;
                grid.appendChild(card);
            }
        }
        
        // Update every 10 seconds
        updateDashboard();
        setInterval(updateDashboard, 10000);
    </script>
</body>
</html>

This architecture fetches server data every 10 seconds and updates a grid of status cards, perfect for NOC displays or embedded monitoring screens.

Remember that Server Scout's built-in dashboard handles most monitoring requirements effectively. Custom dashboards shine when you need specialised views, client-facing displays, or integration with existing systems.

Frequently Asked Questions

How do I get started building a custom dashboard with Server Scout API?

Start by using the /api/servers endpoint to fetch your complete server fleet, then use /api/servers/{server_id}/metrics/current for real-time data. You'll need either session-based authentication or a dedicated API key. Begin with a simple HTML structure that polls current metrics every 10 seconds and displays server status cards.

What are the main API endpoints for custom dashboards?

Server Scout provides three primary endpoints: /api/servers for retrieving your server list, /api/servers/{server_id}/metrics/current for live data from the 5-second collection tier, and /api/servers/{server_id}/metrics/historical for time-series data with customizable time ranges and metric selection.

How often should I poll the Server Scout API for dashboard updates?

Poll current data no more frequently than every 5-10 seconds to match Server Scout's Fast collection tier. For historical data, use appropriate time ranges like hourly for daily views. Implement client-side caching with a 10-second cache duration and exponential backoff for failed requests to maintain performance.

What authentication methods work with custom dashboards?

You can use session-based authentication for dashboards accessed by users who log into Server Scout, utilizing existing session cookies. For automated systems and embedded displays, use a dedicated API key with Bearer token authentication. Always ensure HTTPS to protect credentials and server data.

Why would I build a custom dashboard instead of using the main Server Scout interface?

Custom dashboards are beneficial for NOC displays showing only specific servers on large screens, client-facing status pages displaying uptime for customer servers, integration with internal business systems, and specialized views tailored to specific workflows or organizational requirements that the main dashboard doesn't address.

My custom dashboard API requests are failing, how do I troubleshoot?

Implement proper error handling with exponential backoff for failed requests. Check that you're using HTTPS for all API calls and that your authentication credentials are correct. Ensure you're not exceeding polling frequency limits and verify your API endpoints match the documented format with proper server IDs and parameters.

What front-end technologies can I use with Server Scout API?

Server Scout's API works with any technology capable of making HTTPS requests, including vanilla JavaScript for simple dashboards, React/Vue/Angular for complex interfaces, Python scripts for automated reporting, and analytics platforms like PowerBI or Grafana for advanced integration and visualization.

How do I retrieve historical data for dashboard charts?

Use the /api/servers/{server_id}/metrics/historical endpoint with start and end timestamp parameters and specify the metrics you need. For example, add ?start={timestamp}&end={timestamp}&metrics=cpu,memory to get CPU and memory data for a specific time range. This data is perfect for trend visualization and chart creation.

Was this article helpful?

Related Articles