Health Checks

Automatically monitor your Supabase projects with scheduled health checks.

What Health Checks Monitor

• Container status - All containers running
• Service connectivity - Database, API, Auth accessible
• Resource usage - CPU, memory, disk
• Response times - API latency

Create Health Check Task

Via Web UI

1. Navigate to Tasks
2. Click New Task
3. Select type: Health Check
4. Configure:
   • Name: "Production Health Check"
   • Project: Select project
   • Schedule: Every 5 minutes
5. Click Create Task

Via API

curl -X POST https://supascale.example.com/api/v1/tasks \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Health Check",
    "enabled": true,
    "type": "health-check",
    "projectId": "production",
    "cronExpression": "*/5 * * * *",
    "timezone": "UTC",
    "healthCheckConfig": {
      "checkContainers": true,
      "checkConnectivity": true,
      "alertOnFailure": true
    }
  }'

Schedule Options

Health Check Configuration

What Gets Checked

Container Status

Verifies all project containers are:

• Running (not stopped/exited)
• Healthy (passing health checks)
• Not restarting repeatedly

Database Connectivity

Tests PostgreSQL connection:

SELECT 1;

API Accessibility

Tests REST API endpoint:

GET /rest/v1/

Auth Service

Tests authentication service health:

GET /auth/v1/health

Viewing Results

Via Web UI

1. Go to Tasks
2. Find the health check task
3. View Last Status and History

Via API

curl https://supascale.example.com/api/v1/tasks/task-123 \
  -H "X-API-Key: your-api-key"

Response:

{
  "id": "task-123",
  "name": "Production Health Check",
  "lastRun": "2026-01-19T12:00:00Z",
  "lastStatus": "success",
  "history": [
    {
      "executedAt": "2026-01-19T12:00:00Z",
      "status": "success",
      "duration": 2500,
      "result": {
        "containers": "healthy",
        "database": "connected",
        "api": "accessible"
      }
    }
  ]
}

Alerts

Email Notifications

Configure SMTP to receive alerts:

1. Set up SMTP in Supascale settings
2. Enable alertOnFailure in health check config
3. Set notification email in settings

Alert Contents

Failed health check alerts include:

• Project name
• Failure reason
• Container status details
• Timestamp

Run Health Check Manually

Trigger immediate check:

curl -X POST https://supascale.example.com/api/v1/tasks/task-123/run \
  -H "X-API-Key: your-api-key"

Best Practices

Frequency

• Production: Every 5 minutes
• Staging: Every 15-30 minutes
• Development: Hourly or as needed

Multiple Projects

Create separate health checks for each project:

• Allows different schedules
• Independent alerting
• Clearer history

Response to Failures

1. Automatic: Configure alerts
2. Manual: Investigate logs
3. Escalation: Define response procedures

Troubleshooting

Health Check Always Failing

1. Manually check project status
2. Review container logs
3. Verify network connectivity
4. Check project isn't stopped

No Alerts Received

1. Verify SMTP configuration
2. Check spam folder
3. Verify notification email is set
4. Test SMTP with manual email

False Positives

1. Increase check timeout
2. Verify network stability
3. Check for resource constraints
4. Consider reducing check frequency