participant tools

​

participant_cancel

Tier: write · Tags: participant, 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 participant_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 (pt-...) 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’s people. round: 1-indexed round filter (only meaningful with ask_id). Each cancelled row carries participant_id / success; each skipped row participant_id / reason ("already_terminal" for one that was terminal before the call); the summary carries total / cancelled_count / skipped_count. Returns {"cancelled": [...], "skipped": [...], "summary": {...}}. cancelled[*].success is False when the per-participant endpoint returned an error envelope, the text in the row’s optional status.

​

Parameters

​

participant_extend

Tier: long-running · Tags: dispatch, participant Resume a terminal participant with additional_steps more turns - the reversible “start” half of the participant_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. Bills credits per completed added step; live rates in account_usage().rates. participant_id: UUID or alias (pt-...) 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 240 - under the ~300 s idle limit at which Claude Code kills a silent call. On elapse a wait_timeout envelope returns while the run continues server-side, carrying the ids and a next_action hint that points at the resume poll. See docs_get("reference/long-running-jobs"). Returns a RunStudyResponse keyed by ok; dispatch.participant_ids carries the new participant id, and wait_timeout means the dispatch worked but the wait poll ran out. Full shape: docs_get(“reference/responses”).

​

Parameters