Cargo Analytics

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.

Prerequisites

See `../cargo/references/prerequisites.md` for install, login (--oauth / --token), JSON output conventions, and error shapes. Verify the session with cargo-ai whoami before running any of the commands below.

Discover resources first

Most analytics commands require UUIDs. Discover them before querying.

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

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

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

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

# 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 — full run records (metadata + per-node 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.

# All finished runs
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>

# Specific statuses
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>

run download-outputs — output of a specific node (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 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.

# Required: --workflow-uuid + --output-node-slug
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.

Downloading batch results

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:

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 errors for the batch:

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

Step 3 — Download failed runs to inspect root causes:

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

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

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

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

cargo-ai billing usage get-metrics --help
cargo-ai orchestration run download --help
cargo-ai segmentation segment download --help

Data export examples

Download all finished runs

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

Download runs by status

# 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

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

Download runs from a specific batch

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

Download batch output by node

# 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

# 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

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

# 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

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

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

Response:

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

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

Metrics scoped to a specific batch

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

Metrics for a date range

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

Count errors

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

Response:

{ "count": 42 }

# 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

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

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

Per-workflow cost analysis (full flow)

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

# 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

List runs with filters

# 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

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

{
  "count": 42
}

cargo-ai orchestration run list

{
  "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 the output data for the specified node as a downloadable payload. The response is streamed to stdout.

Troubleshooting

Common errors and recovery steps for cargo-analytics commands.

General

Run metrics and counts

Downloads and exports