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

# Monitor runs

> Stream progress, inspect status and errors, and list historical runs.

Stream updates until the run completes or disconnects.

<CodeGroup>
  ```bash CLI theme={null}
  valkyrie run fetch <run-id> --connect
  ```

  ```python Python SDK theme={null}
  async for update in client.runs.stream(run_id):
      print(update.details.status)
  ```
</CodeGroup>

Full syntax for each command below is in the [`run fetch`](/reference/cli/run#fetch), [`run status`](/reference/cli/run#status), [`run errors`](/reference/cli/run#errors), and [`run list`](/reference/cli/run#list) reference, and in [`client.runs.stream`](/reference/sdk/runs#stream) for Python.

## Fetch one run

Use a one-time text or machine-readable snapshot when streaming is not needed:

```bash theme={null}
valkyrie run fetch <run-id>
valkyrie run fetch <run-id> --format json
valkyrie run fetch <run-id> --connect --format jsonl
```

Connected text output shows run identity and metadata before progress updates. JSONL begins with a `snapshot` record, followed by `update` records. Recognized termination emits `complete`, `error`, `stopped`, `disconnect`, or `interrupted`.

Exit code 0 means the CLI handled the tracker response or stream event. It does not mean the benchmark succeeded. Inspect the run `status` and each JSONL record's `event`.

### Machine-readable output

Unexpected clean JSONL exhaustion emits a final `disconnect` record and exits nonzero. Transport or malformed-protocol failures can exit nonzero without a final record. In fetch output, `metadata_available: false` means identity metadata could not load. Batch `finished_tasks` includes `FINISHED`, `ERROR`, and `STOPPED` tasks.

## Check several run IDs

```bash theme={null}
valkyrie run status --ids <run-id-1>,<run-id-2> --format json
```

Batch status preserves requested order, ignores duplicate IDs, and requests at most 50 IDs at a time. Missing or inaccessible IDs appear in `missing_run_ids` and make the command exit nonzero after it emits the JSON document.

## Inspect errors

```bash theme={null}
valkyrie run errors <run-id>
```

The command shows stored run and current task error messages. Add `--format json` to consume them from a script.

## List runs

Filter the history to find a run:

```bash theme={null}
valkyrie run list --benchmark-name swebench --status IN_PROGRESS
```

Filters combine, and the interactive list supports `[h]` for previous, `[l]` for next, and `[q]` to quit. Emit all matching runs as one document with:

```bash theme={null}
valkyrie run list --format json --all --status IN_PROGRESS
```

Machine-readable output uses a versioned allowlist. It excludes stored agent secrets, kwargs, and raw error messages. Optional identity fields and scores can be `null`; timestamps are UTC ISO 8601 strings, and non-finite scores become `null`.