`cost` 작업
이 페이지는 영어 원문을 기계 번역한 것이며, 영어 원문이 기준입니다. Machine-translated from the English page, which is authoritative.
각 cost.* 작업이 받는 필드와 반환하는 필드를 정확히 설명합니다.
모든 op는 HTTP에서는 POST /v1/<op>이고 MCP에서는 loom_<op> 도구입니다. 식별 필드(org, namespace, agent, user_id, session_id)는 전송 방식이 지원하는 경우 토큰과 MCP 세션에서 채워집니다. 단일 사용자 서버에서 토큰 없이 HTTP를 호출하면, code.*와 tracker.*(각자 자신의 플레인을 유지함)를 제외한 모든 op에서 설치의 org가 사용되며, 일부 op에서는 네임스페이스와 에이전트도 채워집니다. 자세한 내용은 아이덴티티와 네임스페이스를 참고하세요. 작업 색인에서 역할, 종류, MCP all 목록을 설명합니다. 알 수 없는 입력 필드도 처리되며 ignored_args에 이름이 표시됩니다.
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 |
가격표에 모델이 없는 턴의 수로, 반환된 행 전체에 대해 합산합니다. |
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 전체 모드에서만 사용됩니다. |
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초 넘게 앞선 시각으로 기록된 턴 수입니다. 클라이언트 시계가 앞서 있으므로 실행의 비용 구간에서 해당 턴이 늦게 배치될 수 있습니다. |
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입니다. |