Usage

이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.

Usage 대시보드를 열면 크레딧을 사용하는 Developer API 활동을 사람이 보기 좋게 요약해서 볼 수 있습니다. 모든 수치는 크레딧 단위입니다. 프로그래밍 방식으로는 다음에서 사용량을 읽습니다.

정확한 스키마는 라이브 OpenAPI에 있습니다.

잔액

필드	의미
`available_credits`	워크스페이스가 지금 사용할 수 있는 크레딧이며, 정수입니다.
`state`	크레딧이 있으면 `funded`, 없으면 `empty`입니다.
`updated_at`	잔액이 마지막으로 바뀐 시각입니다.
`expiration.next_expires_at`	다음 크레딧이 만료되는 시각이거나 `null`입니다.
`expiration.next_expiring_credits`	`next_expires_at`에 만료되는 크레딧입니다.
`expiration.expiring_soon_days`, `expiration.expiring_soon_credits`	앞으로 `expiring_soon_days`일 안에 만료되는 크레딧입니다.

사용량 원장

사용량 항목에는 워크스페이스와 환경에 따라 예약, 확정, 반환, 크레딧 구매, 그랜트가 포함될 수 있습니다. 각 행은 크레딧 수를 credits로 알려 줍니다.

상태	의미
`reserved`	프로바이더 실행 전에 추정 크레딧을 예약했습니다.
`captured`	성공적으로 완료된 뒤 크레딧을 확정했습니다.
`refunded`	확정 전에 실패하거나 취소되어 예약한 크레딧을 되돌려줬습니다.

Job ID와 request id로 사용량 행과 생성 워크플로를 연결하세요.

스레드 하나, run 하나, Job 하나

thread_id, run_id, job_id를 붙이면 Studio Agent 스레드 하나, Format / Action / Agent run 하나, 생성 Job 하나가 정확히 몇 크레딧을 사용했는지 합산합니다.

응답에 summary가 추가되며, 해당 범위가 만든 모든 원장 행을 접어서 계산합니다(limit은 나열되는 행 수만 제한합니다).

필드	의미
`debited_credits`	지갑에서 실제로 차감된 크레딧: 확정된 행, 모든 operation type(에이전트 자체 턴 포함). 인용할 숫자입니다.
`held_credits`	아직 열려 있는 예약(`pending_*`로 보류된 행 포함). 아직 사용한 크레딧이 아닙니다.
`pending_credits`	`held_credits` 가운데 정산을 기다리며 `pending_*`로 보류된 행의 몫입니다.
`refunded_credits`	실패, 취소, `queue_full` 뒤 Sume가 되돌려준 예약. 사용되지 않은 크레딧입니다.
`final`	열려 있는 예약이 없으면 `true`입니다.
`hold_counts`, `holds`	열린 예약이 무엇을 기다리는지, 그리고 가장 최근 예약들입니다. 예약마다 `credits`가 있습니다.
`includes`	종류별 행 수: LLM 턴, 사이드카, Browser 세션, 생성 Job, `script_run_children`(`script_run` 호출이 만든 Job), 반환된 행, BYOK 행.
`script_runs`	범위 안의 `script_run` 호출별 행 수와 크레딧.
`by_operation_type`, `runs`	같은 크레딧을 operation type별로, 스레드라면 run별로 나눈 값.
`cap`	run의 경우: `limit_credits`(run의 generation cap), `counted_credits`(cap에 산입되는 크레딧: 예약 + 확정 생성 행, LLM 제외. receipt의 `usage.cap.counted_credits`와 같습니다), `remaining_credits`. `counted_credits`는 run의 전체 크레딧이 아닙니다. 전체는 `debited_credits`를 인용하세요.

행은 원장 id를 그대로 갖고 이제 thread_id, run_id, turn_job_id(그 Job을 만든 에이전트 턴), script_run_id / script_run_call_index(script_run이 만든 경우), settle_state도 포함합니다. job_id에 턴의 job id를 넣으면 턴 자체의 행과 그 턴이 만든 모든 Job을 합산합니다. 행을 직접 더하지 말고 summary를 읽으세요. 반환된 행은 예약했던 크레딧을 credits에 그대로 유지합니다.

Job의 크레딧

GET /v1/jobs, GET /v1/jobs/{id}, GET /v1/jobs/{id}/result는 Job마다 usage_summary를 줍니다.

필드	의미
`status`	`reserved`, `captured`, `refunded` 중 하나입니다.
`reserved_credits`	Job을 접수할 때 Sume가 예약한 크레딧입니다.
`captured_credits`	Job이 사용한 크레딧입니다.
`refunded_credits`, `released_credits`	Sume가 잔액으로 되돌려준 크레딧입니다.
`final`	이 숫자들이 더 이상 바뀌지 않으면 `true`입니다.

기능마다 사용하는 크레딧은 API 요금표에 있습니다. 여기에 중복해서 싣지 않습니다.

플랜 변경과 크레딧 구매는 Billing & subscription에서 처리하세요. 크레딧의 동작 방식은 결제와 크레딧에서 살펴보세요.