- Badges are explained under Approvals.
project_idis optional on most tools; without it, the server picks a project for that call only (Projects).expected_organization_idis an optional string on every write tool, omitted from parameter tables; passorganization.idfromget_identity(Organization check).limitvalues 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 alaunchId (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 thelaunchId 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, orschedule_launch_now.basedOn: the parent experiment, the one it was launched from, withdeleted: trueonce it’s gone.schedule: thesch_schedule that launched it, and its slot.children: its child experiments (list them withlist_experimentsandbased_on_experiment_id),scheduleCount, and the 10 newest of those schedules (all of them withlist_schedulesandexperiment_id).
rename_experiment
Rename an experiment. Renames an experiment without changing itsexp_ 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 tolaunch_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 withschedule_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 thelockVersion 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 noproject_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 noproject_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 noproject_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.
Related
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.

