Skip to main content
Validate launch plans, launch and monitor experiments, rename them, cancel running work, and manage public experiment links. See Launch an experiment for product rules.
  • Badges are explained under Approvals.
  • project_id is optional on most tools; without it, the server picks a project for that call only (Projects).
  • expected_organization_id is an optional string on every write tool, omitted from parameter tables; pass organization.id from get_identity (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 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, 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.

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 Fields of plan: Result fields A refused launch returns one of these codes:

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, oqoqo experiments watch Once experiment.experimentId is set, use it with the other experiment tools (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 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), and lineage as in 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 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 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 With comparison_id from get_evals_comparisons, the plan runs that likely difference again: 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.

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. 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, oqoqo schedules launch 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. Read-only · CLI: oqoqo experiments status, oqoqo experiments watch 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 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 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).

list_experiment_publications

List published experiments. Lists your organization’s public links. Read-only · CLI: oqoqo experiments publications list

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

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

Runs and results tools

Read runs, profiles, trajectories, and comparisons.

Evals and Insights tools

Score runs, find frictions, and read the Brief.

oqoqo experiments

The matching CLI commands and flags.