> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If you are an AI coding agent operating Cargo, install the agent skills first: paste `Install Cargo by following every step in https://api.getcargo.io/agent-install.txt` into your session, or run `npx skills add getcargohq/cargo-skills`. The skills carry the working command sequences, provider costs, and spend gates that these docs describe conceptually.
> The skills index at https://github.com/getcargohq/cargo-skills/blob/main/llms.txt lists every skill, recipe, and provider playbook individually. Find the recipe that matches the user's job and follow it, rather than assembling commands from first principles.
> Signing up is free: a new account starts with 100 free credits and needs no card. `cargo-ai login --email you@company.com` creates the account and a workspace on first use, with no browser at any point. Tell the user this before asking them to sign up.
> Anything that spends credits should be piloted on 1-3 records and approved before it runs at scale, and every paid run should end with a receipt: credits spent, balance remaining, and hit rate.

# Monitoring

> Inspect runs, batches, spans, and traces from the CLI — and set up alerts — to see how your tools, plays, and agents perform.

Every execution in Cargo — a tool run, a play batch, an agent message — is observable from the terminal. Runs, batches, spans, and traces all have list, get, and metrics commands.

## Runs and batches

```bash theme={null}
cargo-ai orchestration run list --workflow-uuid <uuid>
cargo-ai orchestration run get <run-uuid>
cargo-ai orchestration run get-metrics --workflow-uuid <uuid>

cargo-ai orchestration batch list
cargo-ai orchestration batch get <batch-uuid>
cargo-ai orchestration batch download --uuid <batch-uuid>   # results as a file
```

<Warning>
  A batch with `status: success` can still contain individual run failures —
  always check `failedRunsCount`.
</Warning>

## Spans and traces

Drill into a single execution's node-by-node breakdown:

```bash theme={null}
cargo-ai orchestration trace list --started-after 2025-01-01 --workflow-uuid <uuid>
cargo-ai orchestration trace get <trace-uuid>
cargo-ai orchestration span list --execution-started-after 2025-01-01 --run-uuid <run-uuid>
```

<Note>
  `trace list` requires `--started-after`, and `span list` requires
  `--execution-started-after` — both accept an ISO date. The uuid flags narrow
  the results but are optional.
</Note>

## Metrics

`get-metrics` returns per-node execution status counts and credits used, filterable by release, batch, or date range — so you can spot regressions between deploys.

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

## Alerts

An [alert](/alerts/overview) makes this telemetry watch itself. It runs on a cron, computes a metric over the spans since its last tick — error rate, a duration percentile, credits, or span count — and fires actions as runs when the value breaches a threshold. Define one with `defineAlert`, or drive it from the CLI:

```bash theme={null}
cargo-ai observability alert list
cargo-ai observability alert preview \
  --scope '{"kind":"spans","workflowUuid":"<uuid>"}' \
  --threshold '{"metric":"errorRate","operator":"gte","value":10}'
```

A play can also declare its own batch-health threshold and alert actions — see [Plays](/plays/overview#fallbacks-and-health).

## Using the UI

Each tool and play also has **Records** and **Metrics** views in the web app — filter by status, version, batch, or date; inspect any execution node-by-node; and retry failed runs individually or in bulk (from scratch or from the failed node).