본문으로 건너뛰기
GET/usage

월별 사용량 조회

모델별, API 키별 월간 요청 수와 비용 조회

관리 API 키가 연결된 스페이스의 KST 월별 사용량 조회 방법과 USD 비용을 포함한 응답 필드를 설명합니다.

페이지 목차

요청 준비하기

관리 API 키가 연결된 스페이스의 사용량을 조회합니다.

현재 관리 API로는 일별 사용량이나 고객 작업별 비용을 조회할 수 없습니다. 호출 한 건의 비용, 일별 집계, 잔액과 납부 내역을 어디서 확인하는지는 요금과 사용량 안내에 정리돼 있습니다. 현재 잔액은 유닛 잔액 조회로 조회합니다.

  • 요청 주소: https://openapi.letsur.ai/v1 아래의 엔드포인트입니다.
  • 인증: 요청의 Authorization 헤더에 관리 API 키를 넣습니다. AI 게이트웨이 API 키로는 호출할 수 없습니다. 키는 관리 API 키 준비와 보관 방법에 따라 준비합니다.
  • 조회할 달: cURL 예시의 month=2026-08 부분을 조회할 KST 월(YYYY-MM)로 바꾸세요.
  • 클라이언트 생성용 JSON: OpenAPI 스키마 가져오기에서 받습니다.
OpenAPI v2026.11.20, 공개 문서 기준문서용 JSON 열기

요청 파라미터

month쿼리
string | null

조회할 월을 KST 기준 YYYY-MM 형식으로 입력합니다. 생략하면 현재 월을 조회합니다.

패턴 ^\d{4}-(?:0[1-9]|1[0-2])$

응답

200성공 응답
  • periodStartstring필수

    집계 기간의 시작 시각입니다.

    형식 date-time
  • periodEndstring필수

    집계 기간의 종료 시각입니다.

    형식 date-time
  • totalCostUsagestring필수

    집계 기간의 총비용입니다. 미국 달러(USD) 금액을 10진수 문자열로 반환합니다.

    패턴 ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
  • totalRequestCountinteger필수

    집계 기간의 총 요청 수입니다.

  • activeVirtualKeyCountinteger필수

    집계 기간에 사용된 AI 게이트웨이 API 키 수입니다.

  • costsByModelarray<object>필수

    모델별 비용과 요청 수입니다.

    • modelstring필수

      요청에 사용한 모델 코드입니다.

    • coststring필수

      해당 항목의 미국 달러(USD) 비용입니다. 10진수 문자열로 반환합니다.

      패턴 ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
    • requestCountinteger필수

      해당 항목의 요청 수입니다.

  • costsByVirtualKeyarray<object>필수

    AI 게이트웨이 API 키별 비용과 요청 수입니다.

    • virtualKeyNamestring필수

      AI 게이트웨이 API 키 이름입니다.

    • creatorNicknamestring | null

      API 키를 만든 사람의 닉네임입니다. null이거나 응답에서 생략될 수 있습니다.

    • coststring필수

      해당 항목의 미국 달러(USD) 비용입니다. 10진수 문자열로 반환합니다.

      패턴 ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
    • requestCountinteger필수

      해당 항목의 요청 수입니다.

422요청 검증 오류
  • detailarray<object>

    요청 검증에 실패한 항목 목록입니다.

    • locarray<string | integer>필수

      오류가 발생한 요청 위치입니다.

    • msgstring필수

      오류 설명입니다.

    • typestring필수

      오류 유형입니다.

조회 기간과 비용 단위

집계 기간 확인하기

HTTP 200을 받으면 periodStart와 periodEnd로 집계 기간을 확인합니다.

USD 비용 읽기

월별 USD 비용은 KRW 청구액이나 납부 금액과 다릅니다. 청구액과 납부 금액에는 VAT와 계약상 정산 조정 등이 반영됩니다.

콘솔의 unit 사용량과 대조할 때는 조회 기간과 대상이 같은지, 사용량 반영이 끝났는지 확인하세요. 값이 다르다면 기간과 단위 비교 조건을 확인합니다.

키별 비용 읽기

costsByVirtualKey 응답에는 키의 고유 ID가 없습니다. 키 이름(virtualKeyName)이나 닉네임(creatorNickname)만으로 다른 시스템의 키와 같은 키라고 판단해 연결하지 마세요.

오류와 복구

  • 422를 받으면 응답 detail 배열의 각 항목에서 loc와 msg로 검증에 실패한 위치와 이유를 확인합니다. month를 지정했다면 YYYY-MM 형식과 월 값이 올바른지 확인하고 요청을 수정합니다.
  • 인증에 실패했다면 관리 API 인증의 확인 항목에 따라 요청 주소와 관리 API 키, Bearer 헤더를 확인합니다. 최근 관리 API 키를 재발급했다면 이전 키는 즉시 무효화되므로 연동에 새 키가 설정됐는지 확인합니다.