---
title: Usage
description: Sume 사용량 원장 항목과 크레딧 잔액을 확인하는 방법을 살펴보세요.
---

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

```text
GET /v1/balance
GET /v1/usage
```

정확한 스키마는 라이브 [OpenAPI](https://api.sume.com/reference/json)에
있습니다.

## 잔액

```bash
curl https://api.sume.com/v1/balance \
  -H "Authorization: Bearer $SUME_API_KEY"
```

```json
{
  "data": {
    "balance": {
      "available_credits": 12480,
      "state": "funded",
      "updated_at": "2026-10-12T09:30:00.000Z",
      "expiration": {
        "next_expires_at": "2026-11-01T00:00:00.000Z",
        "next_expiring_credits": 1800,
        "expiring_soon_days": 30,
        "expiring_soon_credits": 1800
      }
    }
  }
}
```

| 필드 | 의미 |
|---|---|
| `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`일 안에 만료되는 크레딧입니다. |

## 사용량 원장

```bash
curl https://api.sume.com/v1/usage \
  -H "Authorization: Bearer $SUME_API_KEY"
```

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

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

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

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

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

```bash
curl "https://api.sume.com/v1/usage?run_id=arun_…&limit=50" \
  -H "Authorization: Bearer $SUME_API_KEY"
```

응답에 `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 요금표](https://www.sume.com/pricing/api)에
있습니다. 여기에 중복해서 싣지 않습니다.

플랜 변경과 크레딧 구매는
[Billing & subscription](https://www.sume.com/dashboard/subscription)에서
처리하세요. 크레딧의 동작 방식은 [결제와 크레딧](/dashboard/credits)에서
살펴보세요.