---
title: 사용량 조회·한도 관리와 정산
description: "이 문서는 크레딧 사용량을 확인하는 방법, 사용 한도와 알림이 동작하는 방식, 매월 정산·청구 절차를 안내합니다. --- ## 1. 사용량 조회: `GET /usage/summary` API Key별로 기간 내 호출 수, 에러율, 크레딧 사용량을 조회합니다. **조회해도 크레딧이 차감되지 않습니다.** ### 요청 ``` GET…"
url: "https://kr.listeningmind.com/data-api/pricing/usage-billing/"
updated: "2026-10-16"
category: 과금 정책
---

# 사용량 조회·한도 관리와 정산

이 문서는 크레딧 사용량을 확인하는 방법, 사용 한도와 알림이 동작하는 방식, 매월 정산·청구 절차를 안내합니다.

---

## 1. 사용량 조회: `GET /usage/summary`

API Key별로 기간 내 호출 수, 에러율, 크레딧 사용량을 조회합니다. **조회해도 크레딧이 차감되지 않습니다.**

### 요청

```
GET /usage/summary?from=2026-09-01&to=2026-09-21
Header: LM-API-KEY: <발급받은 API Key>
```

| **파라미터** | **필수** | **형식** | **설명** |
| --- | --- | --- | --- |
| `from` | Y | `YYYY-MM-DD` | 조회 시작일 (한국 시간 기준) |
| `to` | Y | `YYYY-MM-DD` | 조회 종료일 (한국 시간 기준) |

데이터 API 중 유일한 GET 방식이며, 파라미터는 쿼리 문자열로 전달합니다.

### 응답 예시

```
{
  "from": "2026-09-01",
  "to": "2026-09-21",
  "total_calls": 1403,
  "error_count": 4,
  "error_rate": 0.29,
  "total_credits": 4051258,
  "endpoints": [
    { "endpoint": "/cluster_finder", "calls": 95, "ratio": 6.77,
      "error_rate": 0.0, "credits": 2437800, "credits_ratio": 60.17 }
    // 이하 생략
  ],
  "platforms": [
    { "platform": "Claude", "calls": 291, "ratio": 20.74,
      "error_rate": 0.34, "credits": 1003585, "credits_ratio": 24.77 }
    // 이하 생략
  ],
  "timeseries": [
    { "date": "2026-09-04", "calls": 356, "errors": 0, "credits": 1497262 }
    // 이하 생략
  ]
}
```

### 응답 필드

| **필드** | **내용** |
| --- | --- |
| `total_calls` · `error_count` · `error_rate` | 기간 내 총 호출 수 / 에러 수(4xx+5xx) / 에러율(%) |
| `total_credits` | 기간 내 총 사용 크레딧 |
| `endpoints[]` | 엔드포인트별 호출 수·비율, 4xx·5xx 에러 수와 비율, 크레딧, 크레딧 비율(`credits_ratio`) |
| `platforms[]` | 연동 플랫폼별 같은 지표 |
| `timeseries[]` | 일별(한국 시간) 호출 수·에러 수·사용 크레딧 |

### 이렇게 활용하세요

| **목적** | **볼 필드** |
| --- | --- |
| 어떤 API가 크레딧을 많이 쓰는지 확인 | `endpoints[].credits_ratio` |
| AI 플랫폼별 사용량 확인 | `platforms[]` |
| 연동 오류 원인 구분 | `rate_4xx`(요청 파라미터 오류) / `rate_5xx`(서버 오류) |
| 사내 비용 대시보드·예산 알림 구성 | `timeseries[]`를 사내 BI·DW에 적재 |

### 유의 사항

- **조회 범위는 요청에 사용한 API Key 한 개의 사용량**입니다. API Key가 여러 개라면 Key별로 각각 조회하세요. 월 정액 구독은 포함 크레딧이 Key별로 적용되므로, Key별 조회로 포함 크레딧 대비 사용량을 확인할 수 있습니다.
- `platform` 값은 `X-MCP-Client` 헤더 기준으로 집계합니다. 헤더 없이 직접 호출하면 `unknown-direct`, MCP를 거쳤지만 클라이언트를 식별하지 못하면 `unknown-mcp`로 집계됩니다.
- `/usage/summary`의 크레딧은 조회 시점 기준 집계값이므로, **청구서의 최종 정산 수치와 차이가 있을 수 있습니다.** 청구는 회사 API 관리 시스템의 월간 누적 기록을 기준으로 합니다.

호출 한 건의 과금 내역은 각 응답의 `cost_detail`과 `used_credits`로 확인할 수 있습니다. 자세한 내용은 [크레딧 산정 기준과 엔드포인트별 단가](https://kr.listeningmind.com/data-api/pricing/credit-and-endpoint-pricing/)를 참고하세요.

---

## 2. 사용 한도와 알림

### 요금제별 한도

| **구분** | **데이터 종량제** | **월 정액 구독** |
| --- | --- | --- |
| 한도 기준 | 월 크레딧 사용 상한(Credit Cap) — **선택 사항** | API Key당 월 포함 크레딧 사용량 설정 |
| 한도 도달 시 | 해당 API Key의 호출 중단 | 초과분을 다음 달에 청구 (계약 시 호출 중단을 선택할 수도 있음) |
| 상한을 정하지 않으면 | 호출이 중단되지 않으며, 사용한 크레딧 전체를 정산 | — |

### 알림

사용량이 한도의 **70%, 90%, 100%에** 도달하면 계약 시 등록한 이메일로 알려 드립니다.

- 데이터 종량제: 설정한 사용 상한 기준
- 월 정액 구독: API Key별 포함 크레딧 기준

> 알림 메일은 발송이 지연되거나 누락될 수 있습니다. 실시간 확인이 필요하면 `/usage/summary`로 사내 알림을 함께 구성하는 것을 권장합니다.

### 호출이 중단되면

- 한도에 도달한 API Key로 요청하면 `402 Payment Required`(월 크레딧 한도 초과) 응답이 반환됩니다. 오류 응답은 과금되지 않습니다.
- 사용 한도와 포함 크레딧은 **정산 기준일에 초기화**되며, 그때부터 다시 호출할 수 있습니다.
- 정산 기준일 전에 다시 사용해야 한다면 담당자에게 한도 조정을 요청하세요.

---

## 3. 정산과 청구

### 정산 기준일

계약 시 **매월 1일 또는 15일** 중 하나를 정산 기준일로 선택합니다. 정산 기준일부터 다음 정산 기준일 전날까지가 한 정산 주기입니다.

| **정산 기준일** | **정산 주기 예시** |
| --- | --- |
| 매월 1일 | 10월 1일 ~ 10월 31일 |
| 매월 15일 | 10월 15일 ~ 11월 14일 |

### 청구 항목

| **요금제** | **매월 청구되는 항목** |
| --- | --- |
| 데이터 종량제 | 해당 정산 주기에 사용한 크레딧 × 1.3원 |
| 월 정액 구독 | 월 구독료 × API Key 수 + 직전 정산 주기의 Key별 초과 크레딧 × 1.3원 |

모든 금액은 VAT 별도입니다. 데이터 종량제의 초기 도입비는 계약 시 한 번 별도로 청구합니다.

### 청구와 납부 절차

| **순서** | **내용** |
| --- | --- |
| 1. 정산 | 회사 API 관리 시스템의 월간 누적 크레딧 기록으로 사용량을 확정합니다. |
| 2. 청구 | 정산 기준일로부터 5영업일 이내에 청구서와 전자세금계산서를 발행합니다. |
| 3. 납부 | 청구서 발행일로부터 30일 이내에 지정 계좌로 이체합니다. |
| 4. 이의 제기 | 청구 내역에 이의가 있으면 청구서 수령일로부터 7일 이내에 서면(이메일)으로 알려 주세요. 5영업일 이내에 검토 결과를 안내하며, 과오납이 확인되면 다음 달 요금에서 정산합니다. |

---

## 4. 자주 묻는 질문

**Q. 이번 달에 쓰지 못한 크레딧은 다음 달로 넘어가나요?**

아니요. 월 정액 구독의 포함 크레딧은 정산 기준일에 초기화되며, 남은 크레딧은 이월되지 않습니다.

**Q. API Key가 2개인데, 한 Key에서 남은 크레딧을 다른 Key에서 쓸 수 있나요?**

아니요. 포함 크레딧은 API Key별로 제공되며 Key 간에 합산되지 않습니다. 계산 예시는 [비용 계산 예시](https://kr.listeningmind.com/data-api/pricing/cost-examples/)를 참고하세요.

**Q. `/usage/summary`의 크레딧과 청구서 금액이 조금 달라요.**

`/usage/summary`는 조회 시점의 집계값이고, 청구는 정산 주기가 끝난 뒤 회사 API 관리 시스템의 월간 누적 기록으로 확정합니다. 집계 시점 차이로 수치가 다를 수 있습니다. 확인이 필요하면 청구서 수령일로부터 7일 이내에 문의해 주세요.

**Q. 오류가 난 호출도 과금되나요?**

아니요. 오류 응답(4xx·5xx)은 입력·출력 모두 과금하지 않습니다. 단, 정상 응답이지만 결과가 비어 있는 경우에는 입력 과금이 발생합니다.

**Q. API Key를 추가하려면 어떻게 하나요?**

담당자에게 요청해 주세요. 월 정액 구독은 API Key 수만큼 월 구독료와 포함 크레딧이 늘어납니다. 데이터 종량제는 API Key 개수에 따라 초기 도입비 조건이 달라질 수 있습니다.

**Q. 여러 시스템에서 API Key 하나를 같이 써도 되나요?**

API Key당 동시 접속은 1개로 제한됩니다. 여러 시스템에서 동시에 호출해야 한다면 API Key를 추가하거나 요청을 순서대로 보내도록 구성하세요.

**Q. 요금제를 바꿀 수 있나요?**

서면(이메일)으로 요청하시면 협의 후 다음 정산 주기부터 적용합니다.

**Q. 월 정액 구독은 언제 해지할 수 있나요?**

최소 이용 기간은 3개월입니다. 3개월이 지나면 월 단위로 해지할 수 있으며, 해지 절차와 시점은 계약서에서 안내합니다.

**Q. 사용 상한을 바꾸고 싶어요.**

담당자에게 요청해 주세요.

---

## 관련 문서

- [리스닝마인드 데이터 API 요금제 안내](https://kr.listeningmind.com/data-api/pricing/listeningmind-daas-data-api-pricing/)
- [크레딧 산정 기준과 엔드포인트별 단가](https://kr.listeningmind.com/data-api/pricing/credit-and-endpoint-pricing/)
- [비용 계산 예시](https://kr.listeningmind.com/data-api/pricing/cost-examples/)
- [비용 최적화 가이드](https://kr.listeningmind.com/data-api/pricing/cost-optimization/)

요금제와 정산에 대해 궁금한 점이 있다면 [상담 문의](https://kr.listeningmind.com/contact/)를 남겨 주세요.