---
title: "Get Subscription Usage Summary"
method: GET
path: "/v1/subscriptions/{subscription_id}/usage-summary"
tags: ["Billing Subscriptions"]
---

# Get Subscription Usage Summary

`GET /v1/subscriptions/{subscription_id}/usage-summary`

## Request

- Base URL: `https://api.xdata.kr` (the document declares no server; this is the origin it was published from)
- URL: `https://api.xdata.kr/v1/subscriptions/{subscription_id}/usage-summary`
- Auth: one of:
  - HTTP basic
  - OAuth 2 (authorization code, authorization URL `https://api.xdata.kr/oauth/authorize`, token URL `https://api.xdata.kr/oauth/token`)

구독 이번 결제주기 사용량 조회 (실사용 축, 콘솔 표시 전용 — 청구 계산과 무관).

## Path parameters

- `subscription_id` integer, required

## Query parameters

- `env_scope` 'production' | 'real_test' | 'sandbox', nullable: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.

## Headers

- `Authorization` string, nullable
- `X-Env-Scope` 'production' | 'real_test' | 'sandbox', nullable: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.

## Response `200`

Successful Response

- SubscriptionUsageSummaryResponse: `GET /v1/subscriptions/{id}/usage-summary` 응답 - 실사용 축이고 청구 계산과 무관하다. 콘솔 "이번 결제주기 사용량" 표시 전용 — `used_quantity` 는 집계(청구 확정) + 미집계(pending) 사용량을 모두 합산한 값이라 `sum_aggregated_quantity_for_period` (청구 로직, 집계된 수량만) 와는 축이 다르다. 청구 금액 산정에는 사용하지 않는다. `period_start`/`period_end`/`included_usage_free_units` 가 모두 NULL 이면 (`current_period_start`/`end` 미확정 = PENDING 등) `used_quantity=0` 고정 (`_resolve_free_allowance` fail-safe 1:1 재사용).
  - `subscription_id` integer, required: subscriptions.id.
  - `organization_id` integer, required: 소유 조직 PK.
  - `env_scope` 'sandbox' | 'real_test' | 'production', required: 환경 스코프.
  - `period_start` string, date-time, nullable: 현재 청구 기간 시작 (미확정 시 NULL).
  - `period_end` string, date-time, nullable: 현재 청구 기간 종료 (미확정 시 NULL).
  - `included_usage_free_units` integer, nullable: 플랜 무료 포함건수(N). NULL=무료 미설정(1건부터 종량 과금).
  - `used_quantity` integer, required: 현재 청구 기간 내 총 사용량(집계+미집계 합산).

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/xdata/apis/xboss-api.md) · [All operations](https://skmtc.dev/xdata/apis/xboss-api/llms.txt) · [OpenAPI document](https://skmtc.dev/xdata/apis/xboss-api/revisions/816de78950db?raw)