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

# Health Check

> System status and readiness verification endpoint

## Overview

The Health Check endpoint allows UserTrace to verify that your agent is operational and ready to handle test requests. This endpoint is called before starting simulations to ensure system readiness.

## Endpoint

```
GET /health
```

## Request Headers

```http theme={null}
Accept: application/json
```

<Note>
  Authentication is not required for health check endpoints as they only provide basic status information.
</Note>

## Request

Simple GET request with no body required:

```bash theme={null}
curl -X GET https://your-sandbox.com/health
```

## Response Format

<ParamField body="status" type="string" required>
  Overall system status. Values: `healthy`, `unhealthy`, `degraded`
</ParamField>

<ParamField body="timestamp" type="string" required>
  ISO 8601 timestamp when the health check was performed
</ParamField>

<ParamField body="version" type="string">
  Current version of your agent or API
</ParamField>

<ParamField body="uptime" type="integer">
  System uptime in seconds (optional)
</ParamField>

<ParamField body="dependencies" type="object">
  Status of external dependencies (optional)

  <Expandable title="Dependencies Object">
    <ParamField body="database" type="string">
      Database connection status: `healthy`, `unhealthy`
    </ParamField>

    <ParamField body="llm_service" type="string">
      LLM service status: `healthy`, `unhealthy`
    </ParamField>

    <ParamField body="external_apis" type="string">
      External API status: `healthy`, `unhealthy`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="metrics" type="object">
  System performance metrics (optional)

  <Expandable title="Metrics Object">
    <ParamField body="response_time_avg" type="number">
      Average response time in milliseconds
    </ParamField>

    <ParamField body="error_rate" type="number">
      Error rate as a percentage (0-100)
    </ParamField>

    <ParamField body="memory_usage" type="number">
      Memory usage as a percentage (0-100)
    </ParamField>

    <ParamField body="cpu_usage" type="number">
      CPU usage as a percentage (0-100)
    </ParamField>
  </Expandable>
</ParamField>

## Response Examples

### Healthy System

```json theme={null}
{
  "status": "healthy",
  "timestamp": "2024-01-21T10:30:00Z",
  "version": "1.0.0",
  "uptime": 3600,
  "dependencies": {
    "database": "healthy",
    "llm_service": "healthy",
    "external_apis": "healthy"
  },
  "metrics": {
    "response_time_avg": 250,
    "error_rate": 0.1,
    "memory_usage": 45,
    "cpu_usage": 30
  }
}
```

### Degraded System

```json theme={null}
{
  "status": "degraded",
  "timestamp": "2024-01-21T10:30:00Z",
  "version": "1.0.0",
  "uptime": 7200,
  "dependencies": {
    "database": "healthy",
    "llm_service": "healthy",
    "external_apis": "unhealthy"
  },
  "metrics": {
    "response_time_avg": 800,
    "error_rate": 5.2,
    "memory_usage": 78,
    "cpu_usage": 85
  }
}
```

### Minimal Response

```json theme={null}
{
  "status": "healthy",
  "timestamp": "2024-01-21T10:30:00Z",
  "version": "1.0.0"
}
```

## Status Codes

| HTTP Status | Status Value | Description                                       |
| ----------- | ------------ | ------------------------------------------------- |
| 200         | `healthy`    | System is fully operational                       |
| 200         | `degraded`   | System is operational but performance is impacted |
| 503         | `unhealthy`  | System is not operational                         |

## Error Responses

### Service Unavailable (503)

```json theme={null}
{
  "status": "unhealthy",
  "timestamp": "2024-01-21T10:30:00Z",
  "version": "1.0.0",
  "error": {
    "message": "Database connection failed",
    "details": "Unable to connect to primary database"
  }
}
```

### Network Issues (500)

```json theme={null}
{
  "error": {
    "message": "Health check service unavailable",
    "type": "internal_error",
    "code": "health_check_failed"
  }
}
```

## Implementation Guidelines

### Health Check Logic

Your health check should verify:

1. **Basic Connectivity**: Server is responding to requests
2. **Dependencies**: Database, LLM services, external APIs
3. **Resources**: Memory, CPU, disk space within acceptable limits
4. **Configuration**: Required environment variables and settings

### Response Time

* Health checks should respond within **2 seconds**
* UserTrace will timeout requests after 10 seconds
* Consider caching health status for frequently called checks

### Frequency

* UserTrace calls health checks before each simulation
* Implement lightweight checks that don't impact system performance
* Avoid expensive operations in health check logic

## Best Practices

1. **Keep it Simple**: Health checks should be lightweight and fast
2. **Include Dependencies**: Check critical external services
3. **Use Caching**: Cache expensive dependency checks
4. **Return Meaningful Data**: Include metrics that help diagnose issues
5. **Handle Failures Gracefully**: Always return a response, even for partial failures

<Note>
  **Monitoring**: Consider using the health check endpoint for your own monitoring and alerting systems.
</Note>