> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pocketbase/pocketbase/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={null}
GET /api/health
```

**Authentication:** Optional (additional info for superusers)

### Response

<ResponseField name="code" type="number">
  HTTP status code (200)
</ResponseField>

<ResponseField name="message" type="string">
  Health status message ("API is healthy.")
</ResponseField>

<ResponseField name="data" type="object">
  Additional health information (varies by auth level)
</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl http://127.0.0.1:8090/api/health
  ```

  ```json Response (guest) theme={null}
  {
    "code": 200,
    "message": "API is healthy.",
    "data": {}
  }
  ```

  ```json Response (superuser) theme={null}
  {
    "code": 200,
    "message": "API is healthy.",
    "data": {
      "canBackup": true,
      "realIP": "192.168.1.100",
      "possibleProxyHeader": "X-Forwarded-For"
    }
  }
  ```
</CodeGroup>

## Superuser response fields

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

<ResponseField name="canBackup" type="boolean">
  Whether a backup operation can be started (no backup currently in progress)
</ResponseField>

<ResponseField name="realIP" type="string">
  The detected real IP address of the client
</ResponseField>

<ResponseField name="possibleProxyHeader" type="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`)
</ResponseField>

## Use cases

### Basic health monitoring

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

```bash theme={null}
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:

```yaml theme={null}
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:

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

### Kubernetes liveness probe

```yaml theme={null}
livenessProbe:
  httpGet:
    path: /api/health
    port: 8090
  initialDelaySeconds: 5
  periodSeconds: 10
```

### Monitoring scripts

```bash theme={null}
#!/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      |

<Note>
  The health endpoint always returns 200 OK if the server is running. It doesn't check database connectivity or other subsystems.
</Note>

## 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

<Warning>
  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
</Warning>

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

## Example monitoring setup

### Simple uptime monitor

```javascript theme={null}
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

```javascript theme={null}
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();
```