cost 操作
cost 操作
本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.
每个 cost.* 操作接受和返回的确切字段。
每个操作都是 HTTP 上的 POST /v1/<op>,同时也是 MCP 工具 loom_<op>。身份字段(org、namespace、agent、user_id、session_id)会在传输层能够提供时,从令牌和 MCP 会话中填充;对于单用户服务器上不带令牌的 HTTP 调用,除 code.* 和 tracker.*(它们保留各自平面的 org)之外,所有操作都使用该安装的 org,而部分操作还会使用该安装的命名空间和 agent;参见身份与命名空间。操作索引说明了 role、kind 以及 MCP 的 all 列表。未知的输入字段仍会被处理,并在 ignored_args 中列出。
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 数,对返回的各行求和。 |
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 |
仅限组织范围模式 |
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 数:说明客户端时钟走快了,因此一次运行的成本窗口可能会把它们算得偏晚。 |
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。 |