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

운세 생성 관련 통계를 조회합니다. 모델별 사용량, 캐시 히트율, 평균 점수 등을 확인할 수 있습니다.

***

## Query 파라미터

<ParamField query="start_date" type="string">
  조회 시작 날짜입니다. ISO 8601 형식(YYYY-MM-DD)입니다. 기본값은 30일 전입니다.
</ParamField>

<ParamField query="end_date" type="string">
  조회 종료 날짜입니다. ISO 8601 형식(YYYY-MM-DD)입니다. 기본값은 오늘입니다.
</ParamField>

<ParamField query="fortune_type" type="string">
  특정 운세 유형만 조회합니다. `daily`, `yearly`, `monthly` 중 하나입니다.
</ParamField>

***

## Response

### 성공

운세 통계 조회에 성공하면 FortuneReport 객체가 반환됩니다.

### 실패

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

***

## 요청 예시

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.sajuapi.dev/v1/reports/fortunes?start_date=2025-01-01&end_date=2025-01-16" \
    -H "X-API-Key: bs_live_xxx"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.sajuapi.dev/v1/reports/fortunes?start_date=2025-01-01&end_date=2025-01-16',
    {
      headers: {
        'X-API-Key': 'bs_live_xxx'
      }
    }
  );

  const report = await response.json();
  ```

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

  response = requests.get(
      'https://api.sajuapi.dev/v1/reports/fortunes',
      headers={'X-API-Key': 'bs_live_xxx'},
      params={
          'start_date': '2025-01-01',
          'end_date': '2025-01-16'
      }
  )

  report = response.json()
  ```
</CodeGroup>

***

## 응답 예시

```json theme={null}
{
  "start_date": "2025-01-01",
  "end_date": "2025-01-16",
  "summary": {
    "total_fortunes": 12580,
    "unique_profiles": 3420,
    "cache_hit_rate": 72.5,
    "average_score": 73.2,
    "average_latency_ms": 1850,
    "total_cost_usd": 8.45
  },
  "by_type": {
    "daily": {
      "count": 10250,
      "percentage": 81.5,
      "average_score": 72.8,
      "cache_hit_rate": 78.2
    },
    "yearly": {
      "count": 1850,
      "percentage": 14.7,
      "average_score": 74.5,
      "cache_hit_rate": 45.3
    },
    "monthly": {
      "count": 480,
      "percentage": 3.8,
      "average_score": 75.1,
      "cache_hit_rate": 52.1
    }
  },
  "by_model": {
    "haiku": {
      "count": 9500,
      "percentage": 75.5,
      "average_latency_ms": 1200,
      "cost_usd": 2.85
    },
    "sonnet": {
      "count": 2580,
      "percentage": 20.5,
      "average_latency_ms": 2800,
      "cost_usd": 4.64
    },
    "gpt4o": {
      "count": 500,
      "percentage": 4.0,
      "average_latency_ms": 3500,
      "cost_usd": 0.96
    }
  },
  "score_distribution": {
    "0-20": 245,
    "21-40": 890,
    "41-60": 3250,
    "61-80": 5420,
    "81-100": 2775
  },
  "category_averages": {
    "overall": 73.2,
    "wealth": 68.5,
    "love": 75.8,
    "health": 71.2,
    "career": 74.9
  },
  "daily_trend": [
    {
      "date": "2025-01-01",
      "count": 780,
      "average_score": 72.5
    },
    {
      "date": "2025-01-02",
      "count": 820,
      "average_score": 73.1
    }
  ]
}
```

***

## FortuneReport 객체

| 필드                   | 타입     | 설명              |
| -------------------- | ------ | --------------- |
| `summary`            | object | 전체 요약 통계입니다.    |
| `by_type`            | object | 운세 유형별 통계입니다.   |
| `by_model`           | object | AI 모델별 통계입니다.   |
| `score_distribution` | object | 점수 분포입니다.       |
| `category_averages`  | object | 카테고리별 평균 점수입니다. |
| `daily_trend`        | array  | 일별 추이입니다.       |

***

## 캐시 히트율 최적화

캐시 히트율을 높이면 비용을 절감하고 응답 속도를 개선할 수 있습니다.

* **동일한 조건 사용**: `profile_id`, `fortune_type`, `fortune_date`, `model` 조합이 동일하면 캐시가 적용됩니다.
* **배치 생성 활용**: 자정에 [배치 API](/api-reference/fortunes/batch)로 미리 생성하면 사용자 요청 시 캐시된 결과를 반환합니다.
* **오늘의 운세 API 사용**: [오늘의 운세](/api-reference/fortunes/daily) 엔드포인트는 자동으로 캐시를 활용합니다.