Back to Details

cargo-billing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cargo CLI — Billing

Cargo CLI — 账单管理

Billing and credit management: pulling usage metrics, checking subscription status, viewing invoices, and managing credits.
See 
references/response-shapes.md
for full JSON response structures. See 
references/troubleshooting.md
for common errors and how to fix them. See 
references/examples/usage-metrics.md
for usage metric and subscription examples.
账单与额度管理：提取使用指标、查看订阅状态、查看发票以及管理额度。
完整JSON响应结构请查看 
references/response-shapes.md
。 常见错误及修复方法请查看 
references/troubleshooting.md
。 使用指标与订阅示例请查看 
references/examples/usage-metrics.md
。

Prerequisites

前置条件

bash
npm install -g @cargo-ai/cli
cargo-ai login --oauth                                  # browser sign-in (recommended)
bash
npm install -g @cargo-ai/cli
cargo-ai login --oauth                                  # 浏览器登录（推荐）

or: cargo-ai login --token <your-api-token> # workspace-scoped API token (non-interactive)

或者：cargo-ai login --token <your-api-token> # 工作区级API令牌（非交互式）

Pin a default workspace at login (with --oauth)

登录时固定默认工作区（使用--oauth）

cargo-ai login --oauth --workspace-uuid <uuid>

Verify with `cargo-ai whoami`. All commands output JSON to stdout. Without a global install, prefix every command with `npx @cargo-ai/cli` instead of `cargo-ai`.

Failed commands exit non-zero and return `{"errorMessage": "..."}`.

**Note:** Billing commands require a token with admin access to the workspace.
cargo-ai login --oauth --workspace-uuid <uuid>

使用 `cargo-ai whoami` 验证。所有命令都会向标准输出（stdout）输出JSON。若未全局安装，请将所有命令中的 `cargo-ai` 替换为 `npx @cargo-ai/cli`。

执行失败的命令会返回非零退出码，并返回 `{"errorMessage": "..."}`。

**注意：** 账单相关命令需要拥有工作区管理员权限的令牌。

Discover resources first

先发现资源

Usage metrics can be filtered and grouped by resource UUID. Discover them before querying.
bash
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)
使用指标可按资源UUID筛选和分组。查询前请先发现相关资源。
bash
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）

Quick reference

快速参考

bash
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
bash
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

Estimating cost before running a batch

运行批量任务前估算成本

Before triggering a large batch, estimate credit consumption to avoid unexpected charges.
Step 1 — Check current credit balance:
bash
cargo-ai billing subscription get
触发大型批量任务前，请估算额度消耗，避免意外收费。
步骤1 — 查看当前额度余额：
bash
cargo-ai billing subscription get

→ subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount = remaining credits

→ 剩余额度 = subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount


**Step 2 — Estimate cost from a sample run:**

Run the workflow on a single record first and measure credits consumed:

```bash

**步骤2 — 通过样本运行估算成本：**

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

```bash

Run on one record

在单条记录上运行

cargo-ai orchestration run create --workflow-uuid <uuid> --data '{...}'
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>
cargo-ai billing usage get-metrics
--from <今日日期> --to <今日日期>
--workflow-uuid <uuid>

→ .totalUsage = credits consumed today for this workflow

→ .totalUsage = 今日该工作流消耗的额度


**Step 3 — Project batch cost:**
estimated_cost = credits_per_record × number_of_records

Compare against `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount` before proceeding.

**Step 4 — Monitor during the batch:**

```bash

**步骤3 — 预估批量任务成本：**
预估成本 = 单条记录消耗额度 × 记录数量

在执行前将预估成本与 `subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount` 进行对比。

**步骤4 — 批量任务运行期间监控：**

```bash

Check running costs mid-batch

批量任务运行中途查看实时成本

cargo-ai billing usage get-metrics
--from <start-date> --to <today>
--workflow-uuid <uuid>

**Cost levers:**

| Action | Effect |
|---|---|
| Use a cheaper model (e.g. `gpt-4o-mini` vs `gpt-4o`) | Significant reduction for AI nodes |
| Add `filter` nodes early in the graph | Skip ineligible records before expensive connector calls |
| Set `fallbackOnFailure: false` | Stop the run early on failures instead of continuing to downstream nodes |
| Reduce `maxSteps` on agent nodes | Limit how many tool calls an agent can make per record |
cargo-ai billing usage get-metrics
--from <开始日期> --to <今日日期>
--workflow-uuid <uuid>

**成本优化手段：**

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

Usage metrics

使用指标

Pull credit and usage data for any time range, optionally filtered and grouped.
bash
undefined
提取任意时间范围的额度与使用数据，可选择筛选和分组。
bash
undefined

Basic usage for a period

某时间段的基础使用数据

cargo-ai billing usage get-metrics --from <start-date> --to <end-date>
cargo-ai billing usage get-metrics --from <开始日期> --to <结束日期>

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
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

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>
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>

Specify unit

指定单位

cargo-ai billing usage get-metrics --from <start-date> --to <end-date> --unit credits

`--group-by` values: `workflow_uuid`, `connector_uuid`, `model_uuid`, `integration_slug`, `agent_uuid`.

Available filters: `--workflow-uuid`, `--model-uuid`, `--connector-uuid`, `--integration-slug`, `--slug`, `--agent-uuid`. Combine with `--group-by` and `--unit`.
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` 组合使用。

Subscription and credits

订阅与额度

bash
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 create-portal-session   # Stripe portal URL for self-service billing
Remaining credits = 
subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount
from 
subscription get
.
Note: Invoice amounts are returned in cents. Divide by 100 for the dollar value.
bash
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

帮助

Every command supports 
--help
:
bash
cargo-ai billing usage get-metrics --help
cargo-ai billing subscription get --help
cargo-ai billing subscription get-invoices --help
所有命令均支持 
--help
参数：
bash
cargo-ai billing usage get-metrics --help
cargo-ai billing subscription get --help
cargo-ai billing subscription get-invoices --help