Usage & Activity

프로그래매틱 사용량 리포트와 대시보드 사용량·활동 내역을 조회합니다. 모두 본인 계정 데이터만 반환합니다.

아래 프로그래매틱 리포트를 제외한 이 페이지의 엔드포인트들은 로그인 세션(JWT)으로 인증되며, 항상 본인 계정으로 범위가 제한됩니다 — 대시보드에서 사용하는 인증입니다. 모든 응답의 cost_krw는 실제 청구된 원화 금액이며, 마진 등 내부 산정 항목은 노출되지 않습니다.

프로그래매틱 리포트#

GET/v1/usage/report

계정 전체 사용량을 축(모델 · 프로바이더 · API 키 · 일자)별로 집계해 반환합니다. 사내 모니터링 · 리포팅 자동화를 위한 read-only API로, 항목은 cost_krw 내림차순으로 정렬됩니다.

이 엔드포인트만 JWT가 아닌 usage:read 스코프를 가진 plm_ API 키로 인증합니다 (Authorization: Bearer plm_...). 스코프가 없는 키는 403이 반환됩니다. usage:read만 있는 키는 모델 호출(과금)이 거부되므로, 지출 권한 없이 리포팅만 안전하게 위임할 수 있습니다 — 키의 IP allowlist도 그대로 적용됩니다.

파라미터	타입	필수	설명
group_by	string	선택	`model` \| `provider` \| `api_key` \| `day`. 기본값 `model`.
days	integer	선택	집계 기간(일). 1 ~ 365, 기본값 30.

request

curl "https://router.pleum.ai/v1/usage/report?group_by=model&days=30" \
  -H "Authorization: Bearer plm_..."

200 OK

{
  "group_by": "model",
  "days": 30,
  "items": [
    {
      "key": "gpt-4o",
      "cost_krw": 48200,
      "input_tokens": 8120000,
      "output_tokens": 912000,
      "calls": 1420
    },
    {
      "key": "claude-sonnet-4-6",
      "cost_krw": 31900,
      "input_tokens": 4210000,
      "output_tokens": 640000,
      "calls": 610
    }
  ]
}

key는 group_by 축의 값(모델 ID · 프로바이더 ID · API 키 ID · 날짜)입니다. 집계 범위는 키 소유자 계정의 전체 사용량이며, 해당 키로 발생한 호출만이 아닙니다.

사용량 요약#

GET/v1/usage/summary

최근 24시간 합계(calls_24h · cost_24h_krw), 최근 7일 일별 추이(cost_by_day), 최근 30일 상위 5개 모델 (cost_by_model)을 한 번에 반환합니다.

200 OK

{
  "calls_24h": 142,
  "cost_24h_krw": 3870,
  "cost_by_day": [
    {"date": "2026-06-26", "cost_krw": 1200, "calls": 40}
  ],
  "cost_by_model": [
    {"model": "gpt-4o", "cost_krw": 2600, "calls": 88}
  ]
}

호출 로그#

GET/v1/usage/requests

개별 호출 내역을 페이지 단위로 반환합니다. 각 항목에는 토큰 사용량, cost_krw(청구액), BYOK 여부와 수수료, 지연시간, 상태 코드, 오류 메시지가 포함됩니다.

파라미터	타입	필수	설명
period	string	선택	`1d` \| `7d` \| `30d` \| `90d`. 생략 시 전체 기간.
model	string	선택	특정 모델 ID로 정확히 일치 필터링.
outcome	string	선택	`success` \| `error`. 결과로 필터링.
page	integer	선택	1 이상. 기본값 1.
size	integer	선택	1 ~ 100. 기본값 30.

200 OK

{
  "items": [
    {
      "id": "a1b2c3d4-...",
      "request_id": "req_5f8e...",
      "model": "gpt-4o",
      "provider": "openai",
      "input_tokens": 1240,
      "output_tokens": 312,
      "total_tokens": 1552,
      "cache_read_tokens": 1024,
      "cost_krw": 58,
      "is_byok": false,
      "byok_fee_krw": 0,
      "latency_ms": 1841,
      "status_code": 200,
      "error_message": null,
      "created_at": "2026-06-26T08:14:02Z"
    }
  ],
  "total": 142,
  "page": 1,
  "size": 30
}

의도 분류 분포#

GET/v1/usage/classifications

Smart Mode가 분류한 요청 의도의 분포를 반환합니다. 건수만 집계하며, 프롬프트 본문은 저장하거나 노출하지 않습니다. 카테고리는 vision · code · translation · creative · reasoning · general입니다.

파라미터	타입	필수	설명
period	string	선택	`1d` \| `7d` \| `30d` \| `90d`. 생략 시 전체 기간.

200 OK

{
  "items": [
    {"category": "code", "count": 42},
    {"category": "reasoning", "count": 17},
    {"category": "general", "count": 9}
  ],
  "total": 68
}

Smart Mode 데이터가 쌓이기 전에는 items가 비어 있을 수 있습니다.

활동 로그#

GET/v1/usage/audit-log

최근 보안·활동 이벤트(API 키 발급, 관리 키 발급 등)를 반환합니다. 각 이벤트에는 event_type, severity, resource_type, detail이 포함됩니다.

파라미터	타입	필수	설명
limit	integer	선택	반환할 이벤트 수. 기본값 50, 최대 200.

200 OK

{
  "events": [
    {
      "id": "e7d6...",
      "event_type": "key_created",
      "severity": "info",
      "resource_type": "api_key",
      "detail": "Created key \"prod-server\"",
      "created_at": "2026-06-26T07:55:11Z"
    },
    {
      "id": "f1a2...",
      "event_type": "management_key_created",
      "severity": "info",
      "resource_type": "management_key",
      "detail": "Created management key",
      "created_at": "2026-06-25T22:03:40Z"
    }
  ]
}