<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>`。身份字段（`org`、`namespace`、`agent`、`user_id`、`session_id`）会在传输层能够提供时，从令牌和 MCP 会话中填充；对于单用户服务器上不带令牌的 HTTP 调用，除 `code.*` 和 `tracker.*`（它们保留各自平面的 org）之外，所有操作都使用该安装的 org，而[部分操作](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)还会使用该安装的命名空间和 agent；参见[身份与命名空间](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md)。[操作索引](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md)说明了 role、kind 以及 MCP 的 `all` 列表。未知的输入字段仍会被处理，并在 `ignored_args` 中列出。

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

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

## `cost.agent_summary`

编码 agent 自身的花费（loom.agent_turn_usage）在某个日期窗口内的汇总，这是 `cost.summary` 未涵盖的数据系列，后者统计的是 LOOM 在上游的花费。

`POST /v1/cost.agent_summary` · MCP `loom_cost_agent_summary` · 角色 `viewer` · 读取

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（标识元组的第一个元素）。 |
| `namespace` | `str \| None` | `None` | 该操作读取或写入的命名空间。 |
| `from_date` | `date` | 必填 | 窗口的下界（含），与每个 turn 的 UTC 日期比较。 |
| `to_date` | `date` | 必填 | 上界（含） |
| `group_by` | `list[Literal['namespace', 'agent', 'day', 'model', 'consumer', 'session_id']]` | `['model']` | 用于 GROUP BY 的维度。 |
| `agent` | `str \| None` | `None` | 写入或读取的 agent；在操作允许的情况下，`'-'` 或 `'*'` 表示任意 agent。 |
| `consumer` | `str \| None` | `None` | 调用方集成的标签，记录在账本行上。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `rows` | `list[CostAgentSummaryRow]` | 每个不同的 `group_by` 维度取值组合对应一行，按花费从高到低排序，最多 5,000 行；当调用方在该 org 中无法读取任何命名空间时为空。 |
| `total_turns` | `int` | 返回的各行 `turns` 之和。 |
| `total_sessions` | `int` | 不同会话的数量：按 `session_id` 分组时为各行之和，否则取最大一行的计数（当一个会话跨越多行时，这是一个下限）。 |
| `total_cost_usd` | `float` | 返回的各行 `cost_usd` 之和，单位为美元；未定价的 turn 按 0 计。 |
| `unpriced_turns` | `int` | 其模型不在价格表中的 turn 数，对返回的各行求和。 |

<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` | 该操作读取或写入的命名空间。 |
| `user_id` | `str \| None` | `None` | 指定终端用户在该命名空间内的滚动 24 小时预算；省略时返回命名空间合计。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `namespace` | `str` | 该操作读取或写入的命名空间。 |
| `user_id` | `str \| None` | 所选的逻辑终端用户；对于命名空间和组织合计则为 None。 |
| `spent_24h_usd` | `float \| None` | 滚动 24 小时的上游支出（美元）；在用户模式下返回 null，除非调用方是不受命名空间角色限制的平台管理员。 |
| `cap_usd` | `float` | 生效的命名空间或指定用户的上限：优先使用命名空间的覆盖值，否则使用服务器默认值。0.0 表示不设上限；组织范围的汇总始终不设上限。 |
| `cap_source` | `Literal['namespace', 'global', 'namespace_user', 'global_user', 'uncapped', 'org']` | `namespace` / `global` 表示命名空间上限，`namespace_user` / `global_user` 表示用户上限，`uncapped` 表示已禁用上限，`org` 表示组织范围的汇总。 |
| `over_cap` | `bool` | 当实际支出达到所选上限时为 True，即使支出数据被隐藏也是如此；组织范围内为 false。 |
| `namespace_over_cap` | `bool \| None` | 在用户模式下，命名空间的支出可能会单独阻止新的工作。 |
| `pct_of_cap` | `float \| None` | 已支出的比例，限制在 0..1 之间；不设上限或用户支出被隐藏时为 null。 |
| `namespaces_with_spend` | `int` | 仅限组织范围模式 |

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

## `cost.record_turns`

编码 agent 自身在一次会话中的花费，每次调用记录一批 turn。

`POST /v1/cost.record_turns` · MCP `loom_cost_record_turns` · 角色 `writer` · 幂等 · 未列在 MCP `all` 工具集中

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | `'-'` | 写入或读取的 agent；在操作允许的情况下，`'-'` 或 `'*'` 表示任意 agent。 |
| `user_id` | `str` | `'-'` | 该行所属的最终用户；`'-'` 表示无。 |
| `session_id` | `str` | 必填 | 该行所属的会话或对话；`'-'` 表示无。 |
| `consumer` | `str` | `''` | 调用方集成的标记，记录在账本行上。 |
| `turns` | `list[TurnUsage]` | 必填 | 要记录的 turn，每次调用 1 到 200 个；使用相同 `message_id` 重新发送的 turn 会替换其之前的行。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `recorded` | `int` | 写入账本的 turn 数；写入失败时为 0（调用本身仍然成功）。 |
| `priced` | `int` | 其模型存在于价格表中的 turn 数；写入失败时为 0。 |
| `unpriced_models` | `list[str]` | 价格表中没有的模型：它们的行带有 cost_usd=0 和 priced=false；请将其添加到 PRICE_PER_1K_TOKENS，而不要信任 $0。 |
| `cost_usd` | `float` | 本批次中已定价 turn 的总价，单位为美元，四舍五入到 6 位小数。 |
| `turns_dated_ahead` | `int` | 时间比服务器时钟晚超过 5 秒的 turn 数：说明客户端时钟走快了，因此一次运行的成本窗口可能会把它们算得偏晚。 |

<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` | 写入或读取的 agent；在 op 允许时，`'-'` 或 `'*'` 表示任意 agent。 |
| `operation` | `str \| None` | `None` | 仅统计该 op 名称（例如 'memory.ask'）；None 表示统计所有 op。 |
| `user_id` | `str \| None` | `None` | 仅限某一位终端用户（会强制扫描 events）；None 或 "-" 表示所有用户。 |
| `traffic_class` | `str \| None` | `None` | 仅限某一个类别（production \| interactive \| bench）；与 `user_id` 一样会强制扫描 events。 |
| `instance_label` | `str \| None` | `None` | 仅限某个启动器的进程（`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` 维度的每个不同取值对应一行，按 op 数量从多到少排序，最多 5,000 行；当调用方无法读取该组织内任何命名空间时为空。 |
| `total_ops` | `int` | 返回各行的 `ops` 之和。 |
| `total_errors` | `int` | 返回各行的 `errors`（失败的 op）之和。 |
| `total_cost_usd` | `float` | 返回各行的上游提供方支出（`upstream_cost_usd`）之和，单位为美元。 |
| `cache_hits` | `int` | 窗口内的精确提示词响应缓存：由缓存表直接响应的 LLM 调用次数，以及这些调用按价格表本应花费而未花费的美元金额。 |
| `cache_saved_usd` | `float` | 响应缓存命中未花费的美元金额，四舍五入到 6 位小数；当 `include_cache` 关闭或过滤条件排除了 `memory.ask` 时为 0。 |

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