---
title: 사용량 API
description: 월별 측정 수량, 정규화된 단위, 예상 금액, 요율표에서 누락된 항목을 읽습니다.
species: reference
---
# 사용량 API

사용량은 읽기 전용이며 `data:read`가 필요합니다. Supernova의 시간별 사용량 원장과 요율표에서 가져옵니다. 엔드포인트는 결제 서비스에 실시간으로 요청하지 않습니다.

## 월별 조회

```endpoint
GET /usage
```

매개변수가 없으면 현재 UTC 월을 반환합니다. 다른 월을 조회하려면 `period=YYYY-MM`을 전달하세요.

```bash
curl "https://api.supernova.ai/usage?period=2026-07" \
  -H "Authorization: Bearer pat_..."
```

수량은 표시 단위로 변환됩니다. 가격이 정해진 항목에는 `amount_cents`가 포함됩니다. 가격이 없는 사용량 종류는 `amount_cents: null`이며 `missing_rate_card_kinds`에 나타납니다. 클라이언트는 null을 비용이 0이라는 뜻으로 처리하면 안 됩니다.

| 종류 | 표시 단위 |
|---|---|
| `compute_gb_sec` | GB-시간 |
| `storage_gb_hour` | GB-월 |
| `egress_byte` | GB |
| `read_op`, `write_op`, `list_op` | 백만 회 작업 |
| `ai_token_in`, `ai_token_out` | 백만 토큰 |

## 조회 가능한 월 목록

`periods=1`을 전달하면 사용량이 있는 월을 최신순으로 조회합니다. `period`와 `periods=1`은 함께 사용할 수 없습니다.

월 형식이 잘못되었거나 허용되지 않는 조합이면 `400 invalid_period`를 반환합니다. 값이 `1`이 아니면 `400 invalid_periods`를 반환합니다.

현재 월의 값은 예상치이며 새로운 시간별 기록이 들어오면 바뀔 수 있습니다. 마감된 월의 값도 같은 원장을 기반으로 하지만 수정된 요율표가 적용되면 변경될 수 있습니다.