Back to Details

cargo-analytics

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cargo CLI — Analytics

Cargo CLI — 分析功能

Measurement and export: monitoring run metrics, downloading run and batch results, and exporting segment data.
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/run-analytics.md
for run metrics and error monitoring. See 
references/examples/exports.md
for data export and download examples. For billing, usage metrics, and subscription: use the 
cargo-billing
skill.
测量与导出：监控运行指标、下载运行及批处理结果、导出细分数据。
完整JSON响应结构请查看
references/response-shapes.md
。 常见错误及修复方法请查看
references/troubleshooting.md
。 运行指标与错误监控示例请查看
references/examples/run-analytics.md
。 数据导出与下载示例请查看
references/examples/exports.md
。 如需查看账单、使用指标及订阅相关内容，请使用
cargo-billing
skill。

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": "..."}`.
cargo-ai login --oauth --workspace-uuid <uuid>

使用`cargo-ai whoami`验证。所有命令会将JSON输出到标准输出。若未全局安装，请在每个命令前添加前缀`npx @cargo-ai/cli`，替代`cargo-ai`。

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

Discover resources first

先发现资源

Most analytics commands require UUIDs. 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 orchestration workflow list        # all workflows (uuid only — no name)
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。请先查询获取这些UUID。
bash
cargo-ai orchestration play list            # 所有剧本（名称、workflowUuid）
cargo-ai orchestration tool list            # 所有工具（名称、workflowUuid）
cargo-ai orchestration workflow list        # 所有工作流（仅uuid，无名称）
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 orchestration run get-metrics --workflow-uuid <uuid>
cargo-ai orchestration run download --workflow-uuid <uuid> --is-finished
cargo-ai orchestration run count --workflow-uuid <uuid> --statuses error
cargo-ai segmentation segment download --model-uuid <uuid> --filter '{"conjonction":"and","groups":[]}'
bash
cargo-ai orchestration run get-metrics --workflow-uuid <uuid>
cargo-ai orchestration run download --workflow-uuid <uuid> --is-finished
cargo-ai orchestration run count --workflow-uuid <uuid> --statuses error
cargo-ai segmentation segment download --model-uuid <uuid> --filter '{"conjonction":"and","groups":[]}'

Workflow run metrics

工作流运行指标

Aggregated metrics for workflow runs (success/error rates, credits per node).
bash
undefined
工作流运行的聚合指标（成功/错误率、每个节点的额度消耗）。
bash
undefined

Metrics for a workflow

某一工作流的指标

cargo-ai orchestration run get-metrics --workflow-uuid <uuid>
cargo-ai orchestration run get-metrics --workflow-uuid <uuid>

Scoped to a release, batch, or date range

限定版本、批处理或日期范围

cargo-ai orchestration run get-metrics --workflow-uuid <uuid> --release-uuid <uuid> cargo-ai orchestration run get-metrics --workflow-uuid <uuid> --batch-uuid <uuid> cargo-ai orchestration run get-metrics --workflow-uuid <uuid>
--created-after <start-date> --created-before <end-date>
undefined
cargo-ai orchestration run get-metrics --workflow-uuid <uuid> --release-uuid <uuid> cargo-ai orchestration run get-metrics --workflow-uuid <uuid> --batch-uuid <uuid> cargo-ai orchestration run get-metrics --workflow-uuid <uuid>
--created-after <start-date> --created-before <end-date>
undefined

Run count

运行计数

Count runs matching specific criteria — useful for monitoring.
bash
cargo-ai orchestration run count --workflow-uuid <uuid> --statuses error
cargo-ai orchestration run count --workflow-uuid <uuid> --is-finished \
  --created-after <start-date> --created-before <end-date>
cargo-ai orchestration run count --workflow-uuid <uuid> --batch-uuid <uuid>
Supports: 
--statuses
, 
--batch-uuid
, 
--release-uuid
, 
--is-finished
, 
--created-after
, 
--created-before
, 
--record-id
, 
--record-title
.
统计符合特定条件的运行次数——便于监控。
bash
cargo-ai orchestration run count --workflow-uuid <uuid> --statuses error
cargo-ai orchestration run count --workflow-uuid <uuid> --is-finished \
  --created-after <start-date> --created-before <end-date>
cargo-ai orchestration run count --workflow-uuid <uuid> --batch-uuid <uuid>
支持参数：
--statuses
, 
--batch-uuid
, 
--release-uuid
, 
--is-finished
, 
--created-after
, 
--created-before
, 
--record-id
, 
--record-title
。

Downloading run results

下载运行结果

Two distinct commands — pick the right one for the job.
有两个不同的命令——根据需求选择合适的命令。

run download
— full run records (metadata + per-node 
runContext
)

run download
— 完整运行记录（元数据 + 每个节点的
runContext
）

Returns each run as a JSON object with status, timing, executions, and 
runContext.<nodeSlug>
containing per-node outputs. Best for debugging or when you need the full execution history.
bash
undefined
以JSON对象形式返回每次运行的状态、时间、执行信息，以及包含每个节点输出的
runContext.<nodeSlug>
。最适合调试或需要完整执行历史的场景。
bash
undefined

All finished runs

所有已完成的运行

cargo-ai orchestration run download --workflow-uuid <uuid> --is-finished
cargo-ai orchestration run download --workflow-uuid <uuid> --is-finished

Date range

日期范围

cargo-ai orchestration run download --workflow-uuid <uuid>
--created-after <start-date> --created-before <end-date>
cargo-ai orchestration run download --workflow-uuid <uuid>
--created-after <start-date> --created-before <end-date>

Specific statuses

特定状态

cargo-ai orchestration run download --workflow-uuid <uuid> --statuses success,error
cargo-ai orchestration run download --workflow-uuid <uuid> --statuses success,error

From a specific batch

来自特定批处理

cargo-ai orchestration run download --workflow-uuid <uuid> --batch-uuid <uuid>
undefined
cargo-ai orchestration run download --workflow-uuid <uuid> --batch-uuid <uuid>
undefined

run download-outputs
— output of a specific node (CSV/JSON via signed URL)

run download-outputs
— 特定节点的输出（通过签名URL获取CSV/JSON）

This is the canonical way to get action results out of the platform. Maps to API 
POST /v1/orchestration/runs/download-outputs
. Returns 
{"url": "..."}
— a signed URL to a CSV (default) or JSON file containing only the output node's data with input/output context. Faster and cheaper than downloading whole run records when you only need the result.
bash
undefined
**这是从平台获取操作结果的标准方式。**对应API的
POST /v1/orchestration/runs/download-outputs
。返回
{"url": "..."}
——一个指向CSV（默认）或JSON文件的签名URL，文件仅包含输出节点的数据及输入/输出上下文。当你只需要结果时，此方式比下载完整运行记录更快、成本更低。
bash
undefined

Required: --workflow-uuid + --output-node-slug

必填参数：--workflow-uuid + --output-node-slug

cargo-ai orchestration run download-outputs
--workflow-uuid <uuid>
--output-node-slug <slug>
--format json
--is-finished
cargo-ai orchestration run download-outputs
--workflow-uuid <uuid>
--output-node-slug <slug>
--format json
--is-finished

Filter by batch + status

按批处理和状态过滤

cargo-ai orchestration run download-outputs
--workflow-uuid <uuid>
--output-node-slug <slug>
--batch-uuid <uuid>
--statuses finished

To find the `output-node-slug`: `cargo-ai orchestration release get <release-uuid>` → look at `nodes[].slug`. The terminal output node is typically named `output` or `end`.
cargo-ai orchestration run download-outputs
--workflow-uuid <uuid>
--output-node-slug <slug>
--batch-uuid <uuid>
--statuses finished

查找`output-node-slug`的方法：执行`cargo-ai orchestration release get <release-uuid>` → 查看`nodes[].slug`。终端输出节点通常命名为`output`或`end`。

Downloading batch results

下载批处理结果

bash
cargo-ai orchestration batch download --uuid <batch-uuid> --output-node-slug <node-slug>
To find the 
output-node-slug
: run 
cargo-ai orchestration release get <release-uuid>
(get the release UUID from the batch) and look at 
nodes[].slug
.
bash
cargo-ai orchestration batch download --uuid <batch-uuid> --output-node-slug <node-slug>
查找
output-node-slug
的方法：执行
cargo-ai orchestration release get <release-uuid>
（从批处理中获取版本UUID），然后查看
nodes[].slug
。

Handling partial batch failures

处理部分批处理失败情况

A batch with 
status: "success"
can still contain individual run failures. Always inspect the batch for errors before treating results as complete.
Step 1 — Check the batch summary:
bash
cargo-ai orchestration batch get <batch-uuid>
状态为
success
的批处理仍可能包含个别运行失败的情况。在将结果视为完整之前，请务必检查批处理中的错误。
步骤1 — 检查批处理摘要：
bash
cargo-ai orchestration batch get <batch-uuid>

→ .runsCount = total records submitted

→ .runsCount = 提交的总记录数

→ .executedRunsCount = records that reached a terminal state (success or error)

→ .executedRunsCount = 达到终端状态（成功或错误）的记录数

→ .failedRunsCount = records that errored

→ .failedRunsCount = 出错的记录数


**Step 2 — Count errors for the batch:**

```bash
cargo-ai orchestration run count \
  --workflow-uuid <uuid> \
  --batch-uuid <batch-uuid> \
  --statuses error
Step 3 — Download failed runs to inspect root causes:
bash
cargo-ai orchestration run download \
  --workflow-uuid <uuid> \
  --batch-uuid <batch-uuid> \
  --statuses error
Step 4 — Re-run only the failed records:
After fixing the underlying issue (connector credentials, bad input data, rate limits):
bash
undefined

**步骤2 — 统计批处理中的错误数：**

```bash
cargo-ai orchestration run count \
  --workflow-uuid <uuid> \
  --batch-uuid <batch-uuid> \
  --statuses error
步骤3 — 下载失败的运行记录以排查根本原因：
bash
cargo-ai orchestration run download \
  --workflow-uuid <uuid> \
  --batch-uuid <batch-uuid> \
  --statuses error
步骤4 — 仅重新运行失败的记录：
修复潜在问题（连接器凭据、无效输入数据、速率限制）后：
bash
undefined

Extract record IDs from the failed run download, then:

从失败的运行记录中提取record ID，然后执行：

cargo-ai orchestration batch create
--workflow-uuid <uuid>
--data '{"kind":"recordIds","recordIds":["id1","id2","id3"]}'

**Filtering by node output slug:**

To download only a specific node's output from a batch (e.g. just the enrichment node, not the full run):

```bash
cargo-ai orchestration batch create
--workflow-uuid <uuid>
--data '{"kind":"recordIds","recordIds":["id1","id2","id3"]}'

**按节点输出slug过滤：**

如需仅下载批处理中特定节点的输出（例如仅富集节点，而非完整运行记录）：

```bash

1. Get the release UUID from the batch

1. 从批处理中获取版本UUID

cargo-ai orchestration batch get <batch-uuid>
cargo-ai orchestration batch get <batch-uuid>

→ .releaseUuid

→ .releaseUuid

2. Find the node slug

2. 查找节点slug

cargo-ai orchestration release get <release-uuid>
cargo-ai orchestration release get <release-uuid>

→ nodes[].slug

→ nodes[].slug

3. Download that node's output

3. 下载该节点的输出

cargo-ai orchestration batch download
--uuid <batch-uuid>
--output-node-slug <node-slug>
undefined
cargo-ai orchestration batch download
--uuid <batch-uuid>
--output-node-slug <node-slug>
undefined

Segment data export

细分数据导出

Filter JSON uses 
conjonction
(not 
conjunction
) — this is intentional. See the 
cargo-orchestration
skill's 
references/filter-syntax.md
for the full filter syntax.
bash
undefined
过滤JSON使用
conjonction
（而非
conjunction
）——这是有意设计的。完整过滤语法请查看
cargo-orchestration
skill的
references/filter-syntax.md
。
bash
undefined

Full export (all records)

完整导出（所有记录）

cargo-ai segmentation segment download
--model-uuid <uuid>
--filter '{"conjonction":"and","groups":[]}'
cargo-ai segmentation segment download
--model-uuid <uuid>
--filter '{"conjonction":"and","groups":[]}'

With sorting and limit

带排序和限制

cargo-ai segmentation segment download
--model-uuid <uuid>
--filter '{"conjonction":"and","groups":[]}'
--sort '[{"columnSlug":"created_at","kind":"desc"}]'
--limit 1000

**IMPORTANT:** `segment download` requires `--model-uuid`, not `--segment-uuid`. Get the `modelUuid` from `segment list`.

For live paginated queries with enrichment, use `segmentation segment fetch` from the `cargo-orchestration` skill.
cargo-ai segmentation segment download
--model-uuid <uuid>
--filter '{"conjonction":"and","groups":[]}'
--sort '[{"columnSlug":"created_at","kind":"desc"}]'
--limit 1000

**重要提示：**`segment download`需要`--model-uuid`，而非`--segment-uuid`。请从`segment list`中获取`modelUuid`。

如需带富集功能的实时分页查询，请使用`cargo-orchestration` skill中的`segmentation segment fetch`。

Help

帮助

Every command supports 
--help
:
bash
cargo-ai billing usage get-metrics --help
cargo-ai orchestration run download --help
cargo-ai segmentation segment download --help
每个命令都支持
--help
参数：
bash
cargo-ai billing usage get-metrics --help
cargo-ai orchestration run download --help
cargo-ai segmentation segment download --help