> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 소비 사용량 조회
> - 지정 기간의 소비 금액과 호출 통계 조회
- 모델 필터 및 모델별·날짜별 그룹화 지원
- 현재 API Key 또는 계정 전체의 소비 통계 지원
- USD 금액, 크레딧, 호출 수, 토큰 사용량 반환
API Key로 지정 기간의 소비 금액을 조회합니다. 모델로 필터링하고 모델별, 날짜별 또는 두 기준을 함께 사용하여 그룹화할 수 있습니다. 집계 결과를 바로 반환하므로 작업 생성이나 상태 폴링이 필요하지 않습니다.
```bash cURL theme={null}
curl --get 'https://api.apimart.ai/v1/usage' \
--header 'Authorization: Bearer ' \
--data-urlencode 'start=2026-09-01T00:00:00+08:00' \
--data-urlencode 'end=2026-09-08T00:00:00+08:00' \
--data-urlencode 'group_by=model'
```
```python Python theme={null}
import requests
response = requests.get(
"https://api.apimart.ai/v1/usage",
headers={"Authorization": "Bearer "},
params={
"start": "2026-09-01T00:00:00+08:00",
"end": "2026-09-08T00:00:00+08:00",
"group_by": "model",
},
timeout=30,
)
payload = response.json()
if not response.ok or not payload.get("success"):
message = payload.get("error", {}).get("message", "사용량 조회 실패")
raise RuntimeError(f"HTTP {response.status_code}: {message}")
print(payload["data"]["total"])
print(payload["data"]["items"])
```
```javascript JavaScript theme={null}
const url = new URL("https://api.apimart.ai/v1/usage");
url.search = new URLSearchParams({
start: "2026-09-01T00:00:00+08:00",
end: "2026-09-08T00:00:00+08:00",
group_by: "model",
}).toString();
const response = await fetch(url, {
headers: { Authorization: "Bearer " },
});
const payload = await response.json();
if (!response.ok || !payload.success) {
throw new Error(
`HTTP ${response.status}: ${payload.error?.message ?? "사용량 조회 실패"}`,
);
}
console.log(payload.data.total);
console.log(payload.data.items);
```
```json 200 theme={null}
{
"success": true,
"data": {
"scope": "key",
"start": 1788192000,
"end": 1788796800,
"tz": "Asia/Shanghai",
"group_by": "model",
"total": {
"amount_usd": 12.3456,
"credits": 123.456,
"requests": 1834,
"prompt_tokens": 902311,
"completion_tokens": 215044
},
"items": [
{
"model": "gpt-5.6-luna",
"amount_usd": 9.1271,
"credits": 91.271,
"requests": 1520,
"prompt_tokens": 880120,
"completion_tokens": 201300
},
{
"model": "sora-2",
"amount_usd": 3.2185,
"credits": 32.185,
"requests": 314,
"prompt_tokens": 22191,
"completion_tokens": 13744
}
]
}
}
```
```json 400 theme={null}
{
"success": false,
"error": {
"code": "range_too_large",
"message": "Time range must not exceed 31 days.",
"type": "usage_query_error"
}
}
```
## 인증
모델 호출에 사용하는 API Key로 Bearer Token 인증을 수행합니다. [API Key 관리 페이지](https://apimart.ai/keys)에서 키를 발급받으세요.
```
Authorization: Bearer YOUR_API_KEY
```
잔액이 0이어도 조회할 수 있습니다. 잔액은 검사하지 않지만 API Key 상태, 만료 시간, IP 허용 목록 및 계정 상태는 검사합니다.
## 엔드포인트
```text theme={null}
GET /v1/usage
GET /usage
```
두 엔드포인트의 기능은 같으며 CORS를 지원합니다. API Key를 안전하게 보관하고 공개 프런트엔드 코드에 노출하지 마세요.
## 요청 매개변수
모든 매개변수는 URL 쿼리로 전달합니다.
시작 시간을 포함합니다. 초 단위 Unix 타임스탬프 또는 시간대가 포함된 RFC3339 문자열(예: `2026-09-01T00:00:00+08:00`)을 지원합니다.
생략하면 `end`의 24시간 전입니다. 타임스탬프 단위는 밀리초가 아닌 초입니다.
종료 시간은 포함하지 않습니다. 형식은 `start`와 같으며 생략하면 현재 시간입니다.
`start`보다 늦어야 하며 `end - start`는 31일 이하여야 합니다.
모델 이름입니다. 생략하면 모든 모델을 집계합니다. 여러 모델은 쉼표로 구분하며 최대 `50`개입니다.
대소문자를 구분하지 않는 정확한 일치만 지원하며 와일드카드는 지원하지 않습니다.
예: `gpt-5.6-luna,sora-2`
그룹화 방식:
* `none`: 합계만 반환하며 `items`는 빈 배열
* `model`: 모델별 그룹화
* `date`: 달력 날짜별 그룹화
* `model,date`: 모델과 달력 날짜를 함께 사용하여 그룹화
IANA 시간대 이름입니다. 기본값은 `Asia/Shanghai`입니다.
`group_by`에 `date`가 포함될 때 날짜 경계에만 영향을 주며 조회 시작·종료 시점은 바꾸지 않습니다. RFC3339 시간은 문자열에 지정된 시간대로 해석됩니다.
집계 범위:
* `key`: 현재 API Key만 집계(기본값)
* `account`: 현재 API Key가 속한 계정의 모든 API Key를 합산
조회 구간은 `[start, end)`로 시작은 포함하고 종료는 제외합니다. 이전 조회의 `end`와 다음 조회의 `start`를 같게 설정하면 경계 시점을 중복 집계하지 않습니다.
URL을 직접 구성할 때 RFC3339의 `+`는 `%2B`로 인코딩해야 합니다. 예제의 cURL `--data-urlencode`, Python `params`, JavaScript `URLSearchParams`가 인코딩을 자동 처리합니다.
## 요청 예제
### 현재 API Key의 최근 24시간 소비 합계
쿼리 매개변수를 생략하면 기본 시간 범위, 집계 범위 및 그룹화 방식을 사용합니다.
```bash theme={null}
curl 'https://api.apimart.ai/v1/usage' \
--header 'Authorization: Bearer '
```
### 계정 전체의 지정 모델별 일일 소비
베이징 시간으로 2026년 9월 11일부터 9월 18일까지(9월 18일 제외)의 소비를 조회합니다.
```bash theme={null}
curl --get 'https://api.apimart.ai/v1/usage' \
--header 'Authorization: Bearer ' \
--data-urlencode 'start=1789056000' \
--data-urlencode 'end=1789660800' \
--data-urlencode 'model=gpt-5.6-luna' \
--data-urlencode 'group_by=date' \
--data-urlencode 'scope=account' \
--data-urlencode 'tz=Asia/Shanghai'
```
### 모델과 날짜로 함께 그룹화
```bash theme={null}
curl --get 'https://api.apimart.ai/v1/usage' \
--header 'Authorization: Bearer ' \
--data-urlencode 'start=2026-09-01T00:00:00+08:00' \
--data-urlencode 'end=2026-09-08T00:00:00+08:00' \
--data-urlencode 'model=gpt-5.6-luna,sora-2' \
--data-urlencode 'group_by=model,date' \
--data-urlencode 'tz=Asia/Shanghai'
```
이 방식에서는 각 `items` 요소에 `model`과 `date`가 모두 포함됩니다.
## 응답 필드
조회 성공 여부입니다. 성공하면 `true`, 사용량 조회 오류이면 `false`입니다.
성공 시 조회 범위, 합계 및 그룹별 내역을 반환합니다.
집계 범위: `key` 또는 `account`.
실제 조회 시작 시간입니다. 초 단위 Unix 타임스탬프이며 시작을 포함합니다.
실제 조회 종료 시간입니다. 초 단위 Unix 타임스탬프이며 종료를 제외합니다.
날짜별 그룹화에 사용한 시간대입니다.
그룹화 방식: `none`, `model`, `date` 또는 `model,date`.
조회 범위의 합계입니다. 통계 필드는 아래 표를 참조하세요.
그룹별 내역으로 `amount_usd` 내림차순입니다. `group_by=none`이면 빈 배열이며 각 요소는 아래 표의 통계 필드를 포함합니다.
* `group_by`에 `model`이 포함되면 요소에 `model` 포함
* `group_by`에 `date`가 포함되면 요소에 `date` 포함. 형식은 `YYYY-MM-DD`이며 날짜는 `tz`를 기준으로 구분
`data.total`과 `data.items[]`는 다음 통계 필드를 공유합니다.
| 필드 | 유형 | 설명 |
| ------------------- | ------- | ---------------------------------------------- |
| `amount_usd` | number | USD 금액, 소수점 이하 6자리로 반올림 |
| `credits` | number | 서비스 크레딧. `amount_usd × 10`이며 공식 웹사이트 표시 단위와 동일 |
| `requests` | integer | 과금에 성공한 호출 수 |
| `prompt_tokens` | integer | 입력 토큰 수. 호출당 또는 초당 과금되는 이미지·영상 모델은 일반적으로 0 |
| `completion_tokens` | integer | 출력 토큰 수. 호출당 또는 초당 과금되는 이미지·영상 모델은 일반적으로 0 |
사용량 조회 오류 시 `code`, `message`, `type`을 반환합니다. `type`은 `usage_query_error`입니다. 401 / 403 인증 오류는 인증 계층에서 반환합니다.
## 호출 제한 및 캐시
* API Key당 분당 최대 `60`회이며 전역 API 호출 제한도 적용
* 동일 매개변수의 결과는 `60`초 캐시되며 응답 헤더 `X-Usage-Cache`는 `hit` 또는 `miss`
* 소비 기록은 보통 1초 이내에 조회 가능하지만 최근 1분의 데이터는 불완전할 수 있고 캐시 지연도 존재
* 조회 간격은 최소 1분을 권장하며 실시간 과금 알림으로 사용하지 마세요
## 집계 기준
* 과금에 성공한 호출 기록을 사용하며 공식 웹사이트 대시보드와 같은 데이터
* 실패한 호출이나 작업 실패 후 환불된 기록은 제외하므로 직접 차감할 필요 없음. 이미지 배치가 일부 성공하면 실제 제공된 이미지 수로 과금
* 과금 기록 시점 기준. 비동기 이미지·영상 작업은 제출이 아닌 완료 시점에 기록되며 자정을 넘긴 작업은 완료일에 포함
* 삭제 후 재생성한 API Key는 새 키입니다. 새 키의 `scope=key` 조회에는 이전 키의 이력이 포함되지 않음
* 관리자의 수동 잔액 조정은 호출 소비가 아니므로 제외
* 2026년 4월 27일 이후 데이터 조회 가능
## 오류 처리
| HTTP 상태 | `error.code` | 설명 |
| --------- | ------------------------------- | ---------------------------------------- |
| 400 | `invalid_start` / `invalid_end` | 시작 또는 종료 시간 형식 오류 |
| 400 | `invalid_range` | `end`가 `start`보다 늦지 않음 |
| 400 | `range_too_large` | 31일 초과. 여러 조회 구간으로 나누세요 |
| 400 | `invalid_tz` | 알 수 없는 IANA 시간대 |
| 400 | `invalid_group_by` | 잘못된 그룹화 방식 |
| 400 | `invalid_scope` | 잘못된 집계 범위 |
| 400 | `too_many_models` | 모델 수가 50개 초과 |
| 401 / 403 | — | API Key가 유효하지 않거나 만료됨, IP 미허용 또는 계정 비활성화 |
| 429 | — | 키당 분당 60회 초과 또는 전역 API 호출 제한 |
| 503 | `usage_unavailable` | 사용량 데이터 일시 사용 불가. 나중에 재시도 |
`503 usage_unavailable` 응답은 금액을 반환하지 않습니다. 조회 불가를 뜻하며 소비가 0이라는 의미가 아닙니다. 실패 응답을 금액 0으로 변환하거나 이전 성공 결과를 덮어쓰지 마세요.
## 다른 엔드포인트와의 차이
| 엔드포인트 | 기능 |
| --------------------------------- | ------------------------------------ |
| `GET /v1/dashboard/billing/usage` | 누적 소비 합계만 반환. 모델 또는 시간 필터 불가 |
| `POST /v1/logs/export` | 호출 내역 비동기 내보내기(CSV / XLSX). 직접 집계 필요 |
| `GET /v1/usage` | 지정 시간 및 모델로 조회하여 합계와 그룹별 소비를 직접 반환 |
남은 한도는 [토큰 잔액 조회](/ko/api-reference/account/token-balance) 또는 [사용자 잔액 조회](/ko/api-reference/account/user-balance)를 이용하세요.