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

# Inspect runs

> Use probe, step-overview, and logs to understand a recorded run.

Start every investigation with the run overview. It returns the first 20
immediate steps in the root run, including persisted summaries when available.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara probe <run-id>
```

Use `--range` for another zero-based, end-exclusive page:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara probe <run-id> --range 20:40
```

Subruns stay collapsed in their parent overview. Open one with `--scope`; the
range applies to that subrun's immediate steps, not to a flattened tree.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
root
├── 1
├── 2
└── 3 subrun
    ├── 3.1
    └── 3.2 subrun
        ├── 3.2.1
        └── 3.2.2
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara probe <run-id> --scope 3
sovara probe <run-id> --scope 3.2
```

The first command returns `3.1` and `3.2`; the second returns `3.2.1` and
`3.2.2`. Nesting can continue to any depth.

## Inspect one step

Use the `step_ref` from the overview:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara probe <run-id> --step 3 --preview
```

`--preview` keeps large fields readable. Use it before fetching full input or
output.

## Inspect selected keys

Use `--input`, `--output`, and `--key-regex` when you know the field you need:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara probe <run-id> --step 3 --input --key-regex "body.max_tokens$"
sovara probe <run-id> --step 3 --output --key-regex "content"
```

This is safer than dumping full prompts, tool arguments, or response payloads.

## Get a semantic summary

When the exact payload is less important than the behavior, ask Sovara for a
step overview:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara step-overview <run-id> --step 3
```

## Read logs

Use logs for captured stdout and stderr:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara logs <run-id> --tail 100
sovara logs <run-id> --grep "Cache miss" --context 2 --line-numbers
```

## Good inspection sequence

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara runs --project-id <project-id-or-name> --limit 20 --sort timestamp --dir desc
sovara probe <run-id>
sovara probe <run-id> --scope 6 --range :20
sovara probe <run-id> --scope 6.2 --range :20
sovara probe <run-id> --step 6.2.1 --preview
sovara logs <run-id> --tail 80
```

Use step refs such as `6.2`, not internal IDs.