Skip to main content

​
Overview

Retrieve comprehensive aggregated statistics for all monitors in your organization, or detailed metrics for a specific monitor. Statistics include uptime percentage, response times, check counts, and incident information.

​
Authentication

All requests must include authentication via:
  • API Key: X-API-Key: YOUR_API_KEY

​
Endpoints

​
Organization Statistics

GET /api/monitors/stats
Get aggregated statistics across all monitors.

​
Individual Monitor Statistics

GET /api/monitors/{id}/stats?period=30d
Get detailed statistics for a specific monitor.

​
Query Parameters

ParameterTypeDefaultDescription
periodenum30dTime period: 7d, 30d, 90d

​
Period Options

PeriodDaysUse Case
7d7Weekly trends, recent performance
30d30Monthly reports, plan evaluation
90d90Quarterly reviews, SLA tracking

​
Organization Statistics Response

​
Success Response (200 OK)

{
  "success": true,
  "data": {
    "total_monitors": 42,
    "by_type": {
      "HTTP": 25,
      "DNS": 8,
      "TCP": 5,
      "ICMP": 3,
      "KEYWORD": 1,
      "HEARTBEAT": 0
    },
    "by_status": {
      "active": 38,
      "paused": 3,
      "disabled": 1
    },
    "by_region": {
      "asia": 15,
      "europe": 20,
      "north-america": 12,
      "oceania": 5
    },
    "recent_activity": [
      {
        "id": "mon_1234567890abcdef",
        "name": "Production API",
        "type": "HTTP",
        "status": "operational",
        "last_check_at": 1703610300000,
        "uptime_percentage": 99.97
      },
      {
        "id": "mon_2234567890abcdef",
        "name": "Database Server",
        "type": "TCP",
        "status": "degraded",
        "last_check_at": 1703610240000,
        "uptime_percentage": 98.50
      }
    ]
  }
}

​
Individual Monitor Statistics Response

​
Success Response (200 OK)

{
  "success": true,
  "data": {
    "uptime_percentage": 99.97,
    "avg_response_time": 245,
    "total_checks": 8640,
    "failed_checks": 2,
    "last_check_at": 1703610300000,
    "last_failure_at": 1703540600000,
    "last_success_at": 1703610300000,
    "current_incident": {
      "id": "inc_1234567890abcdef",
      "started_at": "2024-12-25T14:30:00Z",
      "downtime_minutes": 45,
      "status": "open",
      "severity": "critical"
    }
  }
}

​
Without Current Incident

{
  "success": true,
  "data": {
    "uptime_percentage": 100.0,
    "avg_response_time": 189,
    "total_checks": 8640,
    "failed_checks": 0,
    "last_check_at": 1703610300000,
    "last_failure_at": null,
    "last_success_at": 1703610300000,
    "current_incident": null
  }
}

​
Response Fields

​
Organization Statistics

FieldTypeDescription
total_monitorsnumberTotal number of monitors in organization
by_typeobjectCount of monitors by type
by_statusobjectCount of monitors by status
by_regionobjectCount of monitors by region
recent_activityarrayRecent monitor activity snapshots

​
Monitor Statistics

FieldTypeDescription
uptime_percentagenumberUptime percentage (0-100) for the period
avg_response_timenumberAverage response time in milliseconds
total_checksnumberTotal number of checks executed
failed_checksnumberNumber of failed checks
last_check_atnumberUnix timestamp of last check (milliseconds)
last_failure_atnumberUnix timestamp in milliseconds of last failure or null
last_success_atnumberUnix timestamp in milliseconds of last success or null
current_incidentobjectActive incident details or null

​
Current Incident Fields

FieldTypeDescription
idstringIncident UUID
started_atstringISO 8601 timestamp when incident started
downtime_minutesnumberMinutes since incident started
statusenumIncident status: open, acknowledged
severityenumSeverity: critical, major, minor, warning

​
Period-Specific Behavior

​
7-Day Period

  • Shows recent performance trends
  • Useful for identifying recent issues
  • Includes last 7 days of check results

​
30-Day Period

  • Standard monthly reporting period
  • Used for SLA calculations
  • Captures 4+ week trends

​
90-Day Period

  • Quarterly review period
  • Long-term performance analysis
  • Trend identification

​
Example Calculations

​
Uptime Percentage

Uptime % = (Total Checks - Failed Checks) / Total Checks * 100

Example:
Total Checks: 8640 (every 30 seconds for 30 days)
Failed Checks: 2
Uptime: (8640 - 2) / 8640 * 100 = 99.977%

​
Average Response Time

Average Response Time = Sum of all response times / Total successful checks

Example:
If 8638 successful checks with total 2,117,110ms of response time:
Average: 2,117,110ms / 8638 = 245ms

​
Error Codes

CodeStatusDescription
INVALID_MONITOR_ID400Missing or invalid monitor ID
INVALID_PERIOD400Period must be one of: 7d, 30d, 90d
AUTHENTICATION_REQUIRED401Missing or invalid authentication
STATS_NOT_FOUND404Monitor not found or access denied
STATS_FETCH_FAILED500Failed to retrieve statistics

​
Examples

# Get organization statistics
curl -X GET https://api.uptimeio.com/api/monitors/stats \
  -H "X-API-Key: YOUR_API_KEY"

# Get monitor statistics for 30 days (default)
curl -X GET https://api.uptimeio.com/api/monitors/mon_1234567890abcdef/stats \
  -H "X-API-Key: YOUR_API_KEY"

# Get monitor statistics for 7 days
curl -X GET https://api.uptimeio.com/api/monitors/mon_1234567890abcdef/stats?period=7d \
  -H "X-API-Key: YOUR_API_KEY"

# Get quarterly statistics
curl -X GET https://api.uptimeio.com/api/monitors/mon_1234567890abcdef/stats?period=90d \
  -H "X-API-Key: YOUR_API_KEY"

​
Caching Considerations

Monitor statistics are cached for performance:
  • Cache Duration: Typically 60 seconds
  • Real-Time Data: Recent checks may not appear immediately
  • Historical Consistency: Older data remains consistent
For real-time metrics, consider polling every 60+ seconds.