Overview
Health check endpoint to verify the API is operational and all core services are running properly. This endpoint does not require authentication.
Authentication
No authentication required - This endpoint is publicly accessible for health monitoring.
Response
Overall system status Values:
healthy - All systems operational
degraded - Some non-critical issues
unhealthy - Critical services down
ISO 8601 timestamp of the health check
Status of individual services
Services Object
Database database status (up or down)
Redis cache status (up or down)
RabbitMQ message queue status (up or down)
Worker availability information
Example Request
curl https://spideriq.di-atomic.com/api/v1/system/health
Example Response
200 OK - Healthy
200 OK - Degraded
503 Service Unavailable
{
"status" : "healthy" ,
"timestamp" : "2025-10-27T10:30:45Z" ,
"version" : "1.0.0" ,
"services" : {
"database" : "up" ,
"redis" : "up" ,
"rabbitmq" : "up" ,
"workers" : {
"spider_site" : 4 ,
"spider_maps" : 2 ,
"total" : 6 ,
"available" : true
}
}
}
Status Codes
Status Code Meaning Description 200 OK System is healthy or degraded but operational 503 Service Unavailable Critical services are down
Use Cases
Application Health Check
Monitor API availability in your application:
import requests
import time
def wait_for_api_ready ( max_wait = 60 ):
"""Wait for API to be healthy before proceeding"""
url = "https://spideriq.di-atomic.com/api/v1/system/health"
start_time = time.time()
while time.time() - start_time < max_wait:
try :
response = requests.get(url, timeout = 5 )
data = response.json()
if data[ "status" ] == "healthy" :
print ( "API is healthy and ready" )
return True
elif data[ "status" ] == "degraded" :
print ( "API is degraded but operational" )
return True
else :
print ( f "API unhealthy: { data.get( 'issues' , []) } " )
time.sleep( 5 )
except Exception as e:
print ( f "Health check failed: { e } " )
time.sleep( 5 )
raise TimeoutError ( "API did not become healthy within timeout" )
# Usage
wait_for_api_ready()
Monitoring Script
Continuous monitoring for alerting systems:
import requests
import time
import smtplib
from email.message import EmailMessage
def monitor_health ( check_interval = 60 , alert_email = "admin@example.com" ):
"""Monitor API health and send alerts"""
url = "https://spideriq.di-atomic.com/api/v1/system/health"
last_status = None
while True :
try :
response = requests.get(url, timeout = 10 )
data = response.json()
current_status = data[ "status" ]
# Alert on status change
if last_status and current_status != last_status:
send_alert(
alert_email,
f "SpiderIQ status changed: { last_status } → { current_status } " ,
data
)
# Alert on unhealthy
if current_status == "unhealthy" :
send_alert(
alert_email,
"SpiderIQ is UNHEALTHY" ,
data
)
last_status = current_status
print ( f "[ { data[ 'timestamp' ] } ] Status: { current_status } " )
except Exception as e:
print ( f "Health check error: { e } " )
send_alert(alert_email, "SpiderIQ health check failed" , str (e))
time.sleep(check_interval)
def send_alert ( to_email , subject , body ):
"""Send email alert"""
# Implement your alerting logic
print ( f "ALERT: { subject } " )
Docker Healthcheck
Use in Docker Compose healthcheck:
healthcheck :
test : [ "CMD" , "curl" , "-f" , "https://spideriq.di-atomic.com/api/v1/system/health" ]
interval : 30s
timeout : 10s
retries : 3
start_period : 40s
Kubernetes Liveness Probe
Use as Kubernetes probe:
livenessProbe :
httpGet :
path : /api/v1/system/health
port : 3000
initialDelaySeconds : 30
periodSeconds : 10
timeoutSeconds : 5
failureThreshold : 3
Status Page Widget
Display on your status page:
async function updateStatusPage () {
try {
const response = await fetch (
'https://spideriq.di-atomic.com/api/v1/system/health'
);
const health = await response . json ();
// Update status indicator
const statusEl = document . getElementById ( 'api-status' );
statusEl . textContent = health . status . toUpperCase ();
statusEl . className = `status-badge status- ${ health . status } ` ;
// Update service indicators
document . getElementById ( 'db-status' ). textContent =
health . services . database === 'up' ? '✓' : '✗' ;
document . getElementById ( 'redis-status' ). textContent =
health . services . redis === 'up' ? '✓' : '✗' ;
document . getElementById ( 'workers-status' ). textContent =
` ${ health . services . workers . total } available` ;
// Show issues if any
if ( health . issues && health . issues . length > 0 ) {
const issuesEl = document . getElementById ( 'issues' );
issuesEl . innerHTML = health . issues . map ( i => `<li> ${ i } </li>` ). join ( '' );
}
} catch ( error ) {
console . error ( 'Failed to fetch health status:' , error );
document . getElementById ( 'api-status' ). textContent = 'UNKNOWN' ;
}
}
// Update every 30 seconds
setInterval ( updateStatusPage , 30000 );
updateStatusPage ();
Understanding Status Levels
Healthy
All core services are operational:
Database connected
Redis cache working
RabbitMQ queue available
Workers available to process jobs
Action: Normal operation
Degraded
API is functional but with reduced performance:
Redis cache may be down (slower responses)
Fewer workers available (slower processing)
Action: Monitor closely, consider reducing load
Unhealthy
Critical services are down:
RabbitMQ unavailable (cannot queue jobs)
No workers available (cannot process jobs)
Database connection lost
Action: Do not submit jobs, contact support
Monitoring Best Practices
Regular checks: Poll this endpoint every 30-60 seconds for production monitoring.
Timeout: Set a reasonable timeout (5-10s) for health checks to avoid hanging monitors.
Rate limits: This endpoint is exempt from rate limiting, but avoid excessive polling (< 10s intervals).