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 驗證工作階段。

僅限管理員： 此技能中的所有指令都需要具有工作區管理員權限的 token。非管理員 token 會回傳 {"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          # 所有 connector（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 節點	在昂貴的 connector 呼叫前跳過不符合條件的記錄
設定 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 入口網址，用於自助帳單管理

剩餘點數 = 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