Service Checks API

Overview

The Service Checks API provides access to historical monitoring check results for your services. Check results are collected by UptimeHunt's global network of probes and stored for analysis and visualization.

Endpoint Summary

Authentication

All API requests require authentication using a JWT Bearer token in the Authorization header:

Authorization: Bearer <your_access_token>

See the Authentication API documentation for details on obtaining access tokens.

Get Service Checks

Retrieve recent check results for a specific service.

Endpoint

GET /api/v1/services/{id}/checks

Parameters

Path Parameters

Query Parameters

Currently, the API returns the most recent 30 checks from the last 24 hours. Pagination and filtering parameters are planned for future releases.

Response

Returns a JSON object containing an array of check results and metadata.

Response Structure

{
  "data": [
    {
      "timestamp": "2024-01-15T14:30:00.000Z",
      "probe": {
        "hostname": "probe-nyc-01",
        "city": "New York",
        "country": "United States",
        "isp": "DigitalOcean"
      },
      "response_time": 245.5,
      "status": "success",
      "error": null,
      "status_code": 200,
      "details": {
        "remote_ip": "93.184.216.34",
        "http_status_code": 200,
        "timing": {
          "namelookup": 0.045,
          "connect": 0.089,
          "appconnect": 0.156,
          "pretransfer": 0.157,
          "starttransfer": 0.243,
          "total": 0.245
        },
        "size_download": 1256,
        "speed_download": 5120.5
      }
    }
  ],
  "meta": {
    "total": 30,
    "service_id": 123,
    "service_name": "Production API"
  }
}

Check Result Schema

Common Fields

All check results include these fields regardless of service type:

HTTP Service Details

For HTTP/HTTPS services, the details object includes:

PING Service Details

For PING services, the details object includes:

Examples

cURL Example

curl -X GET "https://api.uptimehunt.com/api/v1/services/123/checks" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

HTTP Service Check - Success

{
  "data": [
    {
      "timestamp": "2024-01-15T14:30:00.000Z",
      "probe": {
        "hostname": "probe-nyc-01",
        "city": "New York",
        "country": "United States",
        "isp": "DigitalOcean"
      },
      "response_time": 245.5,
      "status": "success",
      "error": null,
      "status_code": 200,
      "details": {
        "remote_ip": "93.184.216.34",
        "http_status_code": 200,
        "timing": {
          "namelookup": 0.045,
          "connect": 0.089,
          "appconnect": 0.156,
          "pretransfer": 0.157,
          "starttransfer": 0.243,
          "total": 0.245
        },
        "size_download": 1256,
        "speed_download": 5120.5
      }
    }
  ],
  "meta": {
    "total": 1,
    "service_id": 123,
    "service_name": "Production API"
  }
}

HTTP Service Check - Error

{
  "data": [
    {
      "timestamp": "2024-01-15T14:35:00.000Z",
      "probe": {
        "hostname": "probe-lon-01",
        "city": "London",
        "country": "United Kingdom",
        "isp": "AWS"
      },
      "response_time": null,
      "status": "error",
      "error": "Connection timeout after 10 seconds",
      "status_code": null,
      "details": {
        "remote_ip": null,
        "http_status_code": null,
        "timing": {
          "namelookup": null,
          "connect": null,
          "appconnect": null,
          "pretransfer": null,
          "starttransfer": null,
          "total": null
        },
        "size_download": null,
        "speed_download": null
      }
    }
  ],
  "meta": {
    "total": 1,
    "service_id": 123,
    "service_name": "Production API"
  }
}

PING Service Check - Success

{
  "data": [
    {
      "timestamp": "2024-01-15T14:30:00.000Z",
      "probe": {
        "hostname": "probe-fra-01",
        "city": "Frankfurt",
        "country": "Germany",
        "isp": "Hetzner"
      },
      "response_time": 23.5,
      "status": "success",
      "error": null,
      "status_code": null,
      "details": {
        "target": "example.com",
        "resolved_ip": "93.184.216.34",
        "packet_loss": 0,
        "packets_sent": 4,
        "packets_received": 4,
        "rtt": {
          "min": 22.1,
          "avg": 23.5,
          "max": 25.3
        }
      }
    }
  ],
  "meta": {
    "total": 1,
    "service_id": 124,
    "service_name": "Production Server"
  }
}

PING Service Check - Failure

{
  "data": [
    {
      "timestamp": "2024-01-15T14:35:00.000Z",
      "probe": {
        "hostname": "probe-syd-01",
        "city": "Sydney",
        "country": "Australia",
        "isp": "Vultr"
      },
      "response_time": null,
      "status": "error",
      "error": "Request timeout for icmp_seq 0",
      "status_code": null,
      "details": {
        "target": "192.168.1.100",
        "resolved_ip": "192.168.1.100",
        "packet_loss": 100,
        "packets_sent": 4,
        "packets_received": 0,
        "rtt": {
          "min": null,
          "avg": null,
          "max": null
        }
      }
    }
  ],
  "meta": {
    "total": 1,
    "service_id": 124,
    "service_name": "Production Server"
  }
}

HTTP Status Codes

Interpreting Check Results

Success Checks

A successful check has:

• status: "success"
• error: null
• Valid response_time value
• For HTTP: status_code in the 200-399 range
• For PING: packet_loss of 0%

Failed Checks

A failed check has:

• status: "error"
• error: Contains error message describing the failure
• response_time: Usually null
• Details fields may be null depending on failure type

Common Error Messages

HTTP Errors

• "Connection timeout after 10 seconds" - Server did not respond in time
• "Connection refused" - Server actively rejected the connection
• "Name resolution failed" - DNS lookup failed for the domain
• "SSL certificate verification failed" - Invalid or expired SSL certificate
• "HTTP 500 Internal Server Error" - Server returned an error status

PING Errors

• "Request timeout for icmp_seq X" - No response received for packet
• "Host unreachable" - Network routing failure
• "Permission denied" - ICMP permission issue on probe
• "Name resolution failed" - Cannot resolve domain to IP

Response Time Analysis

HTTP Response Times

• Response time is measured in milliseconds (ms)
• Converted from total timing value (seconds × 1000)
• Includes complete request lifecycle from DNS to download
• Typical values: 50-500ms for most websites
• Values >1000ms indicate performance issues

PING Response Times

• Response time represents average RTT (round-trip time)
• Measured in milliseconds (ms)
• Based on 4 ICMP echo requests by default
• Typical values: <50ms local, <200ms international
• Includes network latency only, not application processing

Probe Location Impact

Check results vary by probe location due to:

• Geographic Distance: Farther probes show higher latency
• Network Routing: Different paths through the internet
• ISP Performance: Varies by provider and peering agreements
• Regional Issues: Localized network problems or filtering

Use results from multiple probes to get a complete picture of service availability and performance across different regions.

Data Retention

Check results are currently stored for:

• Last 24 Hours: Full resolution (all checks)
• Aggregation: Historical data aggregation planned for future releases

Pagination and Filtering

Current Implementation

• Returns most recent 30 checks
• Time window: Last 24 hours
• Ordered by timestamp (newest first)

Planned Features

• limit parameter: Control number of results (1-100)
• offset parameter: Pagination support
• start_date parameter: Filter by start date
• end_date parameter: Filter by end date
• probe_id parameter: Filter by specific probe
• status parameter: Filter by success/error status

Best Practices

Efficient Data Retrieval

1. Cache Results: Cache check data on your side for dashboards
2. Polling Interval: Don't poll more frequently than your check interval
3. Batch Processing: Process multiple services in parallel
4. Time Windows: Focus on relevant time periods

Monitoring Integration

1. Webhook Alternative: Use webhooks for real-time alerts instead of polling
2. Aggregate Data: Calculate averages and percentiles locally
3. Anomaly Detection: Look for patterns across multiple checks
4. Multi-Region Analysis: Compare results across different probe locations

Performance Considerations

1. Response Size: Each check includes detailed timing data
2. Historical Data: Limit queries to necessary time ranges
3. Real-time Needs: Use WebSocket connections for live updates (planned)

Related Endpoints

• Services API - Manage monitoring services
• Projects API - Organize services into projects
• Authentication API - Obtain access tokens

Troubleshooting

No Check Results

If the API returns empty check data:

1. Verify the service is enabled
2. Check that the service interval has elapsed
3. Confirm the service has been active for at least one interval
4. Ensure your service is correctly configured

Missing Probe Information

If probe details are null:

• Probe data is being migrated or updated
• Legacy checks may not have probe metadata
• Contact support if issue persists

Inconsistent Response Times

Variations in response time are normal due to:

• Network conditions at time of check
• Server load during the check
• Geographic distance between probe and target
• Internet routing changes

Compare multiple checks over time for accurate performance assessment.

Support

For API support and questions:

• Documentation: https://docs.uptimehunt.com
• Support Email: support@uptimehunt.com
• API Status: https://status.uptimehunt.com