cargo-billing

Cargo CLI — 账单

账单和积分管理：拉取使用指标、检查订阅状态、查看发票和管理积分。

完整 JSON 响应结构请参见 references/response-shapes.md。
常见错误及修复方法请参见 references/troubleshooting.md。
使用指标和订阅示例请参见 references/examples/usage-metrics.md。

前提条件

安装、登录（--oauth / --token）、JSON 输出约定和错误格式请参见 ../cargo/references/prerequisites.md。在运行以下任何命令之前，请使用 cargo-ai whoami 验证会话。

仅限管理员： 此技能中的每个命令都需要具有工作区管理员访问权限的令牌。非管理员令牌返回 {"errorMessage":"forbidden"}。

先发现资源

使用指标可以按资源 UUID 进行筛选和分组。在查询之前先发现它们。

cargo-ai orchestration play list            # 所有 play（名称，workflowUuid）
cargo-ai orchestration tool list            # 所有工具（名称，workflowUuid）
cargo-ai ai agent list                     # 所有 agent（uuid，名称）
cargo-ai connection connector list          # 所有连接器（uuid，名称，integrationSlug）
cargo-ai storage model list                # 所有模型（uuid，名称，slug）

快速参考

cargo-ai billing usage get-metrics --from <YYYY-MM-DD> --to <YYYY-MM-DD>
cargo-ai billing usage get-metrics --from <YYYY-MM-DD> --to <YYYY-MM-DD> --group-by workflow_uuid
cargo-ai billing subscription get
cargo-ai billing subscription get-invoices
cargo-ai billing subscription create-portal-session

运行批次前估算成本

在触发大批量之前，估算积分消耗以避免意外费用。

步骤 1 — 检查当前积分余额：

cargo-ai billing subscription get
# → subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount = 剩余积分

步骤 2 — 从样本运行估算成本：

首先在单条记录上运行工作流并测量消耗的积分：

# 在一条记录上运行
cargo-ai orchestration run create --workflow-uuid <uuid> --data '{...}'
# → 轮询至完成

# 检查该运行使用的积分
cargo-ai billing usage get-metrics \
  --from <今天> --to <今天> \
  --workflow-uuid <uuid>
# → .totalUsage = 今天此工作流消耗的积分

步骤 3 — 预估批次成本：

预估成本 = 每条记录积分 × 记录数

在继续之前，与 subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount 进行比较。

步骤 4 — 在批次期间监控：

# 检查批次进行中的成本
cargo-ai billing usage get-metrics \
  --from <开始日期> --to <今天> \
  --workflow-uuid <uuid>

成本杠杆：

操作	效果
使用更便宜的模型（例如 gpt-4o-mini 代替 gpt-4o）	显著降低 AI 节点的成本
在图中尽早添加 filter 节点	在昂贵的连接器调用之前跳过不符合条件的记录
设置 fallbackOnFailure: false	失败时提前停止运行，而不是继续到下游节点
减少 agent 节点上的 maxSteps	限制每个记录 agent 可以进行的工具调用次数

要找出哪个节点或提供商主导了 play 的支出，请遵循 ../cargo-diagnostics/references/play-optimize-credits.md 中的归因运行手册。

使用指标

拉取任意时间范围内的积分和使用数据，可选择筛选和分组。

# 一段时间内的基本使用
cargo-ai billing usage get-metrics --from <开始日期> --to <结束日期>

# 按维度分组
cargo-ai billing usage get-metrics --from <开始日期> --to <结束日期> --group-by workflow_uuid
cargo-ai billing usage get-metrics --from <开始日期> --to <结束日期> --group-by connector_uuid
cargo-ai billing usage get-metrics --from <开始日期> --to <结束日期> --group-by integration_slug
cargo-ai billing usage get-metrics --from <开始日期> --to <结束日期> --group-by model_uuid
cargo-ai billing usage get-metrics --from <开始日期> --to <结束日期> --group-by agent_uuid

# 按特定资源筛选
cargo-ai billing usage get-metrics --from <开始日期> --to <结束日期> --workflow-uuid <uuid>
cargo-ai billing usage get-metrics --from <开始日期> --to <结束日期> --agent-uuid <uuid>
cargo-ai billing usage get-metrics --from <开始日期> --to <结束日期> --connector-uuid <uuid>
cargo-ai billing usage get-metrics --from <开始日期> --to <结束日期> --integration-slug <slug>

# 指定单位
cargo-ai billing usage get-metrics --from <开始日期> --to <结束日期> --unit credits

--group-by 值：workflow_uuid、connector_uuid、model_uuid、integration_slug、agent_uuid。

可用筛选条件：--workflow-uuid、--model-uuid、--connector-uuid、--integration-slug、--slug、--agent-uuid。可与 --group-by 和 --unit 组合使用。

订阅和积分

cargo-ai billing subscription get                    # 当前计划、已使用/可用积分、周期日期
cargo-ai billing subscription get-invoices            # 发票历史（金额以分为单位）
cargo-ai billing subscription get-credit-card         # 存档的信用卡
cargo-ai billing subscription create-portal-session   # Stripe 门户 URL，用于自助账单管理

剩余积分 = subscription get 中的 subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount。

注意： 发票金额以分为单位返回。除以 100 得到美元值。

帮助

每个命令都支持 --help：

cargo-ai billing usage get-metrics --help
cargo-ai billing subscription get --help
cargo-ai billing subscription get-invoices --help