Skip to main content
GET
  • 보유한 모든 API Key의 요청별 Token 소비량과 비용을 조회하거나 단일 Key로 필터링
  • 입력, 출력, 캐시 히트 Token을 각각 집계
  • 요약 엔드포인트로 Key별 합계 제공
  • 커서 기반 페이지네이션, 기간은 최대 31일
이 엔드포인트들은 과금 로그를 읽어 과금된 각 요청의 Token 내역과 비용, 그리고 Key별 집계를 반환합니다. 단일 Key의 총 잔액만 반환하는 토큰 잔액 조회를 보완합니다.

인증

string
필수
이 엔드포인트는 sk- API Key가 아닌 사용자 계정으로 인증합니다.
  1. 계정 설정 페이지를 열고 “시스템 액세스 토큰” 카드에서 생성을 클릭해 액세스 토큰을 발급합니다(sk- 키가 아님). 다시 생성하면 이전 토큰은 무효화됩니다.
  2. 액세스 토큰과 사용자 ID를 함께 전송합니다:
숫자 형태의 사용자 ID는 같은 설정 페이지에 표시됩니다.
string
필수
숫자 형태의 사용자 ID. 액세스 토큰과 함께 필수입니다.

엔드포인트

쿼리 파라미터

두 엔드포인트 모두 동일한 파라미터를 받습니다. 정의되지 않았거나 중복된 파라미터는 422로 거부됩니다.
integer
필수
기간 시작, Unix 초 타임스탬프(해당 시각 포함).
integer
필수
기간 종료, Unix 초 타임스탬프(해당 시각 미포함). start_timestamp보다 커야 하며 기간은 최대 31일입니다.
integer
선택. 숫자 토큰 ID로 단일 API Key를 지정합니다. 생략하면 모든 Key가 포함됩니다.
integer
기본값:"50"
페이지당 행 수, 1–100.
string
이전 응답의 meta.next_cursor로 반환된 페이지네이션 커서. 생성된 것과 동일한 엔드포인트, 기간, token_id 필터에서만 유효합니다.

응답

GET /api/usage/tokens/requests는 과금된 요청마다 한 행을 최신 순으로 반환합니다.
integer
요청에 대응하는 내부 로그 ID. 응답 내에서 고유합니다.
integer
요청이 과금된 시각, Unix 초 타임스탬프.
integer
요청을 수행한 API Key ID.
string
API Key 이름.
string
요청을 처리한 모델.
string
비동기 요청(이미지/비디오 생성)의 태스크 ID. 동기 요청에서는 비어 있습니다.
integer
과금된 입력 Token 수.
integer
과금된 출력 Token 수.
integer | null
캐시에서 읽은 입력 Token 수(캐시 히트). 업스트림이 보고하지 않으면 null입니다.
integer | null
캐시에 기록된 Token 수. 보고되지 않으면 null입니다.
integer | null
업스트림 프로바이더가 보고한 총 Token 수(있는 경우).
integer
prompt_tokens + completion_tokens.
string
pre_consumed, settled, 또는 상세 과금 메타데이터 이전의 로그는 unknown.
integer
소비된 쿼터(플랫폼 내부 단위).
string
미국 달러로 환산한 비용. quota / quota_per_usd로 계산합니다(meta 참조). 정밀도 유지를 위해 문자열로 반환합니다.
GET /api/usage/tokens/summary는 API Key별로 한 행을 token_id 오름차순으로 반환합니다.
integer
API Key ID.
integer
기간 내 과금 요청 수.
integer
이 Key의 입력 Token 합계.
integer
이 Key의 출력 Token 합계.
integer
prompt_tokens + completion_tokens.
integer
이 Key가 소비한 쿼터 합계.
string
이 Key의 미국 달러 비용 합계.

Meta

boolean
다음 페이지가 있는지 여부.
string
cursor로 전달하면 다음 페이지를 가져옵니다. has_more가 false이면 비어 있습니다.
string
cost_usd 환산에 사용된 미국 달러당 내부 쿼터 단위 수.
boolean
소비 로깅 활성화 여부. false이면 응답이 비어 있을 수 있습니다.
boolean
현재 항상 false이며 환불 금액은 차감되지 않습니다.

참고 사항

  • 과금된 요청만 표시됩니다. 과금되지 않은 실패 요청은 나타나지 않으며, 요청별 성공 여부 필드도 반환되지 않습니다.
  • 비용은 과금 시점에 기록된 쿼터를 기준으로 하며 현재 카탈로그 가격으로 재계산되지 않고, 환불도 차감되지 않습니다.
  • 이 엔드포인트들은 원본 API Key, 채널, IP 주소, 요청/응답 내용을 노출하지 않습니다.
  • cursor는 엔드포인트, 기간, token_id 필터에 바인딩되므로 다른 쿼리 간에 재사용하지 마세요.
  • 쿼리는 짧은 시간 제한이 있습니다. query_timeout이 반환되면 기간을 줄여서 다시 시도하세요.