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

# `cost` オペレーション

<!-- i18n: source=docs/reference/operations/cost.md blob=f8bcf1fd1aead97faf00f604f2c42a7dca73bcda model=claude-sonnet-5-5 -->
> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/cost.md)の機械翻訳です。内容は英語の原文が優先されます。
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/cost.md), which is authoritative.


各 `cost.*` オペレーションが受け取るフィールドと返すフィールドの一覧です。

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

すべてのオペレーションは、HTTP では `POST /v1/<op>`、MCP ツールでは `loom_<op>` として呼び出せます。ID フィールド（`org`、`namespace`、`agent`、`user_id`、`session_id`）は、トランスポートが対応している場合、トークンと MCP セッションから補完されます。シングルユーザーのサーバーでトークンなしに HTTP 呼び出しを行った場合は、`code.*` と `tracker.*`（それぞれのプレーンの値を保持します）を除くすべてのオペレーションでインストールの org が使われ、[一部のオペレーション](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)では名前空間とエージェントも補完されます。詳細は[ID と名前空間](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md)を参照してください。ロール、種別、MCP の `all` 一覧については[オペレーション一覧](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md)で説明しています。未知の入力フィールドも処理され、`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` | 呼び出し元インテグレーションのタグ。台帳の行に記録されます。 |

| 出力フィールド | 型 | 意味 |
| --- | --- | --- |
| `rows` | `list[CostAgentSummaryRow]` | `group_by` のディメンションの値ごとに 1 行。コストの高い順で、最大 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 時間のアップストリーム支出と、その上限との比較です。

`POST /v1/cost.budget_status` · MCP `loom_cost_budget_status` · ロール `viewer` · 読み取り

| 入力フィールド | 型 | デフォルト | 意味 |
| --- | --- | --- | --- |
| `org` | `str` | 必須 | テナント（アイデンティティタプルの最初の要素）。 |
| `namespace` | `str \| None` | `None` | この op が読み書きする名前空間。 |
| `user_id` | `str \| None` | `None` | 名前空間内で指定したエンドユーザーの直近 24 時間のローリング予算。省略すると名前空間の合計を返します。 |

| 出力フィールド | 型 | 意味 |
| --- | --- | --- |
| `namespace` | `str` | この op が読み書きする名前空間。 |
| `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。値が非公開でも 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`

コーディングエージェント自身の1セッション分の支出を、1回の呼び出しで複数ターンまとめて記録します。

`POST /v1/cost.record_turns` · MCP `loom_cost_record_turns` · ロール `writer` · 冪等 · MCP の `all` ツールセットには含まれません

| 入力フィールド | 型 | デフォルト | 説明 |
| --- | --- | --- | --- |
| `org` | `str` | 必須 | テナント（ID タプルの最初の要素）。 |
| `namespace` | `str` | 必須 | op が読み取りまたは書き込みを行う名前空間。 |
| `agent` | `str` | `'-'` | 書き込みまたは読み取りを行うエージェント。op が許可する場合、`'-'` または `'*'` は任意のエージェントを意味します。 |
| `user_id` | `str` | `'-'` | 行が属するエンドユーザー。なしの場合は `'-'`。 |
| `session_id` | `str` | 必須 | 行が属するセッションまたは会話。なしの場合は `'-'`。 |
| `consumer` | `str` | `''` | 呼び出し元インテグレーションのタグ。台帳の行に記録されます。 |
| `turns` | `list[TurnUsage]` | 必須 | 記録するターン。1回の呼び出しにつき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` | 必須 | テナント（ID タプルの最初の要素）。 |
| `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` | 1 人のエンドユーザーのみ（events のスキャンが必要）。None または "-" はすべてのユーザー。 |
| `traffic_class` | `str \| None` | `None` | 1 つのクラスのみ（production \| interactive \| bench）。`user_id` と同様に events のスキャンが必要です。 |
| `instance_label` | `str \| None` | `None` | 1 つのランチャーのプロセスのみ（`deploy:web:blue`、`iso:w6m1:7864`、…）。`user_id` と同様に events のスキャンが必要です。 |
| `include_cache` | `bool` | `True` | 完全一致プロンプトのレスポンスキャッシュの合計を台帳から読み取ります（memory.ask 行の `out_llm_cache_hits` / `out_llm_cache_saved_usd`）。 |

| 出力フィールド | 型 | 意味 |
| --- | --- | --- |
| `rows` | `list[CostSummaryRow]` | `group_by` ディメンションの値ごとに 1 行。op 数の多い順で、最大 5,000 行。呼び出し元が組織内のどの名前空間も読み取れない場合は空になります。 |
| `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 -->
