Health Endpoints

World Monitor exposes two health endpoints for monitoring data pipeline integrity. Both run on the Vercel Edge Runtime and query Redis (Upstash) to assess system state.

/api/health

Primary health endpoint. Checks all Redis-backed data keys and seed freshness metadata in a single pipeline call.

Authentication: None required. Open to all origins (Access-Control-Allow-Origin: *).

HTTP Method: GET

Query Parameters

Parameter	Values	Description
compact	1	Omit per-key details; only return keys with problems

Response Status Codes

HTTP Status	Overall Status	Meaning
200	HEALTHY	All checks OK, no warnings
200	WARNING	Some keys stale or on-demand keys empty, but no critical failures
503	DEGRADED	1-3 bootstrap keys empty
503	UNHEALTHY	4+ bootstrap keys empty
503	REDIS_DOWN	Could not connect to Redis

Response Body

{
  "status": "HEALTHY | WARNING | DEGRADED | UNHEALTHY | REDIS_DOWN",
  "summary": {
    "total": 57,
    "ok": 52,
    "warn": 5,
    "crit": 0
  },
  "checkedAt": "2026-03-11T14:00:00.000Z",
  "checks": {
    "earthquakes": {
      "status": "OK",
      "records": 142,
      "seedAgeMin": 8,
      "maxStaleMin": 30
    }
  }
}

With ?compact=1, the checks object is replaced by problems containing only non-OK keys.

Key Classifications

Keys are grouped into three tiers that determine alert severity:

Tier	Severity when empty	Description
Bootstrap	CRIT	Seeded data required at startup. Empty means the dashboard is missing critical data
Standalone	CRIT (seeded) / WARN (on-demand)	Populated by seed loops or RPC handlers. On-demand keys are expected to be empty until first request
On-demand	WARN	Populated lazily by RPC calls. Empty is normal if nobody has requested the data yet

Per-Key Statuses

Status	Severity	Meaning
OK	Green	Data present, seed fresh
OK_CASCADE	Green	Key empty but a sibling in the cascade group has data (e.g., theater posture fallback chain)
STALE_SEED	Warn	Data present but seed-meta age exceeds maxStaleMin
EMPTY_ON_DEMAND	Warn	On-demand key has no data yet
EMPTY	Crit	Bootstrap or standalone key has no data
EMPTY_DATA	Crit	Key exists but contains zero records

Cascade Groups

Some keys use fallback chains. If any sibling has data, empty siblings report OK_CASCADE:

• Theater Posture: theaterPostureLive -> theaterPosture (stale) -> theaterPostureBackup
• Military Flights: militaryFlights -> militaryFlightsStale

Staleness Thresholds (maxStaleMin)

Selected thresholds from SEED_META:

Domain	Max Stale (min)	Notes
Market quotes, crypto, sectors	30	High-frequency relay loops
Earthquakes, unrest, insights	30	Critical event data
Predictions	15	Polymarket, fast-moving
Military flights	15	Near-real-time tracking
Flight delays (FAA)	60	Airport delay snapshots
Wildfires, climate anomalies	120	Slower-moving natural events
Cyber threats	480	APT data updated less frequently
BIS data, World Bank, minerals	2880-10080	Institutional data, weekly/monthly updates

Example Requests

# Full health check
curl -s https://api.worldmonitor.app/api/health | jq .

# Compact (problems only)
curl -s "https://api.worldmonitor.app/api/health?compact=1" | jq .

# UptimeRobot / monitoring: check HTTP status code
curl -o /dev/null -s -w "%{http_code}" https://api.worldmonitor.app/api/health
# Returns 200 (healthy/warning) or 503 (degraded/unhealthy)

/api/seed-health

Focused endpoint for seed loop freshness. Checks only seed-meta:* keys without fetching actual data payloads.

Authentication: Requires valid API key or allowed origin.

HTTP Method: GET

Response Status Codes

HTTP Status	Overall Status	Meaning
200	healthy	All seed loops reporting on time
200	warning	Some seeds stale (age > 2x interval)
200	degraded	Some seeds missing entirely
401	-	Invalid or missing API key
503	-	Redis unavailable

Response Body

{
  "overall": "healthy | warning | degraded",
  "checkedAt": 1710158400000,
  "seeds": {
    "seismology:earthquakes": {
      "status": "ok",
      "fetchedAt": 1710158100000,
      "recordCount": 142,
      "sourceVersion": null,
      "ageMinutes": 5,
      "stale": false
    },
    "market:stocks": {
      "status": "stale",
      "fetchedAt": 1710150000000,
      "recordCount": 85,
      "sourceVersion": null,
      "ageMinutes": 140,
      "stale": true
    }
  }
}

Staleness Logic

A seed is considered stale when its age exceeds 2x the configured interval. This accounts for normal jitter in cron/relay timing.

Domain	Interval (min)	Stale After (min)
Predictions, military flights	8	16
Market quotes, earthquakes, unrest	15	30
ETF flows, stablecoins, chokepoints	30	60
Service statuses, spending, wildfires	60	120
Shipping rates, satellites	90-120	180-240
GPS jamming, displacement	360	720
Iran events, UCDP	210-5040	420-10080

Example Request

curl -s https://api.worldmonitor.app/api/seed-health \
  -H "Origin: https://worldmonitor.app" | jq .

Integration with Monitoring Tools

UptimeRobot

Use /api/health as the monitor URL. UptimeRobot checks HTTP status:

• 200 = up
• 503 = down

For keyword monitoring, check for "status":"HEALTHY" in the response body.

Custom Alerting

Parse the JSON response to build granular alerts:

# Alert on any critical keys
STATUS=$(curl -s "https://api.worldmonitor.app/api/health?compact=1")
CRIT=$(echo "$STATUS" | jq '.summary.crit')
if [ "$CRIT" -gt 0 ]; then
  echo "CRITICAL: $CRIT data keys empty"
  echo "$STATUS" | jq '.problems'
fi

Differences Between Endpoints

Aspect	/api/health	/api/seed-health
Scope	Data keys + seed metadata	Seed metadata only
Auth	None (public)	API key or allowed origin
Data fetched	Full Redis values (to count records)	Only seed-meta:* keys
HTTP 503	Yes (DEGRADED/UNHEALTHY)	No (always 200 unless Redis down)
Best for	Uptime monitoring, dashboard health	Debugging seed loop issues
Response size	Larger (57+ keys with record counts)	Smaller (42 seed domains)