# Claude Code 사용량 조회 방법 전체 정리

**조사일**: 2026-03-28
**조사 태스크**: task-1168.1 (dev7-team)
**상세 리서치 파일**: `/home/jay/.cokacdir/workspace/BCBD5839/research_*.md`

---

## 방법 전체 목록 (10가지)

### A. 공식 방법 (Anthropic 제공)

#### 1. Admin API - Usage Report
- **엔드포인트**: `GET /v1/organizations/usage_report/messages`
- **인증**: Admin API Key (`sk-ant-admin...`) 필요
- **데이터**: 토큰 사용량 (모델/워크스페이스/API키별, 1m/1h/1d 버킷)
- **제약**: 조직 계정 필수, 개인 불가. subscription 유저 누락 버그(#27780)
- **지연**: 5분

#### 2. Admin API - Cost Report
- **엔드포인트**: `GET /v1/organizations/cost_report`
- **인증**: Admin API Key
- **데이터**: USD 비용 (일별만)
- **제약**: 조직 계정 필수, Priority Tier 비용 미포함
- **지연**: 5분

#### 3. Admin API - Claude Code Analytics
- **엔드포인트**: `GET /v1/organizations/usage_report/claude_code`
- **인증**: Admin API Key
- **데이터**: 사용자별 일별 집계 (세션수, LOC, 커밋, PR, 도구 승인율, 모델별 토큰/비용)
- **제약**: 조직 계정 필수
- **지연**: 1시간

#### 4. Rate Limit Response Headers
- **방법**: 모든 API 응답 헤더에 자동 포함
- **인증**: 일반 API Key로 접근 가능
- **데이터**: 남은 토큰, 남은 요청, 리셋 시각 (14개 헤더)
- **제약**: Claude Code CLI에서 직접 접근 불가 (API 직접 호출 시에만)
- **실시간**: O

#### 5. statusline `rate_limits` 필드 (v2.1.80+)
- **방법**: statusLine.command에 전달되는 JSON에 포함
- **데이터**: 5시간/7일 `used_percentage`, `resets_at`
- **제약**: statusline hook 설정 필요
- **실시간**: O

#### 6. OpenTelemetry 내장 (CLAUDE_CODE_ENABLE_TELEMETRY=1)
- **방법**: 환경변수 설정으로 활성화
- **데이터**: 토큰, 비용, 세션, LOC, 커밋, PR + 이벤트(api_request, tool_result 등)
- **백엔드**: OTLP(gRPC/HTTP), Prometheus, Console
- **제약**: 수집 인프라 필요 (Prometheus+Grafana 등)
- **실시간**: O (5-60초)

### B. 비공식 방법 (커뮤니티 발견)

#### 7. OAuth Usage API 직접 호출
- **URL**: `https://api.anthropic.com/api/oauth/usage`
- **인증**: `~/.claude/.credentials.json`의 accessToken + `anthropic-beta: oauth-2025-04-20` 헤더
- **데이터**: five_hour/seven_day utilization, extra_usage
- **제약**: 비문서화 API, 과도한 rate limiting(#31637), Keychain popup 이슈
- **실시간**: O

#### 8. 로컬 JSONL 파일 파싱
- **경로**: `~/.claude/projects/[project-slug]/[sessionId].jsonl`
- **데이터**: per-turn 토큰(input/output/cache), costUSD, model, speed
- **도구**: ccusage(npm), claude-monitor(pip), sniffly, ccost 등
- **실시간**: O (fs.watch)

### C. 복합 방법

#### 9. Hook + JSONL 조합
- **방법**: PostToolUse hook에서 실시간 비용 수신 + JSONL 히스토리
- **데이터**: cost.total_cost_usd + context_window + 히스토리

#### 10. MCP 서버 (anthropic-billing-mcp)
- **방법**: Admin API를 MCP 도구로 래핑
- **데이터**: 자연어로 비용 조회
- **제약**: Admin API Key 필요

---

## 우리 환경 (Max20 구독) 적용 가능한 방법

1. **JSONL 파싱** - 즉시 사용 가능, 추가 인프라 불필요
2. **statusline rate_limits** - v2.1.80+ 이면 즉시 사용 가능
3. **OpenTelemetry** - 환경변수 설정만으로 활성화
4. **OAuth Usage API** - 비공식이지만 실질적으로 가장 많이 사용
5. **Hook 시스템** - 현재 세션 실시간 추적

## 주요 커뮤니티 도구

- **ccusage** (npm): `npx ccusage@latest` - 가장 인기, MCP 서버 지원
- **claude-monitor** (pip): `pip install claude-monitor` - 실시간 터미널 대시보드
- **sniffly**: 웹 대시보드
- **claude-code-otel**: Prometheus+Grafana 스택

## 참고
- Admin API는 조직 계정 필수 → 우리 환경에서는 불가
- subscription 유저가 Admin API에서 누락되는 버그 존재 (#27780)
- OAuth Usage API는 rate limiting이 심함 → 캐싱 필수 (5분 TTL 권장)