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

# 서비스 상태 조회

<Info>
  **v1 Enterprise API (Coming Soon)**

  이 엔드포인트는 Enterprise 버전에서 제공될 예정입니다.
  현재는 [v0 API](/api-reference/v0/overview)를 사용하세요.
</Info>

서비스의 상세 상태를 조회합니다. 각 컴포넌트(데이터베이스, 캐시, AI 모델)의 상태와 성능 지표를 확인할 수 있습니다.

***

## Response

### 성공

서비스 상태 조회에 성공하면 ServiceStatus 객체가 반환됩니다.

### 실패

| 상태 코드 | 에러 타입                  | 설명             |
| ----- | ---------------------- | -------------- |
| 401   | `authentication_error` | API 키가 유효하지 않음 |
| 429   | `rate_limited`         | 요청 한도 초과       |

***

## 요청 예시

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.sajuapi.dev/v1/status \
    -H "X-API-Key: bs_live_xxx"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.sajuapi.dev/v1/status',
    {
      headers: {
        'X-API-Key': 'bs_live_xxx'
      }
    }
  );

  const status = await response.json();
  console.log(`Overall status: ${status.status}`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.sajuapi.dev/v1/status',
      headers={'X-API-Key': 'bs_live_xxx'}
  )

  status = response.json()
  print(f"Overall status: {status['status']}")
  ```
</CodeGroup>

***

## 응답 예시

### 정상

```json theme={null}
{
  "status": "operational",
  "version": "1.2.3",
  "environment": "production",
  "timestamp": "2025-01-16T09:00:00Z",
  "components": {
    "api": {
      "status": "operational",
      "latency_ms": 12
    },
    "database": {
      "status": "operational",
      "latency_ms": 8,
      "connections": {
        "active": 15,
        "idle": 5,
        "max": 100
      }
    },
    "cache": {
      "status": "operational",
      "latency_ms": 2,
      "hit_rate": 78.5,
      "memory_usage_mb": 256
    },
    "ai_models": {
      "status": "operational",
      "haiku": {
        "status": "operational",
        "avg_latency_ms": 1200
      },
      "sonnet": {
        "status": "operational",
        "avg_latency_ms": 2800
      },
      "gpt4o": {
        "status": "degraded",
        "avg_latency_ms": 5500,
        "message": "Higher than normal latency"
      }
    }
  },
  "uptime": {
    "seconds": 864000,
    "human": "10 days"
  },
  "last_incident": {
    "id": "inc_abc123",
    "status": "resolved",
    "resolved_at": "2025-01-10T15:30:00Z",
    "message": "Database connection pool exhausted"
  }
}
```

### 부분 장애

```json theme={null}
{
  "status": "degraded",
  "version": "1.2.3",
  "environment": "production",
  "timestamp": "2025-01-16T09:00:00Z",
  "components": {
    "api": {
      "status": "operational",
      "latency_ms": 15
    },
    "database": {
      "status": "degraded",
      "latency_ms": 250,
      "message": "High latency detected",
      "connections": {
        "active": 95,
        "idle": 0,
        "max": 100
      }
    },
    "cache": {
      "status": "operational",
      "latency_ms": 3
    },
    "ai_models": {
      "status": "operational"
    }
  },
  "active_incidents": [
    {
      "id": "inc_xyz789",
      "status": "investigating",
      "started_at": "2025-01-16T08:45:00Z",
      "message": "Database performance degradation"
    }
  ]
}
```

***

## ServiceStatus 객체

| 필드                 | 타입     | 설명                                                         |
| ------------------ | ------ | ---------------------------------------------------------- |
| `status`           | string | 전체 서비스 상태입니다. `operational`, `degraded`, `outage` 중 하나입니다. |
| `version`          | string | API 버전입니다.                                                 |
| `environment`      | string | 환경입니다. `production`, `staging` 중 하나입니다.                    |
| `timestamp`        | string | 상태 확인 시간입니다.                                               |
| `components`       | object | 각 컴포넌트별 상태입니다.                                             |
| `uptime`           | object | 서비스 가동 시간입니다.                                              |
| `last_incident`    | object | 마지막 인시던트 정보입니다.                                            |
| `active_incidents` | array  | 현재 진행 중인 인시던트 목록입니다.                                       |

***

## 상태 값

| 상태            | 설명                           |
| ------------- | ---------------------------- |
| `operational` | 모든 시스템이 정상적으로 작동 중입니다.       |
| `degraded`    | 일부 기능이 저하되었지만 서비스는 이용 가능합니다. |
| `outage`      | 서비스를 사용할 수 없습니다.             |

***

## 모니터링 대시보드

서비스 상태를 주기적으로 모니터링하여 장애를 조기에 감지할 수 있습니다.

```javascript theme={null}
// 상태 모니터링 예시
async function monitorStatus() {
  const response = await fetch('/v1/status', {
    headers: { 'X-API-Key': 'bs_live_xxx' }
  });

  const status = await response.json();

  // 전체 상태 확인
  if (status.status !== 'operational') {
    console.warn(`서비스 상태: ${status.status}`);

    // 문제 컴포넌트 확인
    for (const [name, component] of Object.entries(status.components)) {
      if (component.status !== 'operational') {
        console.error(`${name}: ${component.status} - ${component.message || ''}`);
      }
    }
  }

  // 캐시 히트율 확인
  if (status.components.cache.hit_rate < 50) {
    console.warn(`캐시 히트율 저하: ${status.components.cache.hit_rate}%`);
  }

  return status;
}

// 5분마다 모니터링
setInterval(monitorStatus, 5 * 60 * 1000);
```

<Warning>
  상태 페이지는 공개적으로 접근 가능하지만, 상세 정보(연결 수, 메모리 사용량 등)는 인증된 요청에만 포함됩니다.
</Warning>