Retrieving Server Metrics via the API

Overview

The Server Scout API provides programmatic access to all the server metrics collected by our monitoring agents. Whether you need current snapshots or historical data for analysis, the API delivers the same high-quality data that powers the dashboard graphs in your web interface.

This article covers how to retrieve server metrics via the API, including both current status and time-series data for custom integrations and reporting.

Authentication

Before accessing metrics, you'll need to authenticate using either:

• Your existing session cookie (if calling from a logged-in browser)
• An API key (recommended for programmatic access)

API keys can be generated from your account settings in the dashboard at app.serverscout.ie.

Getting Current Metrics

Current metrics provide the latest snapshot of all collected data for a server. This includes:

• CPU usage and load averages
• Memory utilisation (RAM and swap)
• Disk space and I/O statistics
• Network interface statistics
• System uptime and process counts
• Any enabled optional metrics (cPanel, DirectAdmin, Plesk, JetBackup, custom plugins)

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.serverscout.ie/api/servers/123/metrics/current

The response returns a JSON object with metric names as keys and current values:

{
  "timestamp": "2024-01-15T14:30:00Z",
  "cpu_usage": 23.4,
  "memory_used_percent": 67.2,
  "disk_root_used_percent": 45.8,
  "load_1min": 0.85,
  "network_eth0_rx_bytes": 1234567890
}

Retrieving Historical Metrics

Historical data enables you to build graphs, analyse trends, and perform capacity planning. Server Scout automatically provides data at appropriate resolutions based on your requested time range:

• Last 24 hours: Raw data points at original collection intervals (5-second, 30-second, 5-minute cycles)
• Up to 7 days: Averaged data to reduce response size whilst maintaining accuracy

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.serverscout.ie/api/servers/123/metrics/history?start=2024-01-14T00:00:00Z&end=2024-01-15T00:00:00Z"

Historical responses include arrays of timestamped data points:

{
  "metrics": {
    "cpu_usage": [
      {"timestamp": "2024-01-14T00:00:00Z", "value": 15.2},
      {"timestamp": "2024-01-14T00:05:00Z", "value": 18.7}
    ],
    "memory_used_percent": [
      {"timestamp": "2024-01-14T00:00:00Z", "value": 64.1},
      {"timestamp": "2024-01-14T00:05:00Z", "value": 65.3}
    ]
  }
}

Common Use Cases

External Dashboard Integration

Feed Server Scout metrics into Grafana, custom dashboards, or business intelligence tools for unified monitoring views.

Automated Reporting

Generate scheduled reports combining server metrics with business data, perfect for capacity planning presentations or SLA reporting.

Capacity Planning Scripts

Build automated scripts that analyse historical trends to predict when servers will need upgrades or additional resources.

Internal Monitoring Integration

Incorporate Server Scout data into existing monitoring workflows, alerting systems, or ITSM platforms.

Example Workflow

1. Authenticate and get server list:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.serverscout.ie/api/servers

1. Extract server IDs from the response to identify which servers you want to monitor

1. Request metrics for specific servers using the endpoints shown above

Best Practices

Use appropriate time ranges: Requesting months of raw data creates unnecessarily large responses. Utilise the automatic averaging for longer periods.

Cache responses sensibly: If you're building dashboards, cache current metrics for at least 30 seconds to avoid excessive API calls.

Respect rate limits: The API includes reasonable rate limiting to ensure fair usage. Space out your requests appropriately.

Handle timestamps properly: All timestamps use ISO 8601 format in UTC. Convert to your local timezone as needed for display.

The API provides identical data to what you see in the Server Scout dashboard, ensuring consistency across all your monitoring tools and custom integrations.