월별 사용량 조회

모델별, 가상 키별 요청 수와 비용을 포함한 월별 누적 사용량을 조회합니다.

조회 월은 KST 기준이며 비용은 USD 10진수 문자열로 반환합니다.

OpenAPI v0.0.2-dev3 · 공개 문서 기준문서용 JSON 열기

요청 파라미터

month쿼리: string | null
조회할 월을 KST 기준 YYYY-MM 형식으로 입력합니다. 생략하면 현재 월을 조회합니다.
패턴 ^\d{4}-(?:0[1-9]|1[0-2])$

응답

200성공 응답

periodStartstring필수
집계 기간의 시작 시각입니다.
형식 date-time
periodEndstring필수
집계 기간의 종료 시각입니다.
형식 date-time
totalCostUsagestring필수
집계 기간에 사용한 총비용입니다. 10진수 문자열로 반환합니다.
패턴 ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
totalRequestCountinteger필수
집계 기간의 총 요청 수입니다.
activeVirtualKeyCountinteger필수
집계 기간에 사용된 가상 키 수입니다.
costsByModelarray<object>필수
모델별 비용과 요청 수입니다.
- modelstring필수
  요청에 사용한 모델 코드입니다.
- coststring필수
  해당 항목의 비용입니다. 10진수 문자열로 반환합니다.
  패턴 ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
- requestCountinteger필수
  해당 항목의 요청 수입니다.
costsByVirtualKeyarray<object>필수
가상 키별 비용과 요청 수입니다.
- virtualKeyNamestring필수
  AI 게이트웨이 API 키 이름입니다.
- creatorNicknamestring | null
  가상 키 생성자의 닉네임입니다. 값이 없으면 null입니다.
- coststring필수
  해당 항목의 비용입니다. 10진수 문자열로 반환합니다.
  패턴 ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
- requestCountinteger필수
  해당 항목의 요청 수입니다.

422요청 검증 오류

detailarray<object>
요청 검증에 실패한 항목 목록입니다.
- locarray<string | integer>필수
  오류가 발생한 요청 위치입니다.
- msgstring필수
  오류 설명입니다.
- typestring필수
  오류 유형입니다.

코드 예시

요청 예시

curl 'https://openapi.letsur.ai/v1/usage?month=2026-08' \
  --header 'Authorization: Bearer mk_...'

200 응답 예시

{
  "periodStart": "2026-08-01T00:00:00+09:00",
  "periodEnd": "2026-08-31T23:59:59+09:00",
  "totalCostUsage": "0.00",
  "totalRequestCount": 12,
  "activeVirtualKeyCount": 12,
  "costsByModel": [
    {
      "model": "gpt-4.1-mini",
      "cost": "0.00",
      "requestCount": 12
    }
  ],
  "costsByVirtualKey": [
    {
      "virtualKeyName": "production",
      "creatorNickname": "홍길동",
      "cost": "0.00",
      "requestCount": 12
    }
  ]
}

예시는 스키마의 형식을 설명하기 위한 값이며 실제 계정 데이터가 아닙니다.

관리 API 키를 보내는 방법은 인증, 문서에서 검증한 기계 판독용 스키마는 OpenAPI 스키마에서 확인합니다.