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

# oqoqo runs and results

> List runs, read a run's profile, trajectory, transcript, and output, and analyze results from the terminal.

Page through a project's runs, open one run's recorded work, or analyze many runs at once. In the dashboard, the same results are on [Read results](https://docs.oqoqo.ai/evaluation/results.md) and [Run details](https://docs.oqoqo.ai/evaluation/traces.md).

A run is one agent attempt on one task with one treatment. Each trial is its own run, so a trial ID is also a `run_` ID.

## Run scope flags

The run scope flags narrow a command to the runs that a set of records shaped. `oqoqo runs list`, `oqoqo frictions list`, and `oqoqo frictions get` take all of them. [`oqoqo experiments list`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-list) takes all of them except `--experiment-id`, and lists the experiments of those runs. [`oqoqo results analyze`](#oqoqo-results-analyze) takes them too, but its `--experiment-id`, `--task-id`, and `--friction-id` are its own analysis flags.

| Flag | Takes | Counts only the runs |
| - | - | - |
| `--experiment-id` | `exp_` | Of this experiment |
| `--schedule-id` | `sch_` | Of the experiments this schedule launched |
| `--task-id` | `tsk_` | Of this task, in every version |
| `--task-version-id` | `tskver_` | Of this task version |
| `--treatment-id` | `trt_` | Of this treatment (toolset) |
| `--tool-id` | `skl_`, `mcp_`, `cli_`, `sdk_` | Whose treatment gave the agent this skill, MCP server, CLI, or SDK, in any version |
| `--tool-version-id` | `sklver_`, `mcpver_`, `cliver_`, `sdkver_` | Whose treatment gave the agent this tool version |
| `--file-id` | `fld_` | Whose task had this file |
| `--machine-id` | `env_` | Whose task ran on this machine |
| `--agent-id` | An agent key, such as `claude-code` | Of this agent, with any model. The key is a run's `agentId`. |
| `--agent-model-id` | `agm_` | Of this agent and model, from `oqoqo catalog list --kind agent` |
| `--friction-id` | `frc_` | Where this friction occurred |

Each flag takes one ID, and a run counts only when it matches every flag you pass.

* An ID with the wrong prefix is a usage error. The message says where the right ID comes from.
* An ID that the project doesn't have fails with `scope_not_found` instead of returning an empty list. The error names each ID it couldn't find.
* The runs and frictions results return `scope`: each record they counted, with its `kind`, `id`, current `name`, and `dashboardUrl`.

## oqoqo runs list

Page every run of the current project, newest first, with stable IDs, outcomes, and errors.

```bash theme={null}
oqoqo runs list [flags]
```

**Plugin (MCP) tool:** [`list_runs`](https://docs.oqoqo.ai/mcp-server/runs-and-results#list_runs)

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--experiment-id` | string | | Only the runs of this `exp_` experiment. |
| `--schedule-id` | string | | Only the runs of the experiments that this `sch_` schedule launched. |
| `--task-id` | string | | Only the runs of this `tsk_` task, in every version. |
| `--task-version-id` | string | | Only the runs of this `tskver_` task version. |
| `--treatment-id` | string | | Only the runs of this `trt_` treatment (toolset). |
| `--tool-id` | string | | Only the runs whose treatment gave the agent this skill, MCP server, CLI, or SDK (`skl_`, `mcp_`, `cli_`, or `sdk_`), in any version. |
| `--tool-version-id` | string | | Only the runs whose treatment gave the agent this tool version (`sklver_`, `mcpver_`, `cliver_`, or `sdkver_`). |
| `--file-id` | string | | Only the runs whose task had this `fld_` file. |
| `--machine-id` | string | | Only the runs whose task ran on this `env_` machine. |
| `--agent-id` | string | | Only the runs of this agent key, such as `claude-code`, with any model. |
| `--agent-model-id` | string | | Only the runs of this `agm_` agent and model. |
| `--friction-id` | string | | Only the runs where this `frc_` friction occurred. |
| `--query` | string | | Words in the task name or key, the agent, the model, or the run ID. |
| `--status` | string | | Comma-separated run statuses: `queued`, `running`, `completed`, `errored`, or `cancelled`. At most 20. |
| `--outcome` | string | | Comma-separated outcomes, such as `pass`, `fail`, `evals_failed`, `infra_blocked`, or `inconclusive`. At most 20. |
| `--task-key` | string | | Only the runs of the task with this key. |
| `--treatment` | string | | Only the runs of the treatment with this key or label. |
| `--agent` | string | | Only the runs of the agent with this key or name. |
| `--model-id` | string | | Only the runs of this model ID. |
| `--effort-level` | string | | Only the runs at this effort level. |
| `--provider` | string | | Only the runs on the provider connection with this exact name, as `providerDisplayName` reports it. |
| `--completed-after` | string | | Only the runs that completed at or after this ISO 8601 date-time. |
| `--completed-before` | string | | Only the runs that completed before this ISO 8601 date-time. |
| `--limit` | integer | `50` | Results per page, up to 200 (default 50). |
| `--cursor` | string | | The `nextCursor` from the previous page. |

The first twelve flags are the [run scope flags](#run-scope-flags). Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

List the failed runs of one experiment:

```bash theme={null}
oqoqo runs list --experiment-id exp_8f2c41d0 --outcome fail
```

List every run where a friction occurred:

```bash theme={null}
oqoqo runs list --friction-id frc_7d20e6b4 --output json
```

List every run whose treatment gave the agent one MCP server:

```bash theme={null}
oqoqo runs list --tool-id mcp_2e8b6f13 --output json
```

**Result fields**

Each run has its `runId` and `trialId`, the task, the treatment, and the agent with its model and effort, plus these fields. The result also has `scope`, `hasMore`, and `nextCursor`.

| Field | Meaning |
| - | - |
| `criteriaSummary` | The result in plain words. |
| `treatmentUse` | Whether the agent used the treatment, with each skill, MCP server, CLI, and SDK and its state. `null` when the run has no usable [run profile](https://docs.oqoqo.ai/evaluation/run-profile.md). |
| `error` | A typed error with a `code` and a `message`, when the run errored. |
| `blockedReason` | On a blocked run, its `cause` and a one-line `message`. |
| `setupFailure` | Present when a setup command stopped the run before its agent started. The fields are in the next table. |
| `providerDisplayName` | The provider connection's name. Runs that share agent, model, and effort can differ only by this field; filter them with `--provider`. |

| `setupFailure` field | Meaning |
| - | - |
| `owner` | The machine, CLI, or SDK step that declared the command. `null` for a package install. |
| `commandNumber` | Which command failed, when the owner has several commands of that kind |
| `manager`, `packageOwners` | For a package install, the package manager and who declared the packages |
| `command` | The command that failed |
| `exitCode` or `timeoutSeconds` | How it failed |
| `output` | Its last output lines |

**Notes**

Continue with `--cursor` while `hasMore` is true. To fix a setup failure, see [A run could not start because a setup command failed](https://docs.oqoqo.ai/reference/troubleshooting.md#a-run-could-not-start-because-a-setup-command-failed).

## oqoqo runs profile

Show where one run's tool calls, time, and tokens went, and which skills, MCP servers, CLIs, and SDKs from its treatment the agent used.

```bash theme={null}
oqoqo runs profile <run-id> [flags]
```

**Plugin (MCP) tool:** [`get_run_profile`](https://docs.oqoqo.ai/mcp-server/runs-and-results#get_run_profile)

**Arguments**

| Argument | Description |
| - | - |
| `<run-id>` | Required. The run's `run_` ID. |

Takes only the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

```bash theme={null}
oqoqo runs profile run_6b31e09f --output json
```

**Notes**

This is the [Run profile](https://docs.oqoqo.ai/evaluation/run-profile.md) rail on run details: treatment use, tool calls, what stood out, and time. Counts and times are exact or absent, because Oqoqo never estimates a missing count or time.

A run that a setup command stopped has `setupFailure`, with the fields listed under [`oqoqo runs list`](#oqoqo-runs-list). The text output names the step and what to fix, prints the [`oqoqo resources inspect`](https://docs.oqoqo.ai/cli/catalog#oqoqo-resources-inspect) command for the machine or tool that declared it, then shows the command and its output.

## oqoqo runs trajectory

Read one page of a run's ordered steps, with token usage and measured tool durations.

```bash theme={null}
oqoqo runs trajectory <run-id> [flags]
```

**Plugin (MCP) tool:** [`get_run_trajectory`](https://docs.oqoqo.ai/mcp-server/runs-and-results#get_run_trajectory)

**Arguments**

| Argument | Description |
| - | - |
| `<run-id>` | Required. The run's `run_` ID. |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--after-ordinal` | integer | | Start after this step. Send the `nextAfterOrdinal` of the previous page. The minimum is `-1`. |
| `--projection` | `compact`, `full` | `compact` | `compact` gives each step a text preview of up to 512 bytes. `full` gives each step's complete recorded fields. |
| `--limit` | integer | `100` | Results per page, up to 500 (default 100). |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Read the first 500 steps, then the next page:

```bash theme={null}
oqoqo runs trajectory run_6b31e09f --limit 500 --output json
oqoqo runs trajectory run_6b31e09f --after-ordinal 499 --output json
```

**Result fields**

| Field | Meaning |
| - | - |
| Steps | In ordinal order, grouped by the model turn that produced them. |
| `truncated`, `nextAfterOrdinal` | While `truncated` is true, more steps remain. Send `nextAfterOrdinal` as `--after-ordinal` to read the next page. |
| `coverage` | `firstOrdinal`, `lastOrdinal`, `totalSteps`, and `complete`. |
| Run header tokens and cost | The reported input, cached input, and output tokens, and the cost with its `costSource`. Unknown totals stay `null`. |
| `stopReason`, `reportedModelId`, `reportedModelName`, `agentError` | For a [custom agent](https://docs.oqoqo.ai/setup/custom-agents.md) only: why it stopped, the model it reported, and why it failed before it answered. These fields are `null` for other agents. |
| `setupFailure` | Present when a setup command stopped the run, as in [`oqoqo runs list`](#oqoqo-runs-list). |

**Notes**

For a summary of the whole run, use [`oqoqo runs profile`](#oqoqo-runs-profile).

## oqoqo runs transcript

Read one byte-bounded page of a run's original transcript, unchanged.

```bash theme={null}
oqoqo runs transcript <run-id> [flags]
```

**Plugin (MCP) tool:** [`get_run_transcript`](https://docs.oqoqo.ai/mcp-server/runs-and-results#get_run_transcript)

**Arguments**

| Argument | Description |
| - | - |
| `<run-id>` | Required. The run's `run_` ID. |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--trial-id` | string | | Read this trial's transcript, by its `run_` ID. |
| `--offset` | integer | `0` | The byte to start from. Send the `nextOffset` of the previous page. |
| `--limit-bytes` | integer | `12288` | Content bytes in one page, up to 12,288 (default 12,288). |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Read the first page, then the next:

```bash theme={null}
oqoqo runs transcript run_6b31e09f --output json
oqoqo runs transcript run_6b31e09f --offset 12288 --output json
```

**Result fields**

| Field | Meaning |
| - | - |
| `fileName` | The transcript's file name. |
| `byteSize`, `sha256` | The size and SHA-256 of the whole file. |
| `nextOffset`, `eof` | Continue with `--offset` set to `nextOffset` until `eof` is true. |

**Notes**

Use `--output json` to receive the exact bytes. It's the same file that **⋯ → Download trajectory** saves on [run details](https://docs.oqoqo.ai/evaluation/traces.md#download-the-trajectory).

## oqoqo runs output

Read what a run left behind: the file manifest, a diff of one file or the whole run, one file, the agent's final message, or the full archive.

```bash theme={null}
oqoqo runs output <run-id> [flags]
```

**Plugin (MCP) tool:** [`get_run_output`](https://docs.oqoqo.ai/mcp-server/runs-and-results#get_run_output)

**Arguments**

| Argument | Description |
| - | - |
| `<run-id>` | Required. The run's `run_` ID. |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--part` | `final_message`, `diff`, `manifest`, `archive`, `file` | `manifest` | What to read. `manifest` lists the files. `diff` is the whole-run diff, or one file's diff with `--path`. `file` is one file. `final_message` is the agent's last message. `archive` is every retained file. |
| `--path` | string | | The file to read with `--part file`, or to diff with `--part diff`. At most 4,096 characters. |
| `--trial-id` | string | | Read this trial's output, by its `run_` ID. |
| `--offset` | integer | `0` | The byte to start from. Send the `nextOffset` of the previous page. |
| `--limit-bytes` | integer | `12288` | Content bytes in one page, up to 12,288 (default 12,288). |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

List the files a run changed, then read one file's diff:

```bash theme={null}
oqoqo runs output run_6b31e09f
oqoqo runs output run_6b31e09f --part diff --path src/checkout/cart.ts
```

**Result fields**

| Field | Meaning |
| - | - |
| `nextOffset`, `eof` | Continue with `--offset` set to `nextOffset` until `eof` is true. |
| `sourceTruncated` | When true, the `final_message` part is a preview. Read the complete original with [`oqoqo runs transcript`](#oqoqo-runs-transcript). |

**Notes**

Use `--output json` to receive the exact bytes. The dashboard shows the same files on the **Output** tab of [run details](https://docs.oqoqo.ai/evaluation/traces.md).

## oqoqo results analyze

Run one structured analysis over the runs in a scope: summarize, compare treatments, find failures and frictions, or read one run's evidence.

```bash theme={null}
oqoqo results analyze <mode> [flags]
```

**Plugin (MCP) tool:** [`analyze_results`](https://docs.oqoqo.ai/mcp-server/runs-and-results#analyze_results)

**Arguments**

| Argument | Description |
| - | - |
| `<mode>` | Required. The analysis to run. See [Modes](#modes). |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--query` | string | | Words to search for, in the search modes. |
| `--experiment-id` | string | | Only the runs of this `exp_` experiment. |
| `--run-id` | string | | One run, by its `run_` ID. |
| `--trial-id` | string | | One trial, by its `run_` ID. |
| `--runs` | string | | Up to 3 comma-separated `run_` IDs to analyze together, as **Compare** does. A `run~trial` item names one trial of a run. |
| `--task-id` | string | | Only the runs of this `tsk_` task. |
| `--task-key` | string | | Only the runs of the task with this key. |
| `--skill-id` | string | | Only the runs that involve this `skl_` skill. |
| `--skill-key` | string | | Only the runs that involve the skill with this key. |
| `--friction-id` | string | | Only the runs where this `frc_` friction occurred. |
| `--schedule-id` | string | | Only the runs of the experiments that this `sch_` schedule launched. |
| `--task-version-id` | string | | Only the runs of this `tskver_` task version. |
| `--treatment-id` | string | | Only the runs of this `trt_` treatment (toolset). |
| `--tool-id` | string | | Only the runs whose treatment gave the agent this skill, MCP server, CLI, or SDK (`skl_`, `mcp_`, `cli_`, or `sdk_`), in any version. |
| `--tool-version-id` | string | | Only the runs whose treatment gave the agent this tool version (`sklver_`, `mcpver_`, `cliver_`, or `sdkver_`). |
| `--file-id` | string | | Only the runs whose task had this `fld_` file. |
| `--machine-id` | string | | Only the runs whose task ran on this `env_` machine. |
| `--agent-id` | string | | Only the runs of this agent key, such as `claude-code`, with any model. |
| `--agent-model-id` | string | | Only the runs of this `agm_` agent and model. |
| `--treatment` | string | | Only the runs of the treatment with this key or label. |
| `--outcome` | `pass`, `fail`, `evals_failed`, `infra_blocked`, `inconclusive` | | Only the runs with this outcome. `inconclusive` leaves out the runs that Evals can still judge. |
| `--agent` | string | | Only the runs of the agent with this name or key. |
| `--model-id` | string | | Only the runs of this model ID. |
| `--effort-level` | string | | Only the runs at this effort level. |
| `--provider` | string | | Only the runs on the provider connection with this exact name. |
| `--completed-after` | string | | Only the runs that completed at or after this ISO 8601 date-time. |
| `--completed-before` | string | | Only the runs that completed before this ISO 8601 date-time. |
| `--limit` | integer | | The most ranked items to return, up to 100 (default 12 to 100 depending on the mode: 100 for `summarize_scope` and `compare_treatments`, 80 for `get_run_evidence`, 20 for `search_frictions`, 16 for `search_experiment_evidence`, 15 for `rank_tasks_by_friction`, 12 for the rest). Ranked analysis is never paged. |

`--schedule-id` through `--agent-model-id` are [run scope flags](#run-scope-flags). Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

### Modes

| Mode | What it returns |
| - | - |
| `summarize_scope` | Runs, passes, and failures per treatment and per agent, with `pendingRuns`, `inconclusiveRuns`, and `insightsCoverage` |
| `compare_treatments` | Each treatment against the baseline: pass and fail counts, use rate, mean tokens, working time, tool calls, and mean cost per cost source, with the difference from the baseline. It also counts `pendingRuns` and `inconclusiveRuns`. |
| `find_failure_patterns` | Recurring failures in the scope |
| `search_experiment_evidence` | Recorded evidence that matches `--query` |
| `search_frictions` | Frictions that match `--query`, with `insightsCoverage` |
| `get_run_evidence` | One run's evidence, with its `status`, `evalsPending`, and `insightsPending`. Needs `--run-id`, or a trial's `run_` ID in `--trial-id`. |
| `rank_tasks_by_friction` | Tasks ranked by their frictions |
| `analyze_reasoning_gaps` | Where agents reasoned badly |
| `find_similar_failures` | Failures like the ones in the scope |
| `analyze_skill_usage` | How agents used the skills they were given |

`compare_treatments` compares mean costs only within one cost source, so it never mixes costs that the agent reported with costs that Oqoqo estimated.

**Examples**

Summarize one experiment:

```bash theme={null}
oqoqo results analyze summarize_scope --experiment-id exp_8f2c41d0 --output json
```

Print each treatment's pass rate:

```bash theme={null}
oqoqo results analyze compare_treatments --experiment-id exp_8f2c41d0 --output json \
  | jq '.data.result.treatments[] | {treatmentKey, passRate: (if .failureRate == null then null else 1 - .failureRate end)}'
```

Find recurring failures for a task since July:

```bash theme={null}
oqoqo results analyze find_failure_patterns --task-key checkout --completed-after 2026-07-01T00:00:00Z --output json
```

**Result fields**

With `--output json`, the analysis is in `data.result`. The baseline is the treatment that the experiment's plan names as `referenceTreatmentClientId`. If none is marked, `compare_treatments` uses the first treatment.

| Field | Mode | Meaning |
| - | - | - |
| `totals.runs`, `totals.passedRuns`, `totals.failedRuns` | `summarize_scope` | Runs in scope, and runs with a pass or a fail verdict |
| `totals.evalsFailedRuns`, `totals.infraBlockedRuns`, `totals.inconclusiveRuns`, `totals.pendingRuns` | `summarize_scope` | Runs with no verdict, by reason |
| `treatments[].treatmentKey`, `runCount`, `passedRuns`, `failedRuns` | `summarize_scope`, `compare_treatments` | The same counts for each treatment |
| `treatments[].failureRate` | `compare_treatments` | `failedRuns / (passedRuns + failedRuns)`, or `null` when no run has a verdict |
| `treatments[].isReferenceTreatment` | `compare_treatments` | `true` for the baseline |
| `treatments[].deltaFromReference.failureRate` | `compare_treatments` | The treatment's `failureRate` minus the baseline's |
| `referenceTreatmentKey` | `compare_treatments` | The `treatmentKey` of the baseline |
| `pendingRuns` | `summarize_scope`, `compare_treatments` | Runs with no verdict that Evals can still judge |
| `inconclusiveRuns` | `summarize_scope`, `compare_treatments` | Runs with no verdict that Evals won't judge. It leaves out `pendingRuns`. |
| `insightsCoverage` | `summarize_scope`, `search_frictions` | The runs split into `analyzedRuns`, `pendingRuns`, and `unanalyzedRuns` (Insights off, skipped, failed, or never run). An empty friction list is final when its `pendingRuns` is 0. |
| `status`, `evalsPending`, `insightsPending` | `get_run_evidence` | The run's status, and whether its Evals or Insights result is still to come |
| `page.truncated`, `page.reasons` | Every mode | Whether the response was cut, and why: `row_limit` or `byte_limit` |
| `page.rankedCount` | Every mode | How many items were ranked |
| `page.completeData` | Every mode | The complete read: `data.query` means [`oqoqo data query`](https://docs.oqoqo.ai/cli/data#oqoqo-data-query) with the named dataset, and `run.trajectory.read` means [`oqoqo runs trajectory`](#oqoqo-runs-trajectory) |

**Notes**

A pass rate is `passedRuns / (passedRuns + failedRuns)`, which is `1 - failureRate`. Runs that are blocked, inconclusive, or whose Evals failed have no verdict, so they stay out of both counts. Wait until `pendingRuns` is `0`, because the counts can still change until then.

`--limit` is an upper bound, and the response size limit can return fewer items. The rows that `page.completeData` names can be finer than the ranked items, so check the hint before you compare counts. For how results become final, see [What Evals read](https://docs.oqoqo.ai/evaluation/evals.md#what-evals-read) and [What Insights read](https://docs.oqoqo.ai/evaluation/insights.md#what-insights-read).

## Related

> [card] [oqoqo frictions](https://docs.oqoqo.ai/cli/frictions.md)
>
> List frictions with the same run scope flags.

> [card] [oqoqo evals and insights](https://docs.oqoqo.ai/cli/evals-and-insights.md)
>
> Start Evals and Insights and page their results.

> [card] [Read results](https://docs.oqoqo.ai/evaluation/results.md)
>
> Matrix, Runs, and Compare in the dashboard.

> [card] [CLI reference](https://docs.oqoqo.ai/cli/overview.md)
>
> Global flags, output, and exit codes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.