cargo-billing

Cargo CLI — 计费

计费与额度管理：获取用量指标、查看订阅状态、查看发票和管理额度。

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

初始化

已登录（cargo-ai whoami 返回工作区）？请跳至下一节。

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email [email protected]  # emailed code, no browser; creates the account on first use
                                        # alternatives: --oauth (browser) · --token <api-token> (CI)
cargo-ai whoami                         # confirm the active workspace before any write

每条命令都会将 JSON 输出到标准输出；失败时以非零状态码退出，并返回 {"errorMessage": "..."}。任何会创建运行或批次的命令都是异步的——请传入 --wait-until-finished，或轮询对应的 get。**仅限管理员：**此技能中的每条命令都需要使用在工作区具有管理员访问权限的令牌（即具有 billing:read 权限；更改银行卡、套餐和充值需要 billing:write）。不具备该权限的令牌会收到 401 {"reason":"unauthorized"}，CLI 会报告 Not authenticated: unauthorized：这是权限不足，不是登录过期。安装完整技能包后，../cargo/references/prerequisites.md 会补充 CLI 版本固定要求、令牌范围和仅限管理员的功能说明。

先发现资源

用量指标可以按资源 UUID 筛选和分组。查询前请先发现资源。

cargo-ai orchestration play list            # all plays (name, workflowUuid)
cargo-ai orchestration tool list            # all tools (name, workflowUuid)
cargo-ai ai agent list                     # all agents (uuid, name)
cargo-ai connection connector list          # all connectors (uuid, name, integrationSlug)
cargo-ai storage model list                # all models (uuid, name, 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 update-payment-method --card-number <number> --card-exp <MM/YYYY> --card-cvc <cvc>
cargo-ai billing subscription create-portal-session

批量运行前估算成本

触发大型批次前，请先估算额度消耗，以避免意外扣费。

步骤 1 — 查看当前额度余额：

cargo-ai billing subscription get
# → subscriptionAvailableCreditsCount + additionalAvailableCreditsCount - subscriptionCreditsUsedCount = remaining credits

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

先对单条记录运行工作流，测量消耗的额度：

# Run on one record
cargo-ai orchestration run create --workflow-uuid <uuid> --data '{...}'
# → poll to completion

# Check credits used for that run
cargo-ai billing usage get-metrics \
  --from <today> --to <today> \
  --workflow-uuid <uuid>
# → metrics[].items[] for that workflow (the response has one key, `metrics` — there is no `totalUsage`)

步骤 3 — 预测批次成本：

estimated_cost = (credits_per_record × number_of_records)      # provider actions
               + (nodes_per_record × number_of_records / 100)  # execution charge

第二项是每次执行收取 0.01 额度的平台费用（见下文“执行费用”）。样本运行可免费测得该费用——记录的执行次数为 length(run.executions)，或样本时间范围内 --unit orchestration.executions 的一行数据。若不计入此项，任何步骤较多的图都会低估报价。

继续之前，请将其与 subscriptionAvailableCreditsCount + additionalAvailableCreditsCount - subscriptionCreditsUsedCount 进行比较。

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

# Check running costs mid-batch
cargo-ai billing usage get-metrics \
  --from <start-date> --to <today> \
  --workflow-uuid <uuid>

成本优化手段：

操作	影响
使用成本更低的模型（例如 gpt-4o-mini 而非 gpt-4o）	显著降低 AI 节点的成本
在图的前部添加 filter 节点	在调用成本高昂的连接器之前，跳过不符合条件的记录
设置 fallbackOnFailure: false	发生失败时提前停止运行，而不是继续执行下游节点
降低 Agent 节点的 maxSteps	限制 Agent 对每条记录可进行的工具调用次数
减少节点数量——合并串联的 variables，将成对的分支合并为一个 switch	每条记录按 0.01/次执行计费；当图的开销来自步骤而非服务提供商时，这是唯一的优化手段

若要在选择优化手段前找出哪个节点或服务提供商占用了某个流程的大部分开销，请参阅 ../cargo-diagnostics/references/play-optimize-credits.md 中的归因操作指南。

使用量指标

提取任意时间范围内的额度和使用量数据，还可按条件筛选和分组。

# Basic usage for a period
cargo-ai billing usage get-metrics --from <start-date> --to <end-date>

# Group by dimension
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --group-by workflow_uuid
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --group-by connector_uuid
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --group-by integration_slug
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --group-by model_uuid
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --group-by agent_uuid

# Filter by specific resource
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --workflow-uuid <uuid>
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --agent-uuid <uuid>
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --connector-uuid <uuid>
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --integration-slug <slug>

# One unit at a time (the fourth accepted value, hosting.events, counts hosted worker events)
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --unit billing.credits
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --unit orchestration.executions
cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --unit storage.records

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

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

按成员统计支出。 --group-by user_uuid --unit billing.credits 会将额度归属到触发运行、批次或 Agent 消息的成员。归属功能于 2026 年 10 月上线，此前记录的使用量不含用户信息，因此更早月份的数据无法按成员拆分。API 也支持筛选单个成员（GET /v1/billing/usage/metrics?userUuid=<uuid>&…）；CLI 没有 --user-uuid 标志，因此请进行分组并读取该成员对应的行。管理员可为每位成员设置月度上限（通过 API 或 Web 应用中的 Settings → Users 设置 monthlyCreditsLimit；参见 cargo-workspace-management → Users）。成员达到上限后，在下一个 UTC 月开始前，其新的消耗额度的工作将被拒绝。如果某位成员的运行因额度不足而开始失败，但工作区余额充足，请先查看该成员的细分数据，再判断是否为余额问题。

使用量单位

--unit 只能接受 billing.credits、orchestration.executions、storage.records 或 hosting.events；其他值都会导致 400 错误，并列出这些可用值。未指定 --unit 时，各单位会交错返回在同一个 items[] 数组中，其中的 count 字段代表的量并不相同。请根据 slug 判断单位：

单位	items[] 中的 Slug	count 表示什么
billing.credits	integration.<slug>.action.<action>、native.<action>、integration.<slug>.chat、integration.<slug>.extractor.<name>	额度（可为小数）
orchestration.executions	success、error	节点执行次数，按每次执行计数，不是额度
storage.records	insert	写入的记录数

未限定单位的调用如果同时显示 {"slug":"success","count":1043} 和 {"slug":"integration.peopleDataLabs.action.queryPeople","count":174}，表示的是 1,043 次执行和 174 个额度。将数字用于估算时，务必传入 --unit。

执行费用

每次节点执行收费 0.01 个额度，即每 100 次执行收费 1 个额度。 这适用于每种节点类型和每个节点，包括不产生提供商费用的结构性原生节点：branch、filter、switch、split、group、variables、start、end。工作流中没有免费的步骤。

这项费用不会按节点归属。run get → executions[].creditsUsedCount 和 spans.execution_credits_used_count 列都只记录提供商费用；对于实际产生了费用的原生节点，这两个值仍会显示为 0。因此，逐节点归属会低估每个图的费用，而且差额会随步骤数而非支出金额增加。

只有以下界面会显示这项费用：

cargo-ai billing usage get-metrics --from <YYYY-MM-DD> --to <YYYY-MM-DD> --unit orchestration.executions
# → items[] = [{"slug":"success","count":<executions>}, {"slug":"error","count":<executions>}]
# credits = (success + error) / 100

请与运行时表交叉核对，两者的逐行数据一致：

cargo-ai orchestration query execute \
  "SELECT execution_status, count() AS executions, count() / 100 AS credits
   FROM spans WHERE execution_started_at >= '<YYYY-MM-DD>' GROUP BY execution_status"

为何这会影响估算。 一个图的费用由两部分组成：

credits = (provider cost per record × records) + (nodes per record × records ÷ 100)

第二部分在额度费用表中不可见，因为该表按操作而非步骤计价。对于操作密集型流程，执行费用相对较小（每条记录都执行一次 LinkedIn enrich，其费用远高于 8 个步骤）；而对于步骤密集、操作较少的流程，执行费用则占主导——一个包含 12 个节点、处理 20,000 条记录的路由扫描，即使完全不调用提供商，也会消耗 2,400 个额度。出错的执行同样收费，因此在后期失败的图仍会为此前所有步骤付费。

工具会展开执行。 一个工具节点会计为一次执行，此外，工具自身图中的每个节点也会分别计费。将子图提取为工具有利于调试，但不能节省费用；它会在内部节点原有费用之外，为每条记录额外增加一次执行。如果一个图的执行次数超过其可见节点数，应先检查工具节点：按 node_slug 对 spans 分组即可找到它们。

订阅和额度

cargo-ai billing subscription get                    # current plan, credits used/available, period dates
cargo-ai billing subscription get-invoices            # invoice history (amounts in cents)
cargo-ai billing subscription get-credit-card         # card on file
cargo-ai billing subscription update-payment-method   # add or replace the card (see below)
cargo-ai billing subscription create-portal-session   # Stripe portal URL for self-service billing

剩余额度 = subscription get 返回的 subscriptionAvailableCreditsCount + additionalAvailableCreditsCount - subscriptionCreditsUsedCount。

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

免费套餐

新账户会获得 100 个免费额度，且未绑定银行卡。当 subscription get 显示余额充足或接近初始值时，应结合这笔预算回答费用问题，而不是只给出一个抽象数字——“你已用掉 100 个免费额度中的 12 个”是回答“我目前用得怎么样？”的实用说法；当用户考虑是否继续时，这也是诚实的回答。

100 个额度能做多少事，以下是大致参考（各项操作的费用见 ../cargo-gtm/references/credits-cost-table.md）：

工作	费用	100 个额度约可完成
获取潜在客户 — salesNavigator.searchLeads	0.2/条记录	~500 条潜在客户
从 LinkedIn URL 获取信息并验证邮箱 — aiArk.enrichPerson	0.1	~1,000 人
验证邮箱 — waterfall.verifyEmail	0.1	~1,000 次检查
完整联系人信息补充 — waterfall.enrichContact	2	~50 位联系人
查找电话号码 — FullEnrich.findPhone	6	~16 个号码

快速入门演示大约会花费 5 个额度。查找电话号码是消耗免费额度最快的方式，因此电话查询是需谨慎使用的选项：升级阶段每条记录会花费 3–7 个额度，约为邮箱查询的 10 倍，而且绝不应默认加入调用链——只有用户明确提出要求，且仅针对符合条件的潜在客户时，才将其纳入计划。完整的费用规则见 ../cargo-gtm/references/cost-discipline.md。

添加银行卡

一个工作区只能绑定一张银行卡。update-payment-method 用于设置银行卡，无论之前是否已绑定；可通过三种方式提供银行卡信息。

# Card details — no browser, nothing to hand off
cargo-ai billing subscription update-payment-method \
  --card-number 4242424242424242 --card-exp 12/2030 --card-cvc 123

# Same, but keeps the number out of shell history and the process list
echo '{"number":"4242424242424242","expMonth":12,"expYear":2030,"cvc":"123"}' \
  | cargo-ai billing subscription update-payment-method --card-stdin

# No card details — prints a Stripe-hosted form URL and waits for the card to land
cargo-ai billing subscription update-payment-method

优先使用 --card-stdin。 通过标志传入的任何内容都会显示在 shell 历史记录中，也会被任何能够读取进程列表的进程看到。银行卡信息会从你的设备直接发送到 Stripe 以换取令牌；这些信息不会到达 Cargo API，也不会被打印到任何输出中。

绝不编造银行卡信息，也绝不重复使用对话中其他地方出现的号码。 请向用户索取信息，或使用不带参数的形式并将 URL 提供给用户。

如果没有要提交的银行卡信息，请使用不带参数的形式作为备用方案：该命令会打印一个可直接打开银行卡表单的 URL，然后持续轮询，直到银行卡发生变更（--timeout、--poll-interval、--no-open）。将该 URL 转发给用户即可——通过 SSH 或在沙盒中也能使用。

无论使用哪种方式，银行卡都必须先通过发卡机构验证，才能成为默认支付方式。因此，如果银行卡无法扣款，会在此处失败，而不会等到下次续费时才悄无声息地失败。

失败情况	含义	处理方法
cardDeclined + declineCode	发卡机构拒绝了验证	查看 declineCode。如果是有消费限额的虚拟卡，insufficient_funds 或限额代码表示预算或商户限制不允许使用该卡——请让持卡人提高限额
authenticationRequired	银行卡需要 3-D Secure 验证，必须由持卡人亲自完成	不带参数重新运行，并将托管表单 URL 提供给用户
paymentMethodNotFound	这些信息未能对应到可用的银行卡	与用户核对卡号和有效期

银行卡更新每个工作区每小时最多可进行 10 次（与 setup intents 共享限额）。重试被拒绝的银行卡也会消耗次数——应先解决问题，不要反复重试。

帮助

每条命令都支持 --help：

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