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

Method	Endpoint	Description
GET	/api/v1/services/{id}/checks	Retrieve check history for a service

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

Parameter	Type	Required	Description
id	integer	Yes	The unique identifier of the service

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:

Field	Type	Description
timestamp	string	ISO 8601 timestamp of when the check was performed
probe	object	Information about the probe that performed the check
probe.hostname	string	Hostname of the probe server
probe.city	string	City where the probe is located
probe.country	string	Country where the probe is located
probe.isp	string	Internet service provider of the probe
response_time	number	Response time in milliseconds (ms)
status	string	Check status: success or error
error	string or null	Error message if check failed, otherwise null
status_code	number or null	HTTP status code (HTTP only) or null (PING)

HTTP Service Details

For HTTP/HTTPS services, the details object includes:

Field	Type	Description
remote_ip	string	IP address of the remote server
http_status_code	number	HTTP response status code
timing.namelookup	number	DNS lookup time in seconds
timing.connect	number	TCP connection time in seconds
timing.appconnect	number	SSL/TLS handshake time in seconds
timing.pretransfer	number	Time until transfer start in seconds
timing.starttransfer	number	Time to first byte in seconds
timing.total	number	Total request time in seconds
size_download	number	Response size in bytes
speed_download	number	Download speed in bytes per second

PING Service Details

For PING services, the details object includes:

Field	Type	Description
target	string	Target IP address or domain
resolved_ip	string	Resolved IP address if target was a domain
packet_loss	number	Packet loss percentage (0-100)
packets_sent	number	Number of packets sent
packets_received	number	Number of packets received
rtt.min	number	Minimum round-trip time in milliseconds
rtt.avg	number	Average round-trip time in milliseconds
rtt.max	number	Maximum round-trip time in milliseconds

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

Status Code	Description
200	Success - Check results retrieved successfully
401	Unauthorized - Invalid or missing authentication token
403	Forbidden - Service does not belong to authenticated user
404	Not Found - Service with specified ID does not exist
500	Internal Server Error - Server error occurred

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