Usage API (account)

자체 internal dashboard / 알림 / 월간 리포트에 사용할 수 있는 programmatic 쿼터 사용량 조회. /api/auth/me/usage.

Last updated: 2026-04-27

자기 account 의 quota 사용량과 trial 상태를 프로그래밍 방식으로 조회합니다. Stripe / Twilio / OpenAI 와 동일한 패턴 — institutional buyer 가 자체 internal dashboard / 알림 / 월간 리포트에 통합하기 위한 surface 입니다.

GET /api/auth/me/usage

인증

세션 쿠키 (Syncle SSO) 만 받습니다. API key 인증은 사용하지 않습니다.
로그인된 사용자의 가장 높은 plan 을 가진 active consumer 1개를 반환 (team > pro > internal > starter 우선순위).

요청

bash

curl https://veacon.io/api/auth/me/usage \
  -H "Cookie: veacon_session=<your_session_jwt>"

응답

json

{
  "data": {
    "plan": "team",
    "limits": {
      "monthly_request_quota": 100000,
      "rate_limit_per_minute": 1000
    },
    "current_period": {
      "month": "2026-04",
      "starts_at": "2026-04-01T00:00:00Z",
      "resets_at": "2026-05-01T00:00:00Z",
      "requests_used": 1742,
      "requests_remaining": 98258,
      "percent_used": 1.74
    },
    "trial": {
      "is_active": true,
      "trial_ends_at": "2027-04-25T00:00:00Z",
      "days_remaining": 363,
      "founding_member": true
    },
    "subscription": {
      "status": "trialing"
    }
  },
  "meta": {
    "request_id": "01J3X...",
    "timestamp": "2026-04-27T10:00:00Z"
  }
}

필드 설명

경로	타입	설명
`plan`	string	현재 tier (`starter` / `pro` / `team` / `enterprise` / `internal`)
`limits.monthly_request_quota`	int	월 호출 한도. 한도 초과 시 `402 QUOTA_EXCEEDED`.
`limits.rate_limit_per_minute`	int	분당 호출 한도. Upstash sliding window.
`current_period.month`	string	`YYYY-MM` (UTC 기준)
`current_period.starts_at`	string	현재 빌링 주기 시작. 매 월 1일 00:00 UTC.
`current_period.resets_at`	string	다음 리셋 (= `starts_at + 1 month`).
`current_period.requests_used`	int	이번 달 누적 (2xx 응답만 카운트).
`current_period.requests_remaining`	int	`quota - used`, 음수는 0 으로 클램프.
`current_period.percent_used`	float	0–100 (소수점 2자리).
`trial`	object \| null	trial 상태가 있을 때만 존재. 그 외 `null`.
`trial.is_active`	bool	`trial_ends_at > now` 일 때 `true`.
`trial.days_remaining`	int	만료까지 남은 일수 (올림). 만료 후 0.
`trial.founding_member`	bool	ADR-016 founding cohort 1 멤버 표식. 평생 유지.
`subscription.status`	string \| null	Stripe subscription status (`trialing` / `active` / `past_due` / `canceled` / `unpaid`). subscription 없는 starter consumer 는 `null`.

에러

HTTP	code	의미
401	`NOT_SIGNED_IN` / `JWT_INVALID`	세션 쿠키 없음 또는 만료.
404	`NO_CONSUMER`	로그인은 됐지만 active consumer 가 없음 (provisioning 직전 상태).
500	`USAGE_FAILED`	RPC 에러. drift 발생 가능성 — `request_id` 와 함께 hello@veacon.io 로 신고.

일반 use case

1. Internal dashboard 사용량 위젯

javascript

// React 예시 — useEffect 에서 polling 30s 간격
const r = await fetch('/api/auth/me/usage', { credentials: 'include' });
const { data } = await r.json();
return <UsageGauge percent={data.current_period.percent_used} remaining={data.current_period.requests_remaining} />;

2. 80% 도달 알림 — webhook 대체 (현재 deferred)

quota.warning_80pct webhook 은 v1 에 미구현. 그 동안 cron 으로 polling:

python

# 매 시간 cron 으로 — Slack 알림
import httpx, os

resp = httpx.get('https://veacon.io/api/auth/me/usage',
                 cookies={'veacon_session': os.environ['VEACON_SESSION']})
data = resp.json()['data']
if data['current_period']['percent_used'] >= 80:
    notify_slack(f"Veacon quota 80% 초과: {data['current_period']['requests_used']}/{data['limits']['monthly_request_quota']}")

3. Trial countdown 알림