> Source: https://clickhouse.github.io/loom/ko/reference/operations/cost/ (Markdown: https://clickhouse.github.io/loom/ko/reference/operations/cost.md)

<!-- i18n: source=docs/reference/operations/cost.md blob=f8bcf1fd1aead97faf00f604f2c42a7dca73bcda model=claude-sonnet-5-5 -->
> 이 페이지는 [영어 원문](https://clickhouse.github.io/loom/reference/operations/cost/)을 기계 번역한 것이며, 영어 원문이 기준입니다.
> Machine-translated from the [English page](https://clickhouse.github.io/loom/reference/operations/cost/), which is authoritative.

<a id="cost-operations"></a>

# `cost` 작업

각 `cost.*` 작업이 받는 필드와 반환하는 필드를 정확히 설명합니다.

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

모든 op는 HTTP에서는 `POST /v1/<op>`이고 MCP에서는 `loom_<op>` 도구입니다. 식별 필드(`org`, `namespace`, `agent`, `user_id`, `session_id`)는 전송 방식이 지원하는 경우 토큰과 MCP 세션에서 채워집니다. 단일 사용자 서버에서 토큰 없이 HTTP를 호출하면, `code.*`와 `tracker.*`(각자 자신의 플레인을 유지함)를 제외한 모든 op에서 설치의 org가 사용되며, [일부 op](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)에서는 네임스페이스와 에이전트도 채워집니다. 자세한 내용은 [아이덴티티와 네임스페이스](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md)를 참고하세요. [작업 색인](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md)에서 역할, 종류, MCP `all` 목록을 설명합니다. 알 수 없는 입력 필드도 처리되며 `ignored_args`에 이름이 표시됩니다.

<!-- prettier-ignore-start -->

<a id="costagent_summary"></a>

## `cost.agent_summary`

코딩 에이전트 자체의 지출(loom.agent_turn_usage)을 날짜 구간별로 집계합니다. `cost.summary`가 다루지 않는 계열이며, 그쪽은 LOOM이 업스트림에서 지출하는 비용을 산정합니다.

`POST /v1/cost.agent_summary` · MCP `loom_cost_agent_summary` · 역할 `viewer` · 읽기

| 입력 필드 | 타입 | 기본값 | 의미 |
| --- | --- | --- | --- |
| `org` | `str` | 필수 | 테넌트(식별 튜플의 첫 번째 요소). |
| `namespace` | `str \| None` | `None` | op가 읽거나 쓰는 네임스페이스. |
| `from_date` | `date` | 필수 | 구간의 하한(해당 날짜 포함)이며, 각 턴의 UTC 날짜와 비교합니다. |
| `to_date` | `date` | 필수 | 구간의 상한(해당 날짜 포함) |
| `group_by` | `list[Literal['namespace', 'agent', 'day', 'model', 'consumer', 'session_id']]` | `['model']` | GROUP BY에 사용할 차원. |
| `agent` | `str \| None` | `None` | 쓰거나 읽는 에이전트. op가 허용하는 경우 `'-'` 또는 `'*'`는 모든 에이전트를 의미합니다. |
| `consumer` | `str \| None` | `None` | 호출하는 통합(integration)의 태그이며, 원장 행에 기록됩니다. |

| 출력 필드 | 타입 | 의미 |
| --- | --- | --- |
| `rows` | `list[CostAgentSummaryRow]` | `group_by` 차원의 고유한 값마다 한 행이며, 비용이 높은 순으로 최대 5,000개입니다. 호출자가 해당 org에서 읽을 수 있는 네임스페이스가 없으면 비어 있습니다. |
| `total_turns` | `int` | 반환된 행의 `turns` 합계. |
| `total_sessions` | `int` | 고유 세션 수입니다. `session_id`로 그룹화하면 행의 합계이고, 그렇지 않으면 가장 큰 행의 값입니다(세션이 여러 행에 걸치면 하한값). |
| `total_cost_usd` | `float` | 반환된 행의 `cost_usd` 합계(USD). 가격이 없는 턴은 0으로 계산합니다. |
| `unpriced_turns` | `int` | 가격표에 모델이 없는 턴의 수로, 반환된 행 전체에 대해 합산합니다. |

<a id="costbudget_status"></a>

## `cost.budget_status`

이 네임스페이스의 최근 24시간 업스트림 지출을 한도(cap)와 비교해 보여 줍니다.

`POST /v1/cost.budget_status` · MCP `loom_cost_budget_status` · 역할 `viewer` · 읽기

| 입력 필드 | 타입 | 기본값 | 의미 |
| --- | --- | --- | --- |
| `org` | `str` | 필수 | 테넌트(아이덴티티 튜플의 첫 번째 요소)입니다. |
| `namespace` | `str \| None` | `None` | 작업이 읽거나 쓰는 네임스페이스입니다. |
| `user_id` | `str \| None` | `None` | 네임스페이스 내에서 지정한 최종 사용자의 최근 24시간 예산입니다. 생략하면 네임스페이스 합계를 반환합니다. |

| 출력 필드 | 타입 | 의미 |
| --- | --- | --- |
| `namespace` | `str` | 작업이 읽거나 쓰는 네임스페이스입니다. |
| `user_id` | `str \| None` | 선택된 논리적 최종 사용자입니다. 네임스페이스 및 org 합계에서는 None입니다. |
| `spent_24h_usd` | `float \| None` | 최근 24시간 동안의 업스트림 지출(USD)입니다. 사용자 모드에서는 호출자가 네임스페이스 역할 제한이 없는 플랫폼 관리자가 아니면 null을 반환합니다. |
| `cap_usd` | `float` | 적용되는 네임스페이스 또는 지정 사용자의 한도입니다. 네임스페이스 재정의 값이 있으면 그 값을, 없으면 서버 기본값을 사용합니다. 0.0은 한도 없음을 뜻하며, org 전체 집계는 항상 한도가 없습니다. |
| `cap_source` | `Literal['namespace', 'global', 'namespace_user', 'global_user', 'uncapped', 'org']` | 네임스페이스 한도는 `namespace` / `global`, 사용자 한도는 `namespace_user` / `global_user`, 비활성화된 경우 `uncapped`, org 전체 집계는 `org`입니다. |
| `over_cap` | `bool` | 실제 지출이 선택된 한도에 도달하면 True입니다. 지출 값이 숨겨져 있어도 적용되며, org 전체 집계에서는 false입니다. |
| `namespace_over_cap` | `bool \| None` | 사용자 모드에서는 네임스페이스 지출만으로도 새 작업이 독립적으로 차단될 수 있습니다. |
| `pct_of_cap` | `float \| None` | 지출 비율이며 0..1 범위로 제한됩니다. 한도가 없거나 사용자 지출이 숨겨져 있으면 null입니다. |
| `namespaces_with_spend` | `int` | org 전체 모드에서만 사용됩니다. |

<a id="costrecord_turns"></a>

## `cost.record_turns`

코딩 에이전트 자체의 한 세션 지출을 호출당 여러 턴 묶음으로 기록합니다.

`POST /v1/cost.record_turns` · MCP `loom_cost_record_turns` · 역할 `writer` · 멱등 · MCP `all` 툴셋에는 나열되지 않음

| 입력 필드 | 타입 | 기본값 | 의미 |
| --- | --- | --- | --- |
| `org` | `str` | 필수 | 테넌트(식별 튜플의 첫 번째 요소)입니다. |
| `namespace` | `str` | 필수 | op가 읽거나 쓰는 네임스페이스입니다. |
| `agent` | `str` | `'-'` | 쓰거나 읽는 에이전트입니다. `'-'` 또는 `'*'`는 op가 허용하는 경우 모든 에이전트를 의미합니다. |
| `user_id` | `str` | `'-'` | 해당 행이 속한 최종 사용자입니다. 없으면 `'-'`입니다. |
| `session_id` | `str` | 필수 | 해당 행이 속한 세션 또는 대화입니다. 없으면 `'-'`입니다. |
| `consumer` | `str` | `''` | 호출하는 통합(integration)의 태그이며, 원장 행에 기록됩니다. |
| `turns` | `list[TurnUsage]` | 필수 | 기록할 턴으로, 호출당 1~200개입니다. 같은 `message_id`로 다시 보낸 턴은 이전 행을 대체합니다. |

| 출력 필드 | 타입 | 의미 |
| --- | --- | --- |
| `recorded` | `int` | 원장에 기록된 턴 수입니다. 쓰기에 실패하면 0입니다(호출 자체는 성공합니다). |
| `priced` | `int` | 가격표에 모델이 있는 턴 수입니다. 쓰기에 실패하면 0입니다. |
| `unpriced_models` | `list[str]` | 가격표에 없는 모델입니다. 해당 행은 cost_usd=0, priced=false로 기록됩니다. $0을 그대로 믿지 말고 PRICE_PER_1K_TOKENS에 추가하세요. |
| `cost_usd` | `float` | 이 배치에서 가격이 산정된 턴의 총 가격(USD)이며, 소수점 6자리로 반올림됩니다. |
| `turns_dated_ahead` | `int` | 서버 시계보다 5초 넘게 앞선 시각으로 기록된 턴 수입니다. 클라이언트 시계가 앞서 있으므로 실행의 비용 구간에서 해당 턴이 늦게 배치될 수 있습니다. |

<a id="costsummary"></a>

## `cost.summary`

날짜 범위에 대한 비용 집계입니다.

`POST /v1/cost.summary` · MCP `loom_cost_summary` · 역할 `viewer` · 읽기 · MCP `all` 툴셋에 포함되지 않음

| 입력 필드 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `org` | `str` | 필수 | 테넌트(식별 튜플의 첫 번째 요소)입니다. |
| `namespace` | `str \| None` | `None` | op가 읽거나 쓰는 네임스페이스입니다. |
| `from_date` | `date` | 필수 | 범위의 하한(포함)이며, 각 이벤트의 UTC 일자와 비교합니다. |
| `to_date` | `date` | 필수 | 범위의 상한(포함) |
| `group_by` | `list[Literal['namespace', 'agent', 'day', 'operation', 'memory_key', 'user_id', 'model', 'traffic_class', 'instance_label', 'build_commit']]` | *(계산됨)* | GROUP BY에 사용할 차원입니다. |
| `agent` | `str \| None` | `None` | 기록하거나 읽는 에이전트입니다. op가 허용하는 경우 `'-'` 또는 `'*'`는 모든 에이전트를 의미합니다. |
| `operation` | `str \| None` | `None` | 이 op 이름만 집계합니다(예: 'memory.ask'). None이면 모든 op를 집계합니다. |
| `user_id` | `str \| None` | `None` | 특정 최종 사용자만 집계합니다(이벤트 스캔을 강제함). None 또는 "-"이면 모든 사용자입니다. |
| `traffic_class` | `str \| None` | `None` | 하나의 클래스만 집계합니다(production \| interactive \| bench). `user_id`처럼 이벤트 스캔을 강제합니다. |
| `instance_label` | `str \| None` | `None` | 하나의 런처가 띄운 프로세스만 집계합니다(`deploy:web:blue`, `iso:w6m1:7864`, …). `user_id`처럼 이벤트 스캔을 강제합니다. |
| `include_cache` | `bool` | `True` | 정확히 일치하는 프롬프트의 응답 캐시 합계를 원장에서 읽습니다(memory.ask 행의 `out_llm_cache_hits` / `out_llm_cache_saved_usd`). |

| 출력 필드 | 타입 | 설명 |
| --- | --- | --- |
| `rows` | `list[CostSummaryRow]` | `group_by` 차원의 고유 값마다 한 행이며, op가 많은 순으로 최대 5,000개입니다. 호출자가 해당 org에서 읽을 수 있는 네임스페이스가 없으면 비어 있습니다. |
| `total_ops` | `int` | 반환된 행의 `ops` 합계입니다. |
| `total_errors` | `int` | 반환된 행의 `errors`(실패한 op) 합계입니다. |
| `total_cost_usd` | `float` | 반환된 행의 업스트림 제공자 지출(`upstream_cost_usd`) 합계이며, 단위는 USD입니다. |
| `cache_hits` | `int` | 범위 내 정확히 일치하는 프롬프트의 응답 캐시 적중 수로, 테이블에서 처리된 LLM 호출과 그로 인해 지출하지 않은 가격표 기준 금액을 나타냅니다. |
| `cache_saved_usd` | `float` | 응답 캐시 적중으로 지출하지 않은 USD이며, 소수점 6자리로 반올림합니다. `include_cache`가 꺼져 있거나 필터가 `memory.ask`를 제외하면 0입니다. |

<!-- prettier-ignore-end -->
