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

# Runs and results tools

> MCP tools for listing runs, inspecting run profiles, reading trajectories, transcripts, and outputs, and analyzing results.

Inspect individual runs, tool usage profiles, step trajectories, transcripts, and changed files, or aggregate results across runs. See [Read results](https://docs.oqoqo.ai/evaluation/results.md) and [Run details](https://docs.oqoqo.ai/evaluation/traces.md).

* **Badges** are explained under [Approvals](https://docs.oqoqo.ai/mcp-server/overview.md#approvals).
* **`project_id`** is optional on most tools; without it, the server picks a project for that call only ([Projects](https://docs.oqoqo.ai/mcp-server/overview.md#projects)).
* **`expected_organization_id`** is an optional string on every write tool, omitted from parameter tables; pass `organization.id` from [`get_identity`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#get_identity) ([Organization check](https://docs.oqoqo.ai/mcp-server/overview.md#organization-check)).
* **`limit`** values above a tool's maximum are capped, not refused.

## Tools

### list\_runs

**List run results.** Returns a page of runs with stable IDs, typed errors, and a plain explanation of each result in `criteriaSummary`.

Read-only · CLI: [`oqoqo runs list`](https://docs.oqoqo.ai/cli/runs#oqoqo-runs-list)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `experiment_id` | string | No | Only the runs of this `exp_` experiment. |
| `schedule_id` | string | No | Only the runs of the experiments this `sch_` schedule launched. |
| `task_id` | string | No | Only the runs of this `tsk_` task, every version. |
| `task_version_id` | string | No | Only the runs of this `tskver_` task version. |
| `treatment_id` | string | No | Only the runs of this `trt_` treatment. |
| `tool_id` | string | No | Only the runs whose treatment gave the agent this tool (`skl_`, `mcp_`, `cli_`, or `sdk_`), in any version. |
| `tool_version_id` | string | No | Only the runs whose treatment gave the agent this tool version (`sklver_`, `mcpver_`, `cliver_`, or `sdkver_`). |
| `file_id` | string | No | Only the runs whose task had this `fld_` file. |
| `machine_id` | string | No | Only the runs whose task ran on this `env_` machine. |
| `agent_id` | string | No | Only the runs of this agent, with any model: its key, such as `claude-code`. |
| `agent_model_id` | string | No | Only the runs of this `agm_` agent and model. |
| `friction_id` | string | No | Only the runs where this `frc_` friction happened. |
| `query` | string | No | Text to match, up to 200 characters. |
| `statuses` | array of strings | No | Only these run statuses (`queued`, `running`, `completed`, `errored`, `cancelled`). Up to 20. |
| `outcomes` | array of strings | No | Only these outcomes (`pass`, `fail`, `evals_failed`, `infra_blocked`, `inconclusive`, `evals-off`). Up to 20. |
| `task_key` | string | No | Only the runs of this task key. |
| `treatment` | string | No | Only the runs of this treatment. |
| `agent` | string | No | Only the runs of this agent. |
| `model_id` | string | No | Only the runs of this model. |
| `effort_level` | string | No | Only the runs at this effort level. |
| `provider` | string | No | The exact provider connection name, as in `providerDisplayName`. Runs with the same agent, model, and effort can differ only by provider. |
| `completed_after`, `completed_before` | string (date-time) | No | Only runs that completed in this range. |
| `limit` | integer | No | Results per page, up to 200 (default 50). |
| `cursor` | string | No | The `nextCursor` from the previous page. |

**Result fields**

Each run has its stable IDs, typed errors, and `criteriaSummary`. It can also have:

* `treatmentUse`: each tool's state and calls, as in `get_run_profile`. It's null when the run has no usable profile.
* `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. It has the `owner` step, `commandNumber` when the owner has several commands of that kind (null for a package install, where `manager` and `packageOwners` name the package manager and who declared the packages), the `command`, `exitCode` (null on a timeout, with `timeoutSeconds`), the last `output` lines, and `outputTruncated`. See [troubleshooting](https://docs.oqoqo.ai/reference/troubleshooting.md#a-run-could-not-start-because-a-setup-command-failed).

The scope fields, `experiment_id` to `friction_id`, name the records whose runs to read; a run must match them all. `list_frictions` and `get_friction` take the same ones, and `list_experiments` all but `experiment_id`. An unknown ID returns `scope_not_found`, not an empty list. `scope` in the result names each record with its dashboard page.

### get\_run\_profile

**Get a run profile.** Returns the same profile as the dashboard's **Run profile** rail: treatment use, tool calls, what stood out, tokens, cost, and time.

Read-only · CLI: [`oqoqo runs profile`](https://docs.oqoqo.ai/cli/runs#oqoqo-runs-profile)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `run_id` | string | Yes | The `run_` run. |

**Result fields**

| Field | Meaning |
| - | - |
| `use` | For each tool the run had: `used`, `not_used`, `not_measured` (never visible, as for an SDK), `inconclusive` (the log can't tell), or `not_applicable`, with calls by operation, measured time, and the first step and turn that used it. `calls` is null until use is decided. `treatment` answers for the whole treatment. |
| `signals` | What stood out, each list empty when nothing qualifies: a call repeated with the same input, input that grew by at least 10k tokens and 10% in one turn, a call of at least 5 s and 5% of working time, and a gap between turns of at least 10 s and 3× the median gap |
| `costSource` | `agent_reported`, `estimated`, or `unknown`. Counts and times are exact or null, never estimated. |
| `stopReason`, `reportedModelId`, `reportedModelName`, `agentError` | Custom agents only. `agentError` says why the run failed before the agent answered. |
| `setupFailure` | As in `list_runs` |

Step ordinals refer to `get_run_trajectory`, and the per-turn series is the `runTurns` dataset of `query_data`.

### get\_run\_trajectory

**Get a run trajectory.** Returns a page of a run's steps in order, each with its model turn and tool, plus the run's input, cached-input, and output token totals (or null).

Read-only · CLI: [`oqoqo runs trajectory`](https://docs.oqoqo.ai/cli/runs#oqoqo-runs-trajectory)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `run_id` | string | Yes | The `run_` run. |
| `after_ordinal` | integer | No | Start after this step ordinal (`-1` or higher). Send `nextAfterOrdinal` from the previous page, or `-1` / omit it to start at the first step. |
| `limit` | integer | No | Results per page, up to 500 (default 100). |
| `projection` | `compact`, `full` | No | `compact` (default): each step's kind, tool, and a short text preview of up to 512 bytes. `full`: every recorded field of each step. |

Continue with `nextAfterOrdinal` while `truncated` is true.

**Result fields**

`steps` (each with its ordinal, model turn, and tool; tool steps include their measured duration when the agent reported it), the run's token totals, `truncated`, `nextAfterOrdinal`, and `coverage`, which gives the returned range, the total steps, and whether this page holds the whole trajectory. For a custom agent, the run also has the same `stopReason`, reported model, and `agentError` as `get_run_profile`.

### get\_run\_transcript

**Get a run's raw transcript.** Returns a page of the original transcript: UTF-8 text in `contentText`, other bytes as base64 in `contentBase64`. `sha256` covers the whole transcript.

Read-only · CLI: [`oqoqo runs transcript`](https://docs.oqoqo.ai/cli/runs#oqoqo-runs-transcript)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `run_id` | string | Yes | The `run_` run. |
| `trial_id` | string | No | One trial, when the combination has more than one. |
| `offset` | integer | No | Continue from the returned next offset until `eof` is true (default 0). |
| `limit_bytes` | integer | No | Bytes per page, up to 12,288 (default 12,288). |

### get\_run\_output

**Get a run's output and files.** Returns a page of the final message, the unified diff, the file manifest, one kept file, or the output archive.

Read-only · CLI: [`oqoqo runs output`](https://docs.oqoqo.ai/cli/runs#oqoqo-runs-output)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `run_id` | string | Yes | The `run_` run. |
| `trial_id` | string | No | One trial, when the combination has more than one. |
| `part` | `final_message`, `diff`, `manifest`, `archive`, `file` | No | What to read. Default `manifest`; read it first. |
| `path` | string | No | With `diff`: one file's section of the patch. With `file`: that file's bytes. |
| `offset` | integer | No | Continue from the returned next offset until `eof` is true (default 0). |
| `limit_bytes` | integer | No | Bytes per page, up to 12,288 (default 12,288). |

Text pages are UTF-8 in `contentText`, and other pages are base64 in `contentBase64`. `sourceTruncated` marks a preview that was capped.

### analyze\_results

**Analyze experiment results.** Runs one ranked analysis over experiment and run results.

Read-only · CLI: [`oqoqo results analyze`](https://docs.oqoqo.ai/cli/runs#oqoqo-results-analyze)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `mode` | see below | Yes | The analysis to run. |
| `query` | string | No | Text to search for, in the search modes. |
| `scope` | object | No | The runs to analyze. See the fields of `scope` below. |
| `limit` | integer | No | Most ranked items, up to 100 (default 12 to 100 by 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). |

`scope` takes these fields. A run counts only when it matches every field you send.

| Field | Takes | CLI flag |
| - | - | - |
| `experimentId` | `exp_` ID | `--experiment-id` |
| `runId` | `run_` ID | `--run-id` |
| `trialId` | A trial's `run_` ID | `--trial-id` |
| `runs` | Up to 3 `run_` IDs to analyze together, or `run~trial` items | `--runs` |
| `taskId` | `tsk_` ID | `--task-id` |
| `taskVersionId` | `tskver_` ID | `--task-version-id` |
| `taskKey` | Task key | `--task-key` |
| `skillId` | `skl_` ID | `--skill-id` |
| `skillKey` | Skill key | `--skill-key` |
| `treatmentId` | `trt_` ID | `--treatment-id` |
| `treatment` | Treatment key or label | `--treatment` |
| `toolId` | `skl_`, `mcp_`, `cli_`, or `sdk_` ID | `--tool-id` |
| `toolVersionId` | `sklver_`, `mcpver_`, `cliver_`, or `sdkver_` ID | `--tool-version-id` |
| `fileId` | `fld_` ID | `--file-id` |
| `machineId` | `env_` ID | `--machine-id` |
| `agentId` | Agent key, such as `claude-code` | `--agent-id` |
| `agentModelId` | `agm_` ID | `--agent-model-id` |
| `agent` | Agent name or key | `--agent` |
| `modelId` | Model ID | `--model-id` |
| `effortLevel` | Effort level | `--effort-level` |
| `provider` | Exact provider connection name | `--provider` |
| `frictionId` | `frc_` ID | `--friction-id` |
| `scheduleId` | `sch_` ID | `--schedule-id` |
| `outcome` | `pass`, `fail`, `evals_failed`, `infra_blocked`, or `inconclusive` (any other finished result) | `--outcome` |
| `completedAfter` | ISO 8601 date-time | `--completed-after` |
| `completedBefore` | ISO 8601 date-time | `--completed-before` |

| `mode` | What it returns |
| - | - |
| `summarize_scope` | Runs, passes, and failures for the scope, per treatment and per agent: `totals` and `treatments[]` |
| `find_failure_patterns` | Failure patterns across runs |
| `search_experiment_evidence` | Runs whose recorded work matches `query` |
| `search_frictions` | Frictions that match `query` |
| `get_run_evidence` | One run's evidence (requires `scope.runId` or `scope.trialId`), with its `status`, `evalsPending`, and `insightsPending` |
| `compare_treatments` | Each treatment's use rate, mean tokens, working time, tool calls, `passedRuns`, `failedRuns`, `failureRate`, and `deltaFromReference` against the baseline. `means.cost` gives mean cost per cost source, and a cost delta compares only the same source. |
| `rank_tasks_by_friction` | Tasks ranked by friction |
| `analyze_reasoning_gaps` | Where agents reasoned wrongly |
| `find_similar_failures` | Failures similar to one run's |
| `analyze_skill_usage` | How agents used skills |

Ranked analysis is never paged: `limit` is an upper bound, and the response size limit can return fewer items.

**Result fields**

When `page.truncated` is true, these fields say why and where to read the rest:

| Field | Meaning |
| - | - |
| `page.reasons` | `row_limit` or `byte_limit` |
| `page.rankedCount` | How many items were ranked |
| `page.completeData` | The complete read: a `query_data` dataset, or `get_run_trajectory`. Its rows can be finer-grained than the ranked items, so read its hint before you compare counts. |

The analysis is in `result`:

* `summarize_scope`: `result.totals` (`runs`, `passedRuns`, `failedRuns`, `evalsFailedRuns`, `infraBlockedRuns`, `inconclusiveRuns`, `pendingRuns`) and `result.treatments[]` (`treatmentKey`, `runCount`, `passedRuns`, `failedRuns`).
* `compare_treatments`: `result.treatments[]` with the same counts plus `failureRate`, `isReferenceTreatment`, and `deltaFromReference.failureRate`, and `result.referenceTreatmentKey`.

The pass rate is `passedRuns / (passedRuns + failedRuns)`, or `1 - failureRate`. `pendingRuns` counts runs with no verdict that Evals can still judge. They stay out of the pass and fail counts and out of `inconclusiveRuns`, so wait until `pendingRuns` is 0. `summarize_scope` and `search_frictions` return `insightsCoverage`: `analyzedRuns`, `pendingRuns`, and `unanalyzedRuns` (Insights off, skipped, failed, or never run). An empty friction list is final when `pendingRuns` is 0.

## Related

> [card] [Evals and Insights tools](https://docs.oqoqo.ai/mcp-server/evals-and-insights.md)
>
> Compare treatments and read Evals and Insights.

> [card] [Frictions tools](https://docs.oqoqo.ai/mcp-server/frictions.md)
>
> Rank and inspect frictions across runs.

> [card] [oqoqo runs and results](https://docs.oqoqo.ai/cli/runs.md)
>
> The matching CLI commands and run scope flags.


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