Skip to main content

Health Check

GET/api/v1/system/health

Overview​

Health check endpoint to verify the API is operational and all core services are running properly. This endpoint does not require authentication.

Authentication​

info

No authentication required - This endpoint is publicly accessible for health monitoring.

Response​

statusstring

Overall system status

Values:

  • healthy - All systems operational
  • degraded - Some non-critical issues
  • unhealthy - Critical services down
timestampstring

ISO 8601 timestamp of the health check

versionstring

Current API version

servicesobject

Status of individual services

Services Object​

services.databasestring

Database database status (up or down)

services.redisstring

Redis cache status (up or down)

services.rabbitmqstring

RabbitMQ message queue status (up or down)

services.workersobject

Worker availability information

Example Request​

curl https://spideriq.ai/api/v1/system/health

Example Response​

{
  "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 CodeMeaningDescription
200OKSystem is healthy or degraded but operational
503Service UnavailableCritical 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.ai/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.ai/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.ai/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.ai/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​

tip

Regular checks: Poll this endpoint every 30-60 seconds for production monitoring.

tip

Timeout: Set a reasonable timeout (5-10s) for health checks to avoid hanging monitors.

warning

Rate limits: This endpoint is exempt from rate limiting, but avoid excessive polling (< 10s intervals).

📈

Queue Stats

View queue statistics

🖥️

System Info

Get system information

📨

Submit Job

Submit a scraping job

📋

List Jobs

View all your jobs