Health

Check API health and system status

The Health API provides a simple endpoint to check if the PocketBase API is running and healthy.

Health check

Check the health status of the API.

GET /api/health

Authentication: Optional (additional info for superusers)

Response

code · number

HTTP status code (200)

message · string

Health status message (“API is healthy.”)

data · object

Additional health information (varies by auth level)

curl

curl http://127.0.0.1:8090/api/health

Superuser response fields

When authenticated as a superuser, the response includes additional diagnostic information:

canBackup · boolean

Whether a backup operation can be started (no backup currently in progress)

realIP · string

The detected real IP address of the client

possibleProxyHeader · string

The header used to determine the client’s IP, if behind a proxy (e.g., X-Forwarded-For, CF-Connecting-IP, Fly-Client-IP)

Use cases

Basic health monitoring

Use this endpoint to monitor if your PocketBase instance is running:

curl -f http://127.0.0.1:8090/api/health || echo "API is down"

Load balancer health checks

Configure your load balancer to use /api/health as the health check endpoint:

health_check:
  path: /api/health
  interval: 10s
  timeout: 5s
  healthy_threshold: 2
  unhealthy_threshold: 3

Docker health checks

Add a health check to your Docker configuration:

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:8090/api/health || exit 1

Kubernetes liveness probe

livenessProbe:
  httpGet:
    path: /api/health
    port: 8090
  initialDelaySeconds: 5
  periodSeconds: 10

Monitoring scripts

#!/bin/bash

RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8090/api/health)

if [ $RESPONSE -eq 200 ]; then
  echo "✓ API is healthy"
  exit 0
else
  echo "✗ API is unhealthy (HTTP $RESPONSE)"
  exit 1
fi

Response codes

Code	Status	Description
200	OK	API is healthy and responding
500	Error	API encountered an error

The health endpoint always returns 200 OK if the server is running. It doesn’t check database connectivity or other subsystems.

Proxy detection

For superusers, the endpoint checks common reverse proxy headers to help identify if the application is deployed behind a proxy:

• X-Forwarded-For
• CF-Connecting-IP (Cloudflare)
• Fly-Client-IP (Fly.io)
• Custom headers from TrustedProxy.Headers settings

This helps diagnose IP-related issues when using features like rate limiting or geo-based access control.

Performance

The health endpoint is lightweight and doesn’t perform any database queries. It’s safe to call frequently for monitoring purposes.

Typical response time: < 1ms

Best practices

1. Use for uptime monitoring - Regularly ping this endpoint to detect outages
2. Set appropriate timeouts - Configure health check timeouts (3-5 seconds recommended)
3. Don’t authenticate - Use as an unauthenticated endpoint for public monitoring
4. Combine with deep checks - For critical systems, supplement with database connectivity tests

Limitations

The health endpoint only verifies that the HTTP server is responding. It does not check:

• Database connectivity
• Storage system availability
• Background job status
• Memory or disk space

For comprehensive health monitoring, consider implementing custom health checks that test critical subsystems.

Example monitoring setup

Simple uptime monitor

const axios = require('axios');

setInterval(async () => {
  try {
    const response = await axios.get('http://127.0.0.1:8090/api/health', {
      timeout: 3000
    });
    
    if (response.status === 200) {
      console.log('✓ API healthy');
    }
  } catch (error) {
    console.error('✗ API unhealthy:', error.message);
    // Send alert notification
  }
}, 30000); // Check every 30 seconds

Advanced monitoring with superuser info

const axios = require('axios');

const checkHealth = async () => {
  try {
    const response = await axios.get('http://127.0.0.1:8090/api/health', {
      headers: {
        'Authorization': `Bearer ${superuserToken}`
      },
      timeout: 3000
    });
    
    const { canBackup, realIP, possibleProxyHeader } = response.data.data;
    
    console.log(`Health: OK`);
    console.log(`Can Backup: ${canBackup}`);
    console.log(`Real IP: ${realIP}`);
    console.log(`Proxy Header: ${possibleProxyHeader || 'none'}`);
    
    return true;
  } catch (error) {
    console.error('Health check failed:', error.message);
    return false;
  }
};

checkHealth();