simulation tools

​

simulation_cancel

Tier: write · Tags: simulation, write Cancel queued or running simulations - the reversible “stop” half of the cancel/extend pair; a cancelled run can be resumed from its last interaction via simulation_extend (docs_get("concepts/extending-a-simulation")). Walks each affected participant to cancelled. Persisted artifacts (participant rows, interactions, transcripts) survive - a status flip, not a data removal, hence WRITE not DESTRUCTIVE. Participants already terminal are skipped without dispatch. Set exactly one scope of participant_id / study_id / iteration_id / ask_id:

• participant_id: cancel that single participant’s simulation.
• study_id: cancel every active participant under any iteration of the study.
• iteration_id: cancel every active participant under one iteration.
• ask_id (+ optional round): cancel active participants in that ask, scoped to one round when round is given (1-indexed) or all rounds otherwise.

participant_id: UUID or alias (t-...) of one participant. study_id: UUID or alias (s-...) - fans out across all iterations. iteration_id: UUID or alias (i-...) - fans out across one iteration. ask_id: UUID or alias (a-...) - fans out across the ask audience. round: 1-indexed round filter (only meaningful with ask_id). Returns {"cancelled": [{"participant_id", "success", "status"?}, ...], "skipped": [{"participant_id", "reason"}, ...], "summary": {"total", "cancelled_count", "skipped_count"}}. cancelled[*].success is False when the per-participant endpoint returned an error envelope; the error text lands in status. Skipped reasons cover terminal-state participants ("already_terminal").

​

Parameters

​

simulation_extend

Tier: long-running · Tags: dispatch, simulation Resume a terminal participant with additional_steps more turns - the reversible “start” half of the simulation_cancel + extend pair (docs_get("concepts/extending-a-simulation")). The source must be terminal (completed / failed / cancelled). The backend spawns a new participant under the same iteration, branched from the source’s last interaction; the source row is untouched. participant_id: UUID or alias (t-...) of the source participant. additional_steps: more interactions to allow past the original cap. Default 10; capped server-side (the failure envelope names the bound). instruction: optional user message injected as overriding direction for the rest of the run (e.g. “Stop browsing - switch to the German picker.”). wait: when True, block until the new participant is terminal. Default False - return immediately with the dispatched id. timeout: seconds to wait when wait=True. Default 600. On elapse a wait_timeout envelope returns while the run continues server-side; the next_action hint points at the resume poll. See docs_get("reference/long-running-jobs"). Returns a RunStudyResponse envelope discriminated by ok. On success (ok=True) dispatch.participant_ids carries the new participant id (one entry); the source participant id is the input. On failure (ok=False) error_kind is one of validation_error (source not terminal, bad additional_steps), not_found (unknown participant_id), wait_timeout (dispatch fine but the wait poll ran out), or a backend error code.

​

Parameters