cargo-analytics

# Data export examples

## Download all finished runs

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

## Download runs by status

```bash
# Only successful runs
cargo-ai orchestration run download \
  --workflow-uuid <uuid> \
  --statuses success

# Both success and error (for analysis)
cargo-ai orchestration run download \
  --workflow-uuid <uuid> \
  --statuses success,error

# Only error runs (for debugging)
cargo-ai orchestration run download \
  --workflow-uuid <uuid> \
  --statuses error
```

## Download runs in a date range

```bash
cargo-ai orchestration run download \
  --workflow-uuid <uuid> \
  --created-after 2025-01-01 \
  --created-before 2025-01-31
```

## Download runs from a specific batch

```bash
cargo-ai orchestration run download \
  --workflow-uuid <uuid> \
  --batch-uuid <batch-uuid>
```

## Download batch output by node

```bash
# 1. Get the batch and its release UUID
cargo-ai orchestration batch get <batch-uuid>
# → Extract releaseUuid

# 2. Find the output node slug
cargo-ai orchestration release get <release-uuid>
# → Read nodes[].slug — pick the output node's slug

# 3. Download
cargo-ai orchestration batch download \
  --uuid <batch-uuid> \
  --output-node-slug <node-slug>
```

## Export all segment data

```bash
# 1. List segments to find the modelUuid
cargo-ai segmentation segment list
# → Extract modelUuid (NOT segment uuid)

# 2. Full export
cargo-ai segmentation segment download \
  --model-uuid <model-uuid> \
  --filter '{"conjonction":"and","groups":[]}'
```

## Export segment data with sorting and limit

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

## Export filtered segment data

```bash
# Export only churned accounts
cargo-ai segmentation segment download \
  --model-uuid <model-uuid> \
  --filter '{
    "conjonction": "and",
    "groups": [{
      "conjonction": "and",
      "conditions": [
        {"kind": "string", "columnSlug": "status", "operator": "is", "values": ["churned"]}
      ]
    }]
  }'

# Export US companies with 100+ employees
cargo-ai segmentation segment download \
  --model-uuid <model-uuid> \
  --filter '{
    "conjonction": "and",
    "groups": [{
      "conjonction": "and",
      "conditions": [
        {"kind": "string", "columnSlug": "country", "operator": "is", "values": ["US"]},
        {"kind": "number", "columnSlug": "employee_count", "operator": "greaterThan", "value": 100}
      ]
    }]
  }'

# Export records created after a date
cargo-ai segmentation segment download \
  --model-uuid <model-uuid> \
  --filter '{
    "conjonction": "and",
    "groups": [{
      "conjonction": "and",
      "conditions": [
        {"kind": "date", "columnSlug": "created_at", "operator": "greaterThan", "value": "2025-01-01"}
      ]
    }]
  }'
```

## Export a segment with non-null email

```bash
cargo-ai segmentation segment download \
  --model-uuid <model-uuid> \
  --filter '{
    "conjonction": "and",
    "groups": [{
      "conjonction": "and",
      "conditions": [
        {"kind": "string", "columnSlug": "email", "operator": "isNotNull"}
      ]
    }]
  }'
```

# Run analytics examples

## Get metrics for a workflow

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

Response:

```json
{
  "runMetrics": [
    {
      "nodeUuid": "node-uuid-1",
      "totalExecutionsCount": 1000,
      "successExecutionsCount": 950,
      "errorExecutionsCount": 30,
      "cancelledExecutionsCount": 5,
      "creditsUsedCount": 450
    }
  ]
}
```

Error rate per node = `errorExecutionsCount / totalExecutionsCount`. High error rate on a specific node means that step is failing.

## Metrics scoped to a specific release

```bash
cargo-ai orchestration run get-metrics \
  --workflow-uuid <uuid> \
  --release-uuid <release-uuid>
```

## Metrics scoped to a specific batch

```bash
cargo-ai orchestration run get-metrics \
  --workflow-uuid <uuid> \
  --batch-uuid <batch-uuid>
```

## Metrics for a date range

```bash
cargo-ai orchestration run get-metrics \
  --workflow-uuid <uuid> \
  --created-after 2025-01-01 \
  --created-before 2025-01-31
```

## Count errors

```bash
# Total error count
cargo-ai orchestration run count \
  --workflow-uuid <uuid> \
  --statuses error
```

Response:

```json
{ "count": 42 }
```

```bash
# Errors in a specific period
cargo-ai orchestration run count \
  --workflow-uuid <uuid> \
  --statuses error \
  --created-after 2025-01-15 \
  --created-before 2025-01-16

# Errors in a specific batch
cargo-ai orchestration run count \
  --workflow-uuid <uuid> \
  --statuses error \
  --batch-uuid <batch-uuid>
```

## Count finished runs

```bash
cargo-ai orchestration run count \
  --workflow-uuid <uuid> \
  --is-finished

# In a date range
cargo-ai orchestration run count \
  --workflow-uuid <uuid> \
  --is-finished \
  --created-after 2025-01-01 \
  --created-before 2025-01-31
```

## Count successful runs

```bash
cargo-ai orchestration run count \
  --workflow-uuid <uuid> \
  --statuses success
```

## Per-workflow cost analysis (full flow)

```bash
# 1. List workflows
cargo-ai orchestration workflow list

# 2. Get usage grouped by workflow
cargo-ai billing usage get-metrics \
  --from 2025-01-01 --to 2025-01-31 \
  --group-by workflow_uuid

# 3. Drill into a specific workflow
cargo-ai billing usage get-metrics \
  --from 2025-01-01 --to 2025-01-31 \
  --workflow-uuid <uuid>

# 4. Get run-level metrics
cargo-ai orchestration run get-metrics \
  --workflow-uuid <uuid> \
  --created-after 2025-01-01 \
  --created-before 2025-01-31
```

## Error monitoring and debugging (full flow)

```bash
# 1. Count errors
cargo-ai orchestration run count \
  --workflow-uuid <uuid> \
  --statuses error

# 2. Spot-check: count errors in the last 24 hours
cargo-ai orchestration run count \
  --workflow-uuid <uuid> \
  --statuses error \
  --created-after 2025-01-15 \
  --created-before 2025-01-16

# 3. Download error runs for inspection
cargo-ai orchestration run download \
  --workflow-uuid <uuid> \
  --statuses error \
  --created-after 2025-01-15

# 4. Check per-node error rates
cargo-ai orchestration run get-metrics \
  --workflow-uuid <uuid>
# → Compare errorExecutionsCount vs totalExecutionsCount per node
# → High error rate on a specific node = that step is failing
```

This flow ends at **detection** — you now know how many runs fail and which node is the hotspot. To explain *why* (group failures by root cause, trace exemplar runs through `runContext`), continue with the `cargo-diagnostics` skill: `../../../cargo-diagnostics/references/batch-error-sweep.md`, then `run-trace.md` on the exemplars it hands back.

## List runs with filters

```bash
# All runs for a workflow (paginated)
cargo-ai orchestration run list \
  --workflow-uuid <uuid> \
  --limit 20

# Only error runs
cargo-ai orchestration run list \
  --workflow-uuid <uuid> \
  --statuses error \
  --limit 10

# Runs from a specific batch
cargo-ai orchestration run list \
  --workflow-uuid <uuid> \
  --batch-uuid <batch-uuid>

# Runs for a specific record
cargo-ai orchestration run list \
  --workflow-uuid <uuid> \
  --record-id <record-id>
```

# Response shapes

JSON response structures returned by Cargo CLI commands used in the `cargo-analytics` skill.

> For billing response shapes (usage metrics, subscription, invoices), see the `cargo-billing` skill.

## cargo-ai orchestration run get-metrics

```json
{
  "runMetrics": [
    {
      "nodeUuid": "node-uuid-1",
      "totalExecutionsCount": 1000,
      "idleExecutionsCount": 0,
      "pendingExecutionsCount": 5,
      "runningExecutionsCount": 10,
      "successExecutionsCount": 950,
      "errorExecutionsCount": 30,
      "cancelledExecutionsCount": 5,
      "skippedExecutionsCount": 0,
      "creditsUsedCount": 450
    }
  ]
}
```

**Key fields:** `nodeUuid` (identifies the workflow node), `successExecutionsCount`, `errorExecutionsCount`, `creditsUsedCount`.

To compute an error rate: `errorExecutionsCount / totalExecutionsCount`.

## cargo-ai orchestration run count

```json
{
  "count": 42
}
```

## cargo-ai orchestration run list

```json
{
  "runs": [
    {
      "uuid": "run-uuid",
      "workflowUuid": "...",
      "status": "success",
      "batchUuid": "batch-uuid-or-null",
      "releaseUuid": "...",
      "recordId": "rec-123",
      "recordTitle": "Acme Corp",
      "createdAt": "2025-01-15T10:00:00Z",
      "finishedAt": "2025-01-15T10:00:05Z"
    }
  ]
}
```

## cargo-ai segmentation segment download

Returns raw data as a downloadable payload (typically CSV or JSON depending on the CLI output format). The response is streamed to stdout.

## cargo-ai orchestration batch download

Returns `{"url": "..."}` — a signed URL to a file, **not** the data on stdout. Each row is a batch record joined to its run's output for the chosen node (defaulting to the last executed node), so a record whose run errored comes back with its input fields and no output.

## cargo-ai orchestration run download

Returns `{"url": "..."}` — a signed URL to a **gzipped CSV**. One row per run: `_uuid`, `_workspace_uuid`, `_workflow_uuid`, `_record_id`, `_record_title`, `_created_at`, `_finished_at`, `_status`, `_error_message`, then one column per node slug holding that execution's `title` (a truncated summary, not the node's output). No `runContext`, no `executions[]`.

## cargo-ai orchestration run download-outputs

Returns `{"url": "..."}` — a signed URL to CSV (default) or JSON. One row per run: the `_`-prefixed run metadata above, plus `input` (first node's resolved config) and `output` (chosen node's context, defaulting to the last executed node).

# Troubleshooting

Common errors and recovery steps for `cargo-analytics` commands.

## General

| Symptom | Cause | Fix |
|---------|-------|-----|
| `{"errorMessage": "..."}` with non-zero exit | Any CLI error | Read the `errorMessage` — it usually says exactly what's wrong |
| `command not found: cargo-ai` | CLI not installed or not in PATH | Run `npm install -g @cargo-ai/cli` or prefix with `npx @cargo-ai/cli` |
| `Unauthorized` or `Forbidden` | Bad or expired credentials | Re-run `cargo-ai login --oauth` (browser sign-in) or `cargo-ai login --token <token>`; verify with `cargo-ai whoami` |

## Run metrics and counts

| Symptom | Cause | Fix |
|---------|-------|-----|
| `run get-metrics` returns empty array | No runs exist for that workflow/period | Verify the `--workflow-uuid`; try without date filters to check if any runs exist |
| Error count seems too high | Counting across all time | Scope with `--created-after` and `--created-before` for a specific period |
| `run count` returns 0 unexpectedly | Filter combination too narrow | Remove filters one at a time to isolate which one excludes all runs |

## Downloads and exports

| Symptom | Cause | Fix |
|---------|-------|-----|
| `run download` returns empty | No runs match the filters | Loosen filters — drop the date and status constraints and pass `--workflow-uuid` alone |
| `run download` returns `500 Internal Server Error` | The workflow resolves to zero active nodes — all archived, or the UUID doesn't exist in this workspace. The export builds one column per node slug, so there is nothing to select | Confirm the UUID with `workflow list` / `play list`. Loosening filters won't help; the failure is about the workflow, not the runs |
| `400 unrecognized_keys: <flag>` on a run command | The CLI offers a flag the API's request schema doesn't accept | Drop the flag and express the filter another way — `--statuses success,error` covers "finished". Then report it: `workspaceManagement report create` |
| `batch download` fails with "node not found" | Wrong `--output-node-slug` | Re-run `release get <release-uuid>` and check `nodes[].slug` for the correct value |
| `segment download` returns empty | Wrong model UUID or over-filtered | Verify `--model-uuid` (not `--segment-uuid`); try empty filter `{"conjonction":"and","groups":[]}` first |
| Parse error on filter JSON | Malformed JSON or wrong spelling | Check: it's `conjonction` (not `conjunction`); validate JSON syntax; see the `cargo-orchestration` skill's `references/filter-syntax.md` |

{
  "$comment": "Generated by .github/scripts/skills-metadata.mjs — do not hand-edit. Regenerate with: node .github/scripts/skills-metadata.mjs --write .",
  "name": "cargo-analytics",
  "version": "1.5.0",
  "documents": [
    {
      "path": "SKILL.md",
      "kind": "entrypoint",
      "title": "Cargo CLI — Analytics"
    },
    {
      "path": "references/examples/exports.md",
      "kind": "example",
      "title": "Data export examples"
    },
    {
      "path": "references/examples/run-analytics.md",
      "kind": "example",
      "title": "Run analytics examples"
    },
    {
      "path": "references/response-shapes.md",
      "kind": "reference",
      "title": "Response shapes"
    },
    {
      "path": "references/troubleshooting.md",
      "kind": "reference",
      "title": "Troubleshooting"
    }
  ],
  "contentHash": "47b4bd3af2fbc699c1d92eaf2a7b5b98d83aa11f1591679563c2fb3ec8a0f0e9"
}

---
name: cargo-analytics
description: "Get data out of Cargo and measure what ran — download a run output, export a segment or model to CSV or JSON, and pull run and batch success and error counts. Triggers: \"download the results\", \"export this to CSV\", \"give me the file\", \"how many succeeded\", \"what is my error rate\", \"send me the enriched list\", \"get the output of that run\", \"how many records did it write\". Skip when: asking why something failed or where credits went — use cargo-diagnostics; asking about credits, plans, or invoices — use cargo-billing."
version: "1.5.0"
compatibility: Requires @cargo-ai/cli (npm). Sign in or create an account with `cargo-ai login --email` (emailed code, no browser), `--oauth`, or an API token
homepage: https://github.com/getcargohq/cargo-skills
metadata:
  author: getcargo
  openclaw:
    requires:
      bins:
        - cargo-ai
    install:
      - kind: node
        package: "@cargo-ai/cli@latest"
        bins:
          - cargo-ai
    homepage: https://github.com/getcargohq/cargo-skills
---

# Cargo CLI — Analytics

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.

## Bootstrap

Already signed in (`cargo-ai whoami` returns a workspace)? Skip to the next section.

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

Every command prints JSON to stdout; failures exit non-zero with `{"errorMessage": "..."}`. Anything that creates a run or a batch is async — pass `--wait-until-finished` or poll the matching `get`. When the full skill bundle is installed, [`../cargo/references/prerequisites.md`](../cargo/references/prerequisites.md) adds the CLI version pin, token scopes, and the admin-only surface.

## Scope — measure and export, not explain

This skill answers **"what happened"** and **"give me the data"**: metrics, counts, downloads, exports. The moment the question becomes **"why"** — why did this run fail, why is the output wrong or empty, which root cause explains these errors, why is this play so expensive — switch to the `cargo-diagnostics` skill; its runbooks sequence the raw surfaces into a diagnosis.

| The question sounds like… | Load |
| --- | --- |
| "What's the error rate?" / "How many runs failed this week?" / "Export the results / segment" | **this skill** |
| "Why did this run fail?" / "Run succeeded but the output looks wrong" | `cargo-diagnostics` → `references/run-trace.md` |
| "Why does this batch have errors? Which node keeps failing, and is it one cause or many?" | `cargo-diagnostics` → `references/batch-error-sweep.md` |
| "Why is this play so expensive? Where do the credits go?" | `cargo-diagnostics` → `references/play-optimize-credits.md` |

The two skills chain naturally: analytics **detects** (error rate spiked, batch reports failures), diagnostics **explains** (18 of 20 failures share one root cause), then analytics **retrieves** the clean results once the cause is fixed and the runs re-executed.

## 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)
```

## 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 orchestration query execute "SELECT status, count() FROM runs GROUP BY status"
cargo-ai segmentation segment download --model-uuid <uuid> --filter '{"conjonction":"and","groups":[]}'
```

**Picking the right command:**

- `run get-metrics` / `run count` — workflow-scoped, predefined aggregations. Best when you already have a `workflowUuid`.
- `orchestration query execute` — ad-hoc SQL across the entire workspace (`runs`, `batches`, `spans`, `records`). Best for cross-workflow analytics, per-node breakdowns, and time-series.
- `run download` / `run download-outputs` — per-record output retrieval.
- `segment download` / `storage query execute` — storage data (Companies, Contacts, …).

## Workflow run metrics

Aggregated metrics for workflow runs (success/error rates, credits per node).

```bash
# Metrics for a workflow
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>
```

## 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`.

For cross-workflow analytics or shapes that `run count` doesn't expose (per-node failure breakdowns, p95 durations, error rate over time), use `orchestration query execute` — see the [Ad-hoc execution analytics](#ad-hoc-execution-analytics-orchestration-query) section.

## Ad-hoc execution analytics (`orchestration query`)

Run SQL against orchestration runtime tables — `runs`, `batches`, `spans`, `records` — for analytics that the canned metrics commands don't cover. Tables are referenced without a schema prefix; workspace scoping is automatic. See `cargo-orchestration/references/examples/queries.md` for schemas and limits.

```bash
# Error rate across the workspace in the last day
cargo-ai orchestration query execute \
  "SELECT countIf(status='error') / count() AS error_rate FROM runs WHERE created_at > now() - INTERVAL 1 DAY"

# Failed runs per workflow this week
cargo-ai orchestration query execute \
  "SELECT workflow_uuid, count() AS errors FROM runs WHERE status='error' AND created_at > now() - INTERVAL 7 DAY GROUP BY workflow_uuid ORDER BY errors DESC"

# Per-node failure counts (last 24h)
cargo-ai orchestration query execute \
  "SELECT node_slug, count() AS failures FROM spans WHERE execution_status='error' AND execution_started_at > now() - INTERVAL 1 DAY GROUP BY node_slug ORDER BY failures DESC"

# Credit spend by workflow this month
cargo-ai orchestration query execute \
  "SELECT workflow_uuid, sum(credits_used_count) AS credits FROM batches WHERE created_at >= toStartOfMonth(now()) GROUP BY workflow_uuid ORDER BY credits DESC"
```

Read-only and capped: 30s execution time, 10 000 result rows, 10 000 000 rows scanned. Narrow with a `created_at`/`execution_started_at` predicate to stay under the row-scan cap.

## Downloading run results

Two distinct commands — pick the right one for the job.

### `run download` — one row per run, one column per node (gzipped CSV)

Returns `{"url": "..."}` — a signed URL to a **gzipped CSV**. Each row is a run: `_uuid`, `_workspace_uuid`, `_workflow_uuid`, `_record_id`, `_record_title`, `_created_at`, `_finished_at`, `_status`, `_error_message`, followed by **one column per node slug**.

**Each node column holds that execution's `title` — a truncated human-readable summary, not the node's output.** There is no `runContext` and no `executions[]` in this file. Treat it as a status board across many runs (which node errored, on which record), never as evidence of what a node produced — the same rule `cargo-diagnostics` applies to `title` everywhere else.

```bash
# Every run of a workflow
cargo-ai orchestration run download --workflow-uuid <uuid>

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

# Specific statuses (run statuses: idle, pending, running, success, error,
# cancelling, cancelled, skipped — NOT "finished"/"failed")
cargo-ai orchestration run download --workflow-uuid <uuid> --statuses success,error

# Every run that reached a terminal state. `--is-finished` is `finished_at IS
# NOT NULL`, which is wider than success+error: cancelled and skipped runs
# stamp finishedAt too, so don't substitute one for the other.
cargo-ai orchestration run download --workflow-uuid <uuid> --is-finished

# From a specific batch
cargo-ai orchestration run download --workflow-uuid <uuid> --batch-uuid <uuid>
```

### `run download-outputs` — per-run input + output (CSV/JSON via signed URL)

**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. One row per run: the same `_`-prefixed run metadata, plus `input` (the first node's resolved config) and `output` (the chosen node's context, defaulting to the **last executed node** when `--output-node-slug` is omitted).

```bash
# --workflow-uuid is the only required flag
cargo-ai orchestration run download-outputs \
  --workflow-uuid <uuid> \
  --format json \
  --limit 20

# Pin the output node explicitly, and filter by batch
cargo-ai orchestration run download-outputs \
  --workflow-uuid <uuid> \
  --output-node-slug <slug> \
  --batch-uuid <uuid>
```

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`. Without `--limit`, the file covers **every** matching run of the workflow, so pass one when you only need a sample.

### Getting the full `runContext` for several runs

You can't, in one call. The full per-node context is a **per-run S3 object**, and `orchestration run get <run-uuid>` is the only command that hydrates it — one run at a time. The two exports above are projections: `download` gives you node *titles* across many runs, `download-outputs` gives you first-node input + one node's output across many runs. For everything in between, loop `run get` over the UUIDs from the discovery ladder in [`../cargo-diagnostics/references/run-trace.md`](../cargo-diagnostics/references/run-trace.md) § 0.

Orchestration SQL is not an alternative here: `runs` and `spans` carry status, timing, and credits, but no node input/output columns.

## 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`.

## 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>
# → .runsCount          = total records submitted
# → .executedRunsCount  = records that reached a terminal state (success or error)
# → .failedRunsCount    = records that errored
```

**Step 2 — Count and download the failed runs:**

```bash
cargo-ai orchestration run count \
  --workflow-uuid <uuid> \
  --batch-uuid <batch-uuid> \
  --statuses error

cargo-ai orchestration run download \
  --workflow-uuid <uuid> \
  --batch-uuid <batch-uuid> \
  --statuses error
```

**Step 3 — Diagnose.** Working out *why* they failed — grouping failures by root cause, picking exemplar runs, reading `runContext` — is the `cargo-diagnostics` skill's job: load `../cargo-diagnostics/references/batch-error-sweep.md` and feed it the batch UUID.

**Step 4 — Re-run only the failed records:**

After the diagnosis and fixing the underlying issue (connector credentials, bad input data, rate limits):

```bash
# Extract record IDs from the failed run download, then:
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
# 1. Get the release UUID from the batch
cargo-ai orchestration batch get <batch-uuid>
# → .releaseUuid

# 2. Find the node slug
cargo-ai orchestration release get <release-uuid>
# → nodes[].slug

# 3. Download that node's output
cargo-ai orchestration batch download \
  --uuid <batch-uuid> \
  --output-node-slug <node-slug>
```

## 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
# Full export (all records)
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.

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