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

# Evals and Insights tools

> MCP tools for previewing, triggering, listing, and reading Evals, Insights, comparisons, and experiment Briefs.

Score runs against updated rubrics with [Evals](https://docs.oqoqo.ai/evaluation/evals.md), compare treatments with [Comparisons](https://docs.oqoqo.ai/evaluation/comparisons.md) and the Brief, and discover frictions with [Insights](https://docs.oqoqo.ai/evaluation/insights.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

### preview\_evals

**Preview Evals for an experiment.** Shows which runs Evals can score, rubrics that need attention or changed, model readiness, and the modes available.

Read-only · CLI: [`oqoqo evals preview`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-evals-preview)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `experiment_id` | string | Yes | The `exp_` experiment. |

**Result fields**

`ready`, `modelsReady`, `userProviderReady`, `setupUrl`, `eligibleRunCount`, `runsWithoutRubricsCount`, `runsWithInvalidRubricsCount`, `runsNotJudgeableCount`, `rubricChanges`, `failedRunIds`, and `mode`: `experimentMode` (the mode the experiment launched with), `latestMode`, `agentAvailable`, and, only while your organization can use Agent mode, `estimate` (`runs` and `model`). Their meanings are under [`oqoqo evals preview`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-evals-preview).

### trigger\_evals

**Start Evals for an experiment.** Starts an Evals attempt, or reruns Evals on the same recorded work after a rubric change.

Changes data · You approve each call · CLI: [`oqoqo evals trigger`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-evals-trigger)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `experiment_id` | string | Yes | The `exp_` experiment. |
| `trigger_attempt_id` | string | Yes | An ID you choose, so that a retry doesn't repeat the change. It has 1 to 100 characters. A retry returns the same `eval_` attempt with `replayed: true`. |
| `mode` | `standard`, `agent` | No | How this attempt scores runs. Default: the experiment's launch mode. |
| `project_ai_selections` | array of objects | No | One Evals model override: `role: "judge"`, `provider_connection_id` (`aic_`), `provider_model_id` (`aim_`), and optional `effort_level`. Default: the organization's **Evals model**. |
| `project_ai_instruction_overrides` | array of objects | No | One override: `role: "judge"` and `custom_instructions`. Default: the organization's setting. |
| `run_ids` | array of strings | No | Only these `run_` runs, such as failed cells. Default: every eligible run. |

**Standard** scores each run in one pass with your Evals model and condenses very long runs to fit its context window. It's the fastest and lowest-cost mode. **Agent** has Oqoqo's evals agent read the full run and the changed files and check the agent's claims before it scores. It makes many calls to your Evals model, so it costs more and takes a few minutes per run. Both modes score against the same rubric ([how the modes differ](https://docs.oqoqo.ai/cli/evals-and-insights.md#oqoqo-evals-trigger)).

A request for Agent mode, stated or inherited, is refused with `agent_mode_unavailable` when your organization can't use it: "Agent mode isn't available for your organization. Use Standard mode instead." Without `mode`, the refusal has `details.inheritedMode` set to `agent` and says "This experiment launched Evals in Agent mode, which your organization can't use now. Rerun with mode: "standard"." When the Evals model can't run Agent mode, the refusal is `agent_mode_model_unsupported`, with a `setupUrl` to **Oqoqo AI defaults**. [Agent mode](https://docs.oqoqo.ai/evaluation/agent-mode.md) is in private beta.

**Result fields**

`evalsId` (the new `eval_` attempt), `status`, `mode` (the mode the attempt uses), `pollAfterMs` (60 seconds in Agent mode, 10 seconds in Standard mode, or `null` when the attempt has already finished), and `replayed` (`true` when a repeated `trigger_attempt_id` returned the earlier attempt).

### list\_evals

**List Evals history.** Returns the experiment's Evals attempts, newest first, without reports, each with its `models` and `mode`. A failed attempt has `error` (`code` and `message`). An Agent mode attempt also has `agentUsage` once its agent has reviewed runs: the `inputTokens`, `cacheReadTokens`, and `outputTokens` that the evals agent has used so far.

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

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `experiment_id` | string | Yes | The `exp_` experiment. |
| `limit` | integer | No | Results per page, up to 100 (default 25). |
| `cursor` | string | No | The `nextCursor` from the previous page. |

### get\_evals\_results

**Get Evals results.** Returns a summary for each run of an attempt, or the exact rubric and verdict JSON for one trial.

Read-only · CLI: [`oqoqo evals get`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-evals-get)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `experiment_id` | string | Yes | The `exp_` experiment. |
| `evals_id` | string | No | The `eval_` attempt. Omit it to read the latest attempt. |
| `view` | `summary`, `trial_evidence` | No | Every run's summary, or one trial's exact JSON. Default `summary`. |
| `trial_id` | string | Required with `trial_evidence` | With `trial_evidence`: the `run_` trial. Omit it with `summary`. |
| `cursor` | string | No | With `summary` only: the `nextCursor` from the previous page. |
| `limit` | integer | No | With `summary`: results per page, up to 200 (default 50). |
| `offset` | integer | No | With `trial_evidence` only (`offset > 0` isn't allowed with `summary`): continue from the returned next offset until `eof` is true (default 0). |
| `limit_bytes` | integer | No | With `trial_evidence`: bytes per page, up to 12,288 (default 12,288). |
| `wait_ms` | integer | No | Wait in the call for a change, up to 25,000 ms. |

**Result fields**

| Field | Meaning |
| - | - |
| `attempt` | The attempt this read covers, with its `evalsId`, `models`, `mode`, `error`, and, in Agent mode, `agentUsage`. `models` is empty for an attempt from before Oqoqo recorded models. |
| `status` | Each row's [status](https://docs.oqoqo.ai/cli/evals-and-insights.md#statuses): `queued` or `running` until its result is written, then `completed`, `skipped`, or `failed`, which are final |
| `error` | For a failed row, `code` and `message`. The message starts with "Evals could not evaluate this run, so it has no Pass or Fail." and gives the cause and the next step. |
| `outcomeExplanation` | Whether the run passed, the rule used, and how each criterion affected the result. Percentage rules also explain the overall percentage. |
| `evidenceCoverage` | What was read of the run. `null` for older runs. |
| `hasMore`, `nextCursor` | Paging for the `summary` view. A cursor stays on its attempt, even after a newer attempt starts. |

### get\_evals\_comparisons

**Compare treatments and agents.** Compares an experiment's treatments and agents task by task, from the Matrix's Evals verdicts. It returns the sentence that answers the experiment's question and a block for each difference first, as at the top of [Comparisons](https://docs.oqoqo.ai/evaluation/comparisons.md#answers), then every comparison with its result.

Read-only · CLI: [`oqoqo evals compare`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-evals-compare)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `experiment_id` | string | Yes | The `exp_` experiment. |
| `evals_id` | string | No | The `eval_` attempt. Omit it to read the latest attempt. |
| `kind` | `treatment`, `agent`, `interaction` | No | Only comparisons of this kind. |
| `label` | `clear`, `likely`, `unclear` | No | Only comparisons with this label. |
| `limit` | integer | No | Results per page, up to 200 (default 200). |
| `cursor` | string | No | The `nextCursor` from the previous page. Send it with the same `kind` and `label`. |

`kind` is `treatment` (a treatment against the baseline, for all agents together and for each agent, or each pair of treatments without a baseline), `agent` (two agents with the same treatment), or `interaction` (**Does a treatment help one agent more?**). `label` is `clear` (**Clear difference**), `likely` (**Likely difference**), or `unclear` (**No clear difference**). `unclear` means that the runs can't tell the two sides apart, not that the sides are the same.

The most decisive comparisons come first, the main comparisons before the breakdowns within a label. `kind` and `label` only filter the list: labels don't change, and `summary`, `differences`, `restLine`, and `comparisonCount` stay the same. A read returns up to 200 comparisons that fit in the response. A cursor fails with `invalid_cursor` once the comparisons change. More than 10,000 Matrix cells fails with `experiment_too_large`.

**Result fields**

| Field | Meaning |
| - | - |
| `state`, `message` | `ready`, or the first reason that applies (`nothing_to_compare`, `too_many_agents`, `evals_off`, or `no_verdicts`), and its words |
| `summary` | The sentence that answers the experiment's question over its main comparisons: `text`, and `parts`, where each treatment or agent it names carries its `treatmentKey` or `agentKey`. `null` when the experiment has no main comparison. |
| `differences` | One block for each clear or likely difference, in the order to say them, up to 5: the main comparisons first, then any other comparison with a clear difference. A comparison with no clear difference is never in it. Each has `comparisonId`, `label` (`clear` or `likely`), `name` (the two sides, and what the comparison holds fixed when it isn't a main comparison), `sides` (each with `key`, `label`, `passes`, `runs`, and `percent`), `taskLine` ("Better on 14 tasks, worse on 2, same on 26."), `verdict`, `nextStep`, `byAgent`, and `headline`. |
| `restLine` | One sentence on what `summary` and `differences` leave out, or `null` |
| `notes` | One sentence each on what limits the comparisons |
| `evals`, `running` | The Evals attempt and its `status`, and whether the experiment still has runs to finish |
| `comparisonCount`, `comparisons` | Every comparison's count, and the listed comparisons |
| `treatments`, `agents` | The experiment's treatments, and the agents the listed comparisons name |
| `taskCount`, `runsEach`, `scoredRuns`, `unscoredRuns` | Tasks, trials of each combination, and runs with and without a verdict |
| `noiseFloor`, `ceilingTaskCount`, `floorTaskCount` | Repeated runs that disagreed (`cases`, `disagreeing`), and tasks that passed or failed in every run |
| `agentPairsOmitted` | `true` with more than 6 agents. Then no `agent` or `interaction` comparisons are made. |
| `hasMore`, `nextCursor` | Paging, with the same `kind` and `label` |

Each comparison has `comparisonId` (`cmp_`), `kind`, `label`, `family` (`primary` for a main comparison, or `breakdown`), `title`, `scope`, `headline`, `sides`, `verdict`, `nextStep`, `sentence`, `groupLabel`, `taskSplit`, `treatmentKey`, `referenceTreatmentKey`, `agentKey`, `referenceAgentKey`, `arm` and `reference` (or `first` and `second` for an `interaction`), `tasks` (`higher`, `lower`, `same`), `pValue` (an exact two-sided sign test), `adjustedPValue` (the Holm correction within its `family`), `runsLeftOut`, `confirmation`, and `confirmationUnavailable` (`earlier_evals`, `in_progress`, or `cannot_settle`). `confirmation` holds the runs that check a likely difference again. `cannot_settle` means that running these tasks again can't settle it, and the experiment needs more tasks. To plan them, pass its `comparisonId` to [`get_experiment_plan`](https://docs.oqoqo.ai/mcp-server/experiments#get_experiment_plan) as `comparison_id`, with a new `launch_attempt_id`.

Say the result in the words of `summary` and each `verdict`, which every surface shows, with `verdict` and `nextStep` on one line. `nextStep` is `run_again` (with `text` and `runs`) or `more_tasks` (with `text`), or `null`. Each field is explained under [`oqoqo evals compare`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-evals-compare).

### get\_experiment\_brief

**Get an experiment's Brief.** Reads an experiment's [Brief](https://docs.oqoqo.ai/evaluation/comparisons.md#brief): its clear and likely differences, worded as in [`get_evals_comparisons`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#get_evals_comparisons), with one written sentence and the frictions seen with the side that did worse. Oqoqo counts every number from the experiment's Evals verdicts and frictions. A model writes only each `sentence` and, in Agent mode, each pair's `line`.

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

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `experiment_id` | string | Yes | The `exp_` experiment. |

`state` says how complete the Brief is. `ready`, `failed`, `not_written`, and `no_insights` are final for the Brief. While `state` is `writing`, the differences and counts are already in the read: call again after `waitMs` milliseconds until `state` changes. In Agent mode, also call again after `waitMs` while any finding's `pendingTaskCount` is above 0. The tool takes no `wait_ms`.

| `state` | Meaning |
| - | - |
| `ready` | The differences, each with its `sentence` |
| `writing` | The differences, while the Brief is being written |
| `failed` | The differences, and the Brief could not be written. `error.code` is `brief_model_unavailable`, `brief_model_refused`, or `brief_write_failed`, and `error.message` says why. |
| `not_written` | The differences, with no Brief for them. One is written the next time the experiment's Evals or Insights finish. |
| `no_insights` | Insights hasn't reviewed the experiment's runs. Run it with [`trigger_insights`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#trigger_insights). |
| `not_available` | The experiment, its Evals, or its Insights is still running. |

**Result fields**

| Field | Meaning |
| - | - |
| `state`, `message`, `error` | How complete the Brief is, and its words |
| `waitMs` | Only while `state` is `writing`, or while the insights agent is still reading some pairs of runs: call again after this many milliseconds. |
| `hasMore` | `true` when the read left out some pairs of runs in `explanations` to fit its size limit. There is no cursor for them. |
| `briefId` | The `brf_` ID, set only when `state` is `ready` or `failed` |
| `summary` | The sentence that opens **Comparisons**, as [`get_evals_comparisons`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#get_evals_comparisons) returns it. "Nothing to compare in this experiment." or "This experiment is too large to compare." when there's nothing to compare. `null` when `state` is `no_insights` or `not_available`. |
| `findings` | Up to 5 differences, as below |
| `comparisonsLeftOut`, `restLine` | Clear or likely comparisons that are not findings, and the sentence on what the differences leave out. [`list_frictions`](https://docs.oqoqo.ai/mcp-server/frictions#list_frictions) lists every friction of the experiment. |
| `notes` | What limits the comparisons, as in `get_evals_comparisons` |
| `evalsId`, `insightsId`, `dashboardUrl` | The attempts the findings were read from, and **Comparisons** on the experiment's **Matrix** |

Each finding has the fields of its block in `differences` (`comparisonId`, `label`, `name`, `sides`, `taskLine`, `verdict`, `nextStep`, `byAgent`, `headline`), and `kind`, `title`, `scope`, `arm` and `reference`, `tasks`, `pValue`, `adjustedPValue`, `worseSide`, `worseTaskCount`, `notReviewed`, `sentence`, `confirmation`, `confirmationUnavailable`, `frictions`, and `afterFix`. Each friction has `frictionId` (`frc_`), `title`, `summary` (what goes wrong, in one line), `fixIn`, `tasks`, `dashboardUrl`, `failedRuns` (how many of the worse side's failed runs had it, out of `runs`), `passedRuns` (the same for the other side's passed runs), and, for `arm` and `reference`, `runsWithFriction` out of `runsReviewed`, which is how the friction was picked. The counts use only the `worseTaskCount` tasks and the runs that Insights reviewed. `afterFix` is set for a clear difference with a friction to fix in the product: its `text`, `taskCount`, and `runs`.

When the experiment's latest Insights ran in [Agent mode](https://docs.oqoqo.ai/evaluation/agent-mode.md), each finding also has these fields:

| Field | Meaning |
| - | - |
| `explainedTaskCount` | How many tasks have a pair of runs to read side by side: a failed run of `worseSide` and a passed run of the other side |
| `explanations` | Every pair. Once `exampleTaskVersionId` is set, the example comes first, then the tasks in `differentTaskVersionIds`, then the rest. Before that, the largest pass-rate gap comes first. |
| `pendingTaskCount` | How many pairs the insights agent is still reading. The Brief is ready before they are, so call again after `waitMs`. |
| `exampleTaskVersionId` | Once every pair is read and `sentence` says what the runs did across the tasks: the `tskver_` task whose pair shows it |
| `differentTaskVersionIds` | With `exampleTaskVersionId`: the tasks that went differently, which `sentence` names, in order |
| `similarTaskCount` | With `exampleTaskVersionId`: how many other tasks with lines went like the example |

Each pair has `taskVersionId` (`tskver_`), `taskName`, `dashboardUrl`, and `state`: `pending` while the agent reads it, `completed` when its lines are written, or `failed` when the agent gave no answer that passed Oqoqo's checks, which shows only the two runs. Its `worse` and `better` runs each have these fields:

| Field | Meaning |
| - | - |
| `runId`, `trialId` | The run, and the trial of it that was read |
| `sideRuns`, `sideMatched` | The side's compared runs on the task, and how many of them failed or passed |
| `sideCountLine` | "Raw Agent failed 2 of 3 runs" when the side's runs disagree, or `null` |
| `explained` | `stepIndex`, `line`, and `quote` (up to 5 lines of that step, as the run's trace shows them), or `null` unless the pair is `completed` |
| `dashboardUrl` | The run's trace, at that step when there is one |

Show the pairs in that order, as the dashboard does: the example with "Like N other tasks" (from `similarTaskCount`), each task that went differently with "Went differently", then the rest. A pair says where two runs went different ways, not why the difference happened. What the agent used to read the pairs counts in the Insights attempt's `agentUsage` ([`list_insights`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#list_insights)).

When you report a friction, give both sides' counts ("Raw Agent 24 of 28 failed runs · Stripe CLI 0 of 26 passed runs") and say it was seen with the side that did worse. Don't call it the cause. To run a likely difference again, pass its `comparisonId` to [`get_experiment_plan`](https://docs.oqoqo.ai/mcp-server/experiments#get_experiment_plan) as `comparison_id`. To run a clear difference again after a fix, add `after_fix` set to `true`. Each field is explained under [`oqoqo experiments brief`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-brief).

### preview\_insights

**Preview Insights for an experiment.** Shows whether the Insights models and your provider access are ready, with a dashboard link for any secure setup, and the modes this experiment can use.

Read-only · CLI: [`oqoqo insights preview`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-insights-preview)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `experiment_id` | string | Yes | The `exp_` experiment. |

**Result fields**

`ready`, `modelsReady`, `userProviderReady`, `setupUrl`, `failedRunIds`, and `mode`: `experimentMode` (the mode the experiment launched with), `latestMode`, `agentAvailable`, and, only while your organization can use Agent mode, `estimate` (`runs`, `model`, and `experimentModel` when the Experiment insights model is a different model). Their meanings are under [`oqoqo insights preview`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-insights-preview).

### trigger\_insights

**Start Insights for an experiment.** Starts an Insights attempt, or reruns Insights on the same recorded work.

Changes data · You approve each call · CLI: [`oqoqo insights trigger`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-insights-trigger)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `experiment_id` | string | Yes | The `exp_` experiment. |
| `trigger_attempt_id` | string | Yes | An ID you choose, so that a retry doesn't repeat the change. It has 1 to 100 characters. A retry returns the same `insights_` attempt with `replayed: true`. |
| `mode` | `standard`, `agent` | No | How this attempt reviews runs. Default: the experiment's launch mode. |
| `project_ai_selections` | array of objects | No | Up to two model overrides: `role` (`sweep` Insights, `consolidation` Experiment insights), `provider_connection_id` (`aic_`), `provider_model_id` (`aim_`), and optional `effort_level`. A role you omit uses the organization's model. |
| `project_ai_instruction_overrides` | array of objects | No | Up to two overrides, each with `role` and `custom_instructions`. A role you omit uses the organization's setting. |
| `run_ids` | array of strings | No | Only these `run_` runs. Default: every eligible run. |

**Standard** reviews each run in one pass with your Insights model. It's the fastest and lowest-cost mode. **Agent** has Oqoqo's insights agent read the whole run and check each friction against what the tools returned. It costs more and takes a few minutes per run. It also does the experiment's grouping of frictions, which Standard mode does in one pass. For each task of each difference in the Brief, it says what a failed run and a passed run did differently ([`get_experiment_brief`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#get_experiment_brief)). Both modes report frictions in the same way. Without `mode`, the attempt uses the experiment's launch mode, not the latest attempt's mode as the dashboard does.

A request for Agent mode, stated or inherited, is refused with `agent_mode_unavailable` when your organization can't use it: "Agent mode isn't available for your organization. Use Standard mode instead." Without `mode`, the refusal has `details.inheritedMode` set to `agent` and says "This experiment launched Insights in Agent mode, which your organization can't use now. Rerun with mode: "standard"." When the Insights model or the Experiment insights model can't run Agent mode, the refusal is `agent_mode_model_unsupported`, with a `setupUrl` to **Oqoqo AI defaults**. [Agent mode](https://docs.oqoqo.ai/evaluation/agent-mode.md) is in private beta.

**Result fields**

`insightsId` (the new `insights_` attempt), `status`, `mode` (the mode the attempt uses), `pollAfterMs` (60 seconds in Agent mode, 10 seconds in Standard mode, or `null` when the attempt has already finished), and `replayed` (`true` when a repeated `trigger_attempt_id` returned the earlier attempt).

### list\_insights

**List Insights history.** Returns the experiment's Insights attempts, newest first, without reports, each with its `models` and `mode`. A failed attempt has `error` (`code` and `message`); when the insights agent couldn't group the frictions, `error.message` starts with "Insights could not group this experiment's frictions." An Agent mode attempt also has `agentUsage` once its agent has reviewed runs: the `inputTokens`, `cacheReadTokens`, and `outputTokens` that the insights agent has used so far, including grouping the frictions and the pairs of runs in the Brief.

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

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `experiment_id` | string | Yes | The `exp_` experiment. |
| `limit` | integer | No | Results per page, up to 100 (default 25). |
| `cursor` | string | No | The `nextCursor` from the previous page. |

### get\_insights\_results

**Get Insights results.** Returns a summary for each run of an attempt, the attempt's public report, or the exact Insights JSON for one trial.

Read-only · CLI: [`oqoqo insights get`](https://docs.oqoqo.ai/cli/evals-and-insights#oqoqo-insights-get)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `experiment_id` | string | Yes | The `exp_` experiment. |
| `insights_id` | string | No | The `insights_` attempt. Omit it to read the latest attempt. |
| `view` | `summary`, `attempt_report`, `trial_evidence` | No | Every run's summary, the attempt's report, or one trial's exact JSON. Default `summary`. |
| `trial_id` | string | Required with `trial_evidence` | With `trial_evidence`: the `run_` trial. |
| `cursor` | string | No | With `summary` only: the `nextCursor` from the previous page. |
| `limit` | integer | No | With `summary`: results per page, up to 200 (default 50). |
| `offset` | integer | No | With `attempt_report` or `trial_evidence` only (`offset > 0` isn't allowed with `summary`): continue from the returned next offset until `eof` is true (default 0). |
| `limit_bytes` | integer | No | With an exact view: bytes per page, up to 12,288 (default 12,288). |
| `wait_ms` | integer | No | Wait in the call for a change, up to 25,000 ms. |

**Result fields**

`attempt` (with its `insightsId`, `models`, `mode`, `error`, and, in Agent mode, `agentUsage`), and for each row its `status`, its `error` (a failed row's message starts with "Insights could not analyze this run." and gives the cause), which follows the same rules as in `get_evals_results`, and `evidenceCoverage` (`null` for older runs). `hasMore` and `nextCursor` page the `summary` view.

## Related

> [card] [Frictions tools](https://docs.oqoqo.ai/mcp-server/frictions.md)
>
> Inspect the frictions Insights found.

> [card] [oqoqo evals and insights](https://docs.oqoqo.ai/cli/evals-and-insights.md)
>
> The matching CLI commands and output formats.


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