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

# API 사용량 조회

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

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

API 사용량 통계를 조회합니다. 기간별, 엔드포인트별 호출 횟수와 비용 정보를 확인할 수 있습니다.

***

## Query 파라미터

<ParamField query="period" type="string" default="day">
  집계 기간입니다. `hour`, `day`, `week`, `month` 중 하나입니다.
</ParamField>

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

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

<ParamField query="group_by" type="string" default="endpoint">
  그룹화 기준입니다. `endpoint`, `method`, `status_code` 중 하나입니다.
</ParamField>

***

## Response

### 성공

API 사용량 조회에 성공하면 UsageReport 객체가 반환됩니다.

### 실패

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

***

## 요청 예시

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

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    period: 'day',
    start_date: '2025-01-10',
    end_date: '2025-01-16'
  });

  const response = await fetch(
    `https://api.sajuapi.dev/v1/reports/usage?${params}`,
    {
      headers: {
        'X-API-Key': 'bs_live_xxx'
      }
    }
  );

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

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

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

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

***

## 응답 예시

```json theme={null}
{
  "period": "day",
  "start_date": "2025-01-10",
  "end_date": "2025-01-16",
  "summary": {
    "total_requests": 15420,
    "successful_requests": 15180,
    "failed_requests": 240,
    "success_rate": 98.44,
    "total_cost_usd": 12.45,
    "average_latency_ms": 245
  },
  "by_endpoint": [
    {
      "endpoint": "POST /v1/fortunes",
      "requests": 5230,
      "success_rate": 99.2,
      "average_latency_ms": 2340,
      "cost_usd": 8.50
    },
    {
      "endpoint": "GET /v1/fortunes/daily/{profile_id}",
      "requests": 4890,
      "success_rate": 99.8,
      "average_latency_ms": 45,
      "cost_usd": 0
    },
    {
      "endpoint": "POST /v1/profiles",
      "requests": 2100,
      "success_rate": 98.5,
      "average_latency_ms": 120,
      "cost_usd": 0
    },
    {
      "endpoint": "GET /v1/profiles",
      "requests": 1850,
      "success_rate": 99.9,
      "average_latency_ms": 85,
      "cost_usd": 0
    }
  ],
  "daily_breakdown": [
    {
      "date": "2025-01-10",
      "requests": 2100,
      "cost_usd": 1.75
    },
    {
      "date": "2025-01-11",
      "requests": 2250,
      "cost_usd": 1.82
    },
    {
      "date": "2025-01-12",
      "requests": 2180,
      "cost_usd": 1.78
    },
    {
      "date": "2025-01-13",
      "requests": 2050,
      "cost_usd": 1.65
    },
    {
      "date": "2025-01-14",
      "requests": 2340,
      "cost_usd": 1.90
    },
    {
      "date": "2025-01-15",
      "requests": 2200,
      "cost_usd": 1.80
    },
    {
      "date": "2025-01-16",
      "requests": 2300,
      "cost_usd": 1.75
    }
  ],
  "rate_limit_status": {
    "limit": 100000,
    "used": 15420,
    "remaining": 84580,
    "resets_at": "2025-02-01T00:00:00Z"
  }
}
```

***

## UsageReport 객체

| 필드                  | 타입     | 설명            |
| ------------------- | ------ | ------------- |
| `period`            | string | 집계 기간입니다.     |
| `start_date`        | string | 조회 시작 날짜입니다.  |
| `end_date`          | string | 조회 종료 날짜입니다.  |
| `summary`           | object | 전체 요약 통계입니다.  |
| `by_endpoint`       | array  | 엔드포인트별 통계입니다. |
| `daily_breakdown`   | array  | 일별 분석입니다.     |
| `rate_limit_status` | object | 요청 한도 상태입니다.  |

***

## 비용 계산

API 호출 비용은 주로 AI 모델 사용에서 발생합니다.

| 모델     | 비용 (대략)    |
| ------ | ---------- |
| haiku  | \$0.001/요청 |
| sonnet | \$0.002/요청 |
| gpt4o  | \$0.003/요청 |

<Note>
  캐시된 응답(`cached: true`)은 비용이 발생하지 않습니다. 캐시 히트율을 높여 비용을 절감하세요.
</Note>