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

# Experiments tools

> MCP tools for preflighting plans, launching, renaming, monitoring, rerunning, cancelling, and publishing experiments.

Validate launch plans, launch and monitor experiments, rename them, cancel running work, and manage [public experiment links](https://docs.oqoqo.ai/evaluation/share.md). See [Launch an experiment](https://docs.oqoqo.ai/experiments/launch.md) for product rules.

* **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

### preflight\_experiment

**Check an experiment plan before launch.** Checks the exact plan, its tools' and machines' setup, your provider access, the revisions, and your run balance, without reserving runs.

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

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `plan` | object | Yes | The launch plan, as in [`launch_experiment`](https://docs.oqoqo.ai/mcp-server/experiments#launch_experiment). |

The call succeeds even when the launch is blocked, so check `ready`. A plan with `evalsMode` or `insightsMode` set to `agent` gets the blocker `agent_mode_unavailable` when your organization can't use that [Agent mode](https://docs.oqoqo.ai/evaluation/agent-mode.md), or `agent_mode_model_unsupported`, with a `setupUrl` to **Oqoqo AI defaults**, when a model can't run it.

**Result fields**

These are the same fields as in [`oqoqo experiments preflight`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-preflight).

| Field | Meaning |
| - | - |
| `ready`, `runCount` | Whether the plan can launch, and the runs it uses |
| `issues` | Required variables, headers, and OAuth connections without a value, each with the `setupUrl` where a person enters it. Variables without `required: true` aren't checked. |
| `blockers` | Everything else that stops the launch, such as `variable_name_clash` for a [name that two places set to different values](https://docs.oqoqo.ai/experiments/machines-and-files.md#when-two-places-set-the-same-variable) |
| `notices` | Facts that don't block it, such as a custom agent that isn't tested or needs attention, with its page |
| `quota` | `requiredRuns`, `availableRuns`, and `covered` |
| `agentModeEstimates` | Only for a feature that the plan runs in Agent mode while your organization can use it: one entry per feature, with `feature` (`evals` or `insights`) and `estimate` (the `runs` its agent would review, the `model` it uses, and for Insights `experimentModel` when the Experiment insights model is a different model) |
| `plan` | Your plan with the current configuration revisions filled in |

### launch\_experiment

**Launch an experiment.** Launches an exact plan that names catalog versions by ID, and returns a `launchId` (`adm_…`) for `get_launch_status`.

Changes data · You approve each call · CLI: [`oqoqo experiments launch`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-launch)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `plan` | object | Yes | The launch plan, as below. `get_experiment_plan` builds one from an earlier experiment. |

Fields of `plan`:

| Field | Required | Description |
| - | - | - |
| `selectedTaskDefinitionIds` | Yes | 1 to 100 `tskver_` IDs: each task's `versionId` from `inspect_catalog`, not its `tsk_` ID. |
| `treatments` | Yes | 1 to 100 treatments. Each has `clientId`, `name`, and `treatmentDefinitionId`, plus optional `preset`, `skillVersionIds`, `mcpServerVersionIds`, `cliVersionIds`, `sdkVersionIds`, `treatmentKey`, `sourceTreatment`, and `contentHash`. |
| `referenceTreatmentClientId` | Yes | The `clientId` of the baseline treatment, usually **Raw Agent**, that `compare_treatments` reads the others against. |
| `agentSelections` | Yes | 1 to 100 agents, each with `projectAgentModelBindingId` (an `agm_` ID from `inspect_catalog` with `kinds: ["agent"]` and `projection: "full"`) and optional `effortLevel`. A custom agent's model is named the same way. |
| `projectConfigurationRevision`, `organizationConfigurationRevision` | Yes | From an agent item in `inspect_catalog` with `projection: "full"`, or `preflight_experiment`. A stale value returns `configuration_changed`. |
| `trialCount` | Yes | Trials of each combination, 1 to 20. Each trial is one run from your balance. Total runs (`tasks × treatments × agents × trials`) must not exceed **100,000**. |
| `launchAttemptId` | Yes | An ID you choose, so that a retry doesn't repeat the change. An exact retry returns the first launch. |
| `evals`, `insights` | No | Turn Evals and Insights on or off. Both default to `true`. |
| `evalsMode` | No | `standard` (default) or `agent`, which needs `evals: true`. [Agent mode](https://docs.oqoqo.ai/evaluation/agent-mode.md) is in private beta; an organization without it fails before runs are reserved. |
| `insightsMode` | No | `standard` (default) or `agent`, which needs `insights: true`. [Agent mode](https://docs.oqoqo.ai/evaluation/agent-mode.md) is in private beta; an organization without it fails before runs are reserved. |
| `projectAiSelections` | No | Up to 3 model overrides for this experiment: `role` (`judge` Evals, `sweep` Insights, `consolidation` Experiment insights), `providerConnectionId`, `providerModelId`, and optional `effortLevel`. `judge` needs `evals: true`; the others need `insights: true`. |
| `projectAiInstructionOverrides` | No | Up to 3 custom instructions for this experiment, each with `role` and `customInstructions`. |
| `maxParallelAgentSessions` | No | **Max Concurrency**: agent sessions active at once, `1` to `100,000` (`1` runs them one at a time). Oqoqo can apply a lower limit. Doesn't affect Evals or Insights. |
| `label`, `description` | No | The experiment name (1 to 120 characters) and description. |
| `templateKey`, `rerunSourceExperimentPublicId`, `entrySource`, `mode`, `reasoningHook` | No | Filled in by `get_experiment_plan`; keep them as they are. `entrySource` defaults to `agent`. |

**Result fields**

| Field | Meaning |
| - | - |
| `launchId` | The `adm_` ID to poll with `get_launch_status` |
| `experimentId` | The `exp_` ID, or `null` until the launch is admitted |
| `status` | `accepted` |
| `runCount` | The runs the launch uses |
| `dashboardUrl` | The launch's page in the dashboard |

A refused launch returns one of these codes:

| Code | Fix |
| - | - |
| `quota_exceeded`, `no_entitlement`, `grant_expired` | The run balance doesn't cover it. A person fixes that on **Organization settings → Usage & billing**. |
| `configuration_changed`, `version_selection_changed` | Something changed since you read the plan. Run `preflight_experiment` again and launch its `plan` with a new `launchAttemptId`. |
| `launch_attempt_spent` | The ID belongs to an earlier launch that failed or expired. Use a new one. |
| `launch_attempt_conflict` | The same ID came with a different plan. |
| `agent_mode_unavailable` | Your organization cannot use Agent mode; use `standard` or email support. |
| `agent_mode_model_unsupported` | An assigned Evals or Insights model cannot run Agent mode; use `setupUrl` or `standard`. |

### get\_launch\_status

**Get launch status.** Returns a launch's progress by the `launchId` from `launch_experiment`, `rerun_experiment`, or `test_custom_agent`, before it has an `exp_` ID, with the same phase, `terminal`, and counts as `get_experiment_status`.

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

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `launch_id` | string | Yes | The `adm_` launch ID. |
| `wait_ms` | integer | No | Wait up to this many ms, 0 to 25,000, for a status change, a finished run, or `terminal`. A run changing phase doesn't end the wait. |

Once `experiment.experimentId` is set, use it with the other experiment tools ([Polling](https://docs.oqoqo.ai/mcp-server/overview.md#polling)).

### list\_experiments

**List experiments.** Lists the project's experiments with their tags and lineage. Experiments launched again or by a schedule share their source's name, so tell them apart by lineage.

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

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `query` | string | No | Text to match, up to 200 characters. |
| `statuses` | array of `running`, `completed`, `completed_with_errors`, `cancelled`, `errored` | No | Only these statuses. |
| `schedule_id`, `task_id`, `task_version_id`, `treatment_id`, `tool_id`, `tool_version_id`, `file_id`, `machine_id`, `agent_id`, `agent_model_id`, `friction_id` | string | No | Only experiments with a run that matches every one. Each takes the ID that [`list_runs`](https://docs.oqoqo.ai/mcp-server/runs-and-results#list_runs) describes. |
| `based_on_experiment_id` | string | No | Only the child experiments of this `exp_` parent experiment: launched again, edited, or scheduled from it. |
| `created_after`, `created_before` | string (date-time) | No | Only experiments created in this range. |
| `tags` | array of strings | No | Only experiments with any of these tags, by name or `tag_` ID. 1 to 20 tags. |
| `untagged` | boolean | No | `true`: only untagged experiments. With `tags`: experiments with those tags or with none. |
| `limit` | integer | No | Results per page, up to 200 (default 50). |
| `cursor` | string | No | The `nextCursor` from the previous page. |

An experiment is listed when one of its runs matches every scope field. `schedule_id` also lists a launched experiment that has no runs yet. An unknown ID returns `scope_not_found`. The result has no `scope`.

**Result fields**

Each experiment has its tags, `infraBlockedCount` ([Progress counts](https://docs.oqoqo.ai/mcp-server/overview.md#progress-counts)), and `lineage` as in [`get_experiment`](https://docs.oqoqo.ai/mcp-server/experiments#get_experiment). `hasMore` and `nextCursor` page the list.

### get\_experiment

**Get an experiment.** Returns an experiment's details, progress counts, launcher, runs used, and lineage.

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

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

**Result fields**

`lineage` has these parts:

* `launchedVia`: `new`, `from_experiment`, `schedule`, or `schedule_launch_now`.
* `basedOn`: the parent experiment, the one it was launched from, with `deleted: true` once it's gone.
* `schedule`: the `sch_` schedule that launched it, and its slot.
* `children`: its child experiments (list them with `list_experiments` and `based_on_experiment_id`), `scheduleCount`, and the 10 newest of those schedules (all of them with `list_schedules` and `experiment_id`).

### rename\_experiment

**Rename an experiment.** Renames an experiment without changing its `exp_` ID, runs, or results, so existing links keep working. Sending the name it already has changes nothing.

Changes data · CLI: [`oqoqo experiments rename`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-rename)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `experiment_id` | string | Yes | The `exp_` ID of the experiment to rename. |
| `name` | string | Yes | The new name, up to 120 characters. |
| `project_id` | string | No | The `prj_` project. |

**Result fields**

Returns `project` (`projectId`, `name`, `description`, `createdAt`, and `updatedAt`) and `experiment` (`experimentId`, `label`, and `dashboardUrl`). Fails with `experiment_not_found` if the experiment was deleted or belongs to another project.

### get\_experiment\_plan

**Get an experiment's launch plan.** Builds a launchable plan from an earlier experiment, at its task versions or the latest ones. Edit it, then pass it to `launch_experiment`.

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

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `experiment_id` | string | Yes | The `exp_` experiment. |
| `launch_attempt_id` | string | Yes | An ID you choose for the plan's `launchAttemptId`, so that a retry doesn't repeat the launch. It has 1 to 100 characters. |
| `version_mode` | `experiment`, `latest` | No | The experiment's task versions, or the latest. Default `latest`. |
| `comparison_id` | string | No | The `cmp_` ID of a likely difference. The plan then runs that likely difference again. |
| `after_fix` | boolean | No | With the `comparison_id` of a clear difference that lists a friction to fix in the product (its `afterFix` in [`get_experiment_brief`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#get_experiment_brief)): the plan runs it again after your fix, on the tasks where its two sides differed, with both sides and the experiment's runs each. Default `false`. |

With `comparison_id` from [`get_evals_comparisons`](https://docs.oqoqo.ai/mcp-server/evals-and-insights#get_evals_comparisons), the plan [runs that likely difference again](https://docs.oqoqo.ai/evaluation/comparisons.md#run-a-comparison-again-to-be-sure): the tasks that can still show a difference, the two sides (both treatments and agents for an `interaction`), and enough runs each to likely settle it. Launching the plan spends the person's runs, so say the run count and ask first. `version_mode` then defaults to `experiment`, treatments use their current tools as with **Launch again**, and Evals uses the latest Evals attempt's settings.

| Code | When |
| - | - |
| `comparison_not_found` | The ID names no comparison in the experiment's latest Evals. |
| `comparison_not_confirmable` | The comparison isn't a likely difference in the latest Evals, the experiment or its Evals is still running, or no confirmation can settle it. `details.reason` is `clear`, `unclear`, `earlier_evals`, `in_progress`, or `cannot_settle`. |
| `after_fix_unavailable` | With `after_fix`: the difference isn't clear in the latest Evals, the experiment, its Evals, or its Insights is still running, or no friction listed with it is fixed in the product. `details.reason` is `not_clear`, `in_progress`, or `no_product_friction`. |
| `rerun_selection_unavailable` | A task, treatment, or model used by the comparison is no longer available. |

### rerun\_experiment

**Launch an experiment again.** Relaunches a finished experiment with the same tasks, treatments, agents, trials, Evals, and Insights, or launches a schedule now with `schedule_id`. Evals and Insights run in the modes the experiment launched with, including [Agent mode](https://docs.oqoqo.ai/evaluation/agent-mode.md). If your organization can no longer use that Agent mode, the launch is refused with `agent_mode_unavailable`; use `get_experiment_plan` and set `evalsMode` or `insightsMode` to `standard`.

Changes data · You approve each call · CLI: [`oqoqo experiments rerun`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-rerun), [`oqoqo schedules launch`](https://docs.oqoqo.ai/cli/schedules#oqoqo-schedules-launch)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `experiment_id` | string | One of these two | The finished `exp_` experiment to launch again. |
| `schedule_id` | string | One of these two | The `sch_` schedule to launch now. |
| `launch_attempt_id` | string | Yes | An ID you choose, so that a retry doesn't repeat the change. It has 1 to 100 characters, and a retry returns the first launch. |
| `version_mode` | `experiment`, `latest` | No | The experiment's task versions, or the latest. Default `latest`. Omit when passing `schedule_id` (schedules always use the latest task versions). |

With `schedule_id`, it launches the schedule's experiment at the latest task versions, under the schedule's name, without moving the next launch. Refused calls return `experiment_schedule_run_active`, `rerun_selection_unavailable`, `agent_mode_unavailable`, `agent_mode_model_unsupported`, `quota_exceeded`, `no_entitlement`, `grant_expired`, `launch_attempt_conflict`, or `launch_attempt_spent`. Poll the `launchId` with `get_launch_status`. To change the plan first, use `get_experiment_plan`, then `launch_experiment`.

### get\_experiment\_status

**Get experiment status.** Returns the phase, `terminal`, and [progress counts](https://docs.oqoqo.ai/mcp-server/overview.md#progress-counts).

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

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `experiment_id` | string | Yes | The `exp_` experiment. |
| `wait_ms` | integer | No | Wait up to this many ms, 0 to 25,000. Omit or 0 for the current snapshot. |

While `terminal` is false, call again with `wait_ms` or after `pollAfterMs`. When `terminal` is true, read the final runs with `list_runs`.

### cancel\_experiment

**Cancel an experiment or run.** Cancels a whole experiment, or every still-active trial of one task, treatment, and agent combination. Completed work stays available.

Destructive · CLI: [`oqoqo experiments cancel`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-cancel)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `experiment_id` | string | Yes | The `exp_` experiment, or the `adm_` ID of a launch that has no experiment yet. |
| `run_id` | string | No | A `run_` ID. Cancels every still-active trial of the same task, treatment, and agent. |

A finished or stopping target returns its status. Poll `get_experiment_status` until the cancellation finishes.

### publish\_experiment

**Publish an experiment.** Creates a public link that anyone can view without an account, with runs, traces, outputs, Evals, Insights, and text files up to 256 KiB. Larger or binary files and private machine settings aren't shared.

Changes data · You approve each call · CLI: [`oqoqo experiments publish`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-publish)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `experiment_id` | string | Yes | The `exp_` experiment. |
| `title` | string | Yes | The public title, 1 to 120 characters. |
| `description` | string or null | No | The public description, up to 2,000 characters. |
| `show_organization` | boolean | No | Show your organization's name. Defaults to `false`. |
| `attempt_id` | string | Yes | An ID you choose, so that a retry doesn't repeat the change. It has 16 to 200 characters. |

Later results go live only through `update_experiment_publication`. Refused calls return `experiment_not_publishable`, `experiment_publication_already_exists`, `experiment_publication_attempt_reused`, or `public_metadata_contains_protected_content`. To share privately, invite the person to your organization ([Share results](https://docs.oqoqo.ai/evaluation/share.md)).

### list\_experiment\_publications

**List published experiments.** Lists your organization's public links.

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

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. Omit to list links across every project in the organization. |
| `experiment_id` | string | No | Only the links of this `exp_` experiment. |
| `statuses` | array of `preparing`, `active`, `failed`, `revoked` | No | Only these statuses. |
| `limit` | integer | No | Results per page, up to 200 (default 50). |
| `cursor` | string | No | The `nextCursor` from the previous page. |

### get\_experiment\_publication

**Get an experiment's public link.** Returns a link's status, current version, whether an update is available, and the `lockVersion` a change needs (takes no `project_id`).

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

| Parameter | Type | Required | Description |
| - | - | - | - |
| `publication_id` | string | Yes | The `pub_` public link ID. |

### update\_experiment\_publication

**Update a published experiment.** Replaces the results at the same link with the latest ones (takes no `project_id`). The earlier results stay until the update is ready.

Destructive · You approve each call · CLI: [`oqoqo experiments publications update`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-publications-update)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `publication_id` | string | Yes | The `pub_` public link ID. |
| `lock_version` | integer | Yes | From `get_experiment_publication`. A stale value returns `publication_changed`. |
| `attempt_id` | string | Yes | An ID you choose, so that a retry doesn't repeat the change. It has 16 to 200 characters. |
| `retry_pending` | boolean | No | `true` takes over an update stuck preparing, instead of refusing with `publication_preparation_in_progress`. Default `false`. |

Refused calls return `publication_not_found`, `publication_revoked`, `publication_changed`, `publication_preparation_in_progress`, or `publication_update_attempt_conflict`.

### unpublish\_experiment

**Unpublish an experiment.** Stops sharing an experiment, and the public link stops working at once (takes no `project_id`).

Destructive · CLI: [`oqoqo experiments publications unpublish`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-publications-unpublish)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `publication_id` | string | Yes | The `pub_` public link ID. |
| `lock_version` | integer | Yes | From `get_experiment_publication`. A stale value returns `publication_changed`. |

Unpublishing again returns the unpublished experiment (`publication_not_found` if unknown).

### get\_public\_experiment

**Get results from a public link.** Reads the results at a public experiment link, one section at a time (takes no `project_id`).

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

| Parameter | Type | Required | Description |
| - | - | - | - |
| `publication_id` | string | Yes | The `pub_` public link ID. |
| `section` | `overview`, `matrix`, `runs`, `frictions`, `evals`, `insights`, `trajectory`, `output`, `run-evals`, `files`, `task-details`, `treatment-details` | No | The part of the results to read. Default `overview`. |
| `run_key` | string | No | A run on the public page, such as `r1`. |
| `trial_key` | string | No | A trial, such as `trial1`. |
| `task_key` | string | No | A task, such as `task1`. |
| `treatment_key` | string | No | A treatment, such as `treatment1`. |
| `evaluation_key` | string | No | An Evals attempt, such as `e1`. |
| `insights_key` | string | No | An Insights attempt, such as `i1`. |
| `limit` | integer | No | Results per page, up to 200 (default 50). |
| `cursor` | string | No | The `nextCursor` from the previous page. |

A large Frictions result arrives in parts (`part.index` of `part.count`). Read every page, then append each part's clusters, family clusters, and outcome badge audits in order. A repeated `clusterKey` continues the previous cluster's occurrences.

## Related

> [card] [Runs and results tools](https://docs.oqoqo.ai/mcp-server/runs-and-results.md)
>
> Read runs, profiles, trajectories, and comparisons.

> [card] [Evals and Insights tools](https://docs.oqoqo.ai/mcp-server/evals-and-insights.md)
>
> Score runs, find frictions, and read the Brief.

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


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