Monitor Website Uptime with HTTP Probes

The Uptime Monitor service sends periodic HTTP probes to your endpoints and tracks their availability. Get notified when a site goes down, see response time trends, and calculate SLA percentages.

What You'll Learn

  • How to create a monitoring target with custom check intervals
  • How to view current status and response time
  • How to retrieve check history and understand UP/DOWN transitions

Prerequisites

Before you start: You need an API key. Follow the Platform Quick Start to get one.

  • curl (or any HTTP client)
  • A valid API key in the X-API-KEY header

Step 1: Create a Monitoring Target

Register a URL for monitoring. Specify the check interval, expected status code, and timeout.

bash
curl -X POST /api/uptime-monitor/targets \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key" \
  -d '{
    "name": "Production API",
    "url": "https://api.mycompany.com/health",
    "intervalSeconds": 60,
    "timeoutMs": 5000,
    "expectedStatus": 200
  }'
python
import requests

resp = requests.post(
    "/api/uptime-monitor/targets",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "name": "Production API",
        "url": "https://api.mycompany.com/health",
        "intervalSeconds": 60,
        "timeoutMs": 5000,
        "expectedStatus": 200
    }
)
target = resp.json()["data"]
print(f"Target ID: {target['targetId']}")
Response — 201 Created
{
  "status": "OK",
  "data": {
    "targetId": "tgt_a1b2c3d4",
    "name": "Production API",
    "url": "https://api.mycompany.com/health",
    "intervalSeconds": 60,
    "state": "PENDING",
    "createdAt": "2026-03-26T16:00:00Z"
  }
}

Step 2: View Current Status

After the first check runs, query the target to see its current state.

bash
curl -X GET "/api/uptime-monitor/targets/tgt_a1b2c3d4" \
  -H "X-API-KEY: your-api-key"
Response — 200 OK
{
  "status": "OK",
  "data": {
    "targetId": "tgt_a1b2c3d4",
    "name": "Production API",
    "state": "UP",
    "lastCheckedAt": "2026-03-26T16:01:00Z",
    "lastResponseMs": 142,
    "lastStatusCode": 200,
    "uptimePercent": 100.0,
    "totalChecks": 1
  }
}

Step 3: Check History

Retrieve the last N checks to see response time trends and any failures.

bash
curl -X GET "/api/uptime-monitor/targets/tgt_a1b2c3d4/history?limit=5" \
  -H "X-API-KEY: your-api-key"
Response — 200 OK
{
  "status": "OK",
  "data": {
    "checks": [
      { "checkedAt": "2026-03-26T16:05:00Z", "state": "UP",   "responseMs": 138, "statusCode": 200 },
      { "checkedAt": "2026-03-26T16:04:00Z", "state": "UP",   "responseMs": 145, "statusCode": 200 },
      { "checkedAt": "2026-03-26T16:03:00Z", "state": "DOWN", "responseMs": 5001, "statusCode": 0 },
      { "checkedAt": "2026-03-26T16:02:00Z", "state": "UP",   "responseMs": 151, "statusCode": 200 },
      { "checkedAt": "2026-03-26T16:01:00Z", "state": "UP",   "responseMs": 142, "statusCode": 200 }
    ]
  }
}

Step 4: Understanding UP/DOWN Transitions

A target transitions from UP to DOWN after consecutive failures (configurable via confirmations). This prevents a single timeout from triggering false alerts.

State machine: PENDING → first check → UP or DOWN. Transitions between UP and DOWN require confirmations consecutive results (default: 2).

  • statusCode: 0 means the request timed out or DNS resolution failed.
  • responseMs exceeding timeoutMs is counted as a failure.
  • Any status code other than expectedStatus is counted as a failure.

Integration Tips

  • Slack/PagerDuty alerts: Use the webhookUrl field on the target to receive instant DOWN notifications.
  • SLA dashboards: The uptimePercent field calculates availability over the monitoring window.
  • Multi-region: Create the same target in multiple regions to distinguish local outages from global ones.
  • Health endpoints: Monitor /health or /actuator/health rather than homepage URLs for more reliable signals.

Next Steps