사용량 조회 API
BizRouter 사용량 API는 조직의 과금 상태, 일별 사용량 집계, 요청 로그 메타데이터를 외부 모니터링 시스템이나 사내 리포팅 도구에서 조회할 수 있는 전용 API입니다.
기본 정보
사용량 API의 Base URL과 인증 방식 Base URL 전용 키 사용 사용량 API는 모델 호출용 API 키( sk-br-v1- )가 아니라 사용량 조회 전용 키( sk-br-usage-v1- )로 인증합니다.
엔드포인트
외부 시스템에서 조회할 수 있는 Usage API 목록 Endpoint 용도 주요 활용 GET /api-keys 모델 호출용 API 키 목록 조회 UUID 확인, 사용량 필터 준비 GET /billing 조직의 크레딧과 과금 상태 조회 잔액 모니터링, 월 사용액 알림 GET /usage 기간별 사용량 집계 조회 일별 리포트, API 키/모델별 비용 분석 GET /logs 요청 로그 메타데이터 조회 운영 감사, 장애 분석, 요청 추적
사용량 API 키 발급
Owner 권한이 있는 사용자만 키를 만들고 관리할 수 있습니다.
사용량 API 키 발급 · 발급 절차
BizRouter 대시보드에 로그인합니다. 설정 > API 연동 > 사용량 조회 API 메뉴로 이동합니다. 키 만들기 를 누르고 연동 목적을 알 수 있는 이름을 입력합니다. 생성된 전체 키를 안전한 비밀 저장소에 보관합니다. 전체 키는 생성 직후 한 번만 표시됩니다.
사용량 API 키 발급 · 관리 정책
조직당 최대 3개의 활성 사용량 API 키를 만들 수 있습니다. 목록에서는 키 이름, 미리보기, 마지막 사용일, 만든 사람을 확인할 수 있습니다. 키별로 허용 IP 또는 CIDR을 최대 32개까지 등록할 수 있습니다. 허용 IP를 등록하지 않은 키는 모든 IP에서 사용할 수 있습니다. 키 이름은 수정할 수 있지만, 전체 키는 다시 조회할 수 없습니다. 삭제된 키는 즉시 비활성화되며 이후 인증에 사용할 수 없습니다. 키 원문은 저장하지 않고 해시(hash)로만 보관됩니다. 운영 권장사항 운영 시스템에서 키를 교체할 때는 새 키를 먼저 배포한 뒤 기존 키를 삭제하십시오. 삭제 후에는 같은 키를 복구하거나 다시 확인할 수 없습니다. Usage API Key도 browser, mobile app, frontend bundle에 포함하지 말고 backend secret으로 보관하십시오.
인증
모든 사용량 API 요청에는 Bearer token 인증이 필요합니다.
인증 · 인증 실패
인증 헤더가 없거나, 키가 잘못되었거나, 삭제된 키를 사용하면 401 Unauthorized 가 반환됩니다. 허용 IP가 설정된 키를 허용되지 않은 IP에서 호출하면 403 Forbidden 이 반환됩니다. 성공적으로 인증된 요청만 해당 키의 마지막 사용 시간이 갱신됩니다.
모델 호출 API 키 목록 조회
사용량과 요청 로그를 특정 API 키로 필터링할 때 필요한 UUID를 조회합니다.
모델 호출 API 키 목록 조회 · Request
GET /api-keys 요청입니다. 삭제되지 않은 모델 호출용 API 키를 반환하며, 비활성 키도 기본적으로 포함합니다. page 조회할 페이지 값: 기본값 1 limit 페이지당 API 키 수 값: 1-100, 기본값 20 search API 키 이름 또는 preview 검색 값: 문자열 is_active 활성 상태 필터 값: true, false
모델 호출 API 키 목록 조회 · Response
응답의 items[].id 값을 api_key_id 필터에 사용합니다. API 키 원문이나 hash는 반환하지 않습니다. credit_limit 은 키에 설정된 사용 한도(KRW)입니다. credit_limit_period 는 한도 기간( lifetime , daily , monthly )이며, limit_period_usage_krw 는 해당 기간의 사용량, limit_period_start_date 와 limit_period_end_date 는 기간의 시작일과 마지막 날짜(포함)입니다. 한도를 설정하지 않은 키는 이 네 필드가 모두 null 입니다. usage_attribution_enabled 는 키에서 사용량 귀속 헤더를 기록하도록 켜져 있는지, require_usage_subject 와 require_usage_group 은 해당 헤더가 없는 요청을 거절하도록 설정되어 있는지를 true 또는 false 로 알려 줍니다. 헤더를 보냈는데 요청 로그의 귀속 칸이 비어 있으면 먼저 이 값을 확인하십시오. 사용량에는 모델 호출 사용량과 Corepin 사용량이 모두 포함되며, 한도 대비 사용률은 limit_period_usage_krw / credit_limit 로 계산합니다.
사용량 조회
일별 또는 전체 기간 기준으로 토큰, 요청 수, 비용을 집계합니다.
사용량 조회 · Request
GET /usage 요청입니다. Request body는 사용하지 않고, 조회 조건은 query parameter로 전달합니다. cURL Node.js
사용량 조회 · Query parameters
날짜를 생략하면 최근 30일 기준으로 조회합니다. start_date 조회 시작일 값: YYYY-MM-DD end_date 조회 종료일 값: YYYY-MM-DD granularity 응답 집계 단위 값: day, total group_by 집계 차원. 쉼표로 여러 값을 지정할 수 있습니다. 값: api_key, model, source, is_byok, usage_subject, usage_group api_key_id 특정 모델 호출 API 키로 필터링합니다. 생략하면 조직 전체를 조회하며, GET /api-keys 응답의 ID를 사용합니다. 값: UUID model_code 특정 모델 코드로 필터링 예: openai/gpt-5.6-sol source_type 사용 출처 필터 값: api_key, model_test is_byok BYOK 사용 여부 값: true, false usage_subject 요청에 기록된 Usage Subject로 필터링 예: customer-user-123 usage_group 요청에 기록된 Usage Group으로 필터링 예: customer:acme 조회 범위 /usage 는 최대 1년까지 조회할 수 있습니다. 날짜를 생략하면 최근 30일 기준으로 조회합니다. 최근 요청 반영 시간 요청 로그와 일별 집계는 처리 시점 차이로 최근 요청이 잠시 늦게 보일 수 있습니다. 즉시 대조가 필요하면 요청에 보낸 X-BizRouter-Client-Request-Id 를 보관하고 잠시 후 다시 조회하십시오.
사용량 조회 · Response
기간 합계는 totals 에, 그룹별 집계는 items 에 반환됩니다.
과금 상태 조회
현재 조직의 크레딧, 월 사용액, 충전/환불 누계를 확인합니다.
과금 상태 조회 · Request
GET /billing 요청입니다. Request body와 query parameter는 사용하지 않습니다.
과금 상태 조회 · Query parameters
없음
과금 상태 조회 · Response
선불 조직은 보유 크레딧과 현재 월 사용액을, 후불 조직은 미청구 사용액을 함께 반환합니다.
요청 로그 조회
프롬프트와 응답 본문을 제외한 요청 메타데이터를 조회합니다.
요청 로그 조회 · Request
GET /logs 요청입니다. Request body는 사용하지 않고, 조회 조건과 pagination cursor는 query parameter로 전달합니다.
요청 로그 조회 · Query parameters
시간을 생략하면 최근 24시간 기준으로 조회합니다. start_time 조회 시작 시각 값: ISO datetime end_time 조회 종료 시각 값: ISO datetime limit 페이지당 로그 수 값: 1-1000 cursor 다음 페이지 조회용 cursor 값: next_cursor api_key_id 특정 모델 호출 API 키로 필터링합니다. 생략하면 조직 전체를 조회하며, GET /api-keys 응답의 ID를 사용합니다. 값: UUID model_code 특정 모델 코드로 필터링 예: openai/gpt-5.6-sol status 요청 성공 여부 값: success, failure response_type 보안 처리 결과 값: normal, sensitive, blocked app_name 요청에 기록된 애플리케이션 이름 값: X-Title user_id 특정 사용자로 필터링 값: UUID usage_subject Usage Subject가 일치하는 요청만 조회 예: customer-user-123 usage_group Usage Group이 일치하는 요청만 조회 예: customer:acme client_request_id 고객 시스템의 request ID로 조회 값: req-20260518-001 민감 정보 보호 /logs 응답에는 요청 프롬프트나 모델 응답 본문이 포함되지 않습니다. 비용, 토큰, 모델, 상태, 지연 시간 같은 운영 메타데이터만 반환합니다. 로그 조회 범위는 최대 31일입니다.
요청 로그 조회 · Response
최신 로그부터 반환되며, 다음 페이지가 있으면 next_cursor 를 다음 요청의 cursor 로 전달합니다.