跳转至

尚无译文的页面会以英语打开,并标注为英语。

本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.

cost 操作

每个 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。