Skip to content

Session and run states ​

Run stateMeaningIntegration action
acceptedTask acceptedStore identifiers and wait
startingEnvironment preparationObserve preparation and hooks
runningAgent executingClarifications can be sent
cancellingCancellation in progressWait for cancellation to finish
finalizingFinalization and hooksWait for delivery outcome
completedRun succeededRead the result
failedRun failedInspect error, phase and hooks
cancelledRun cancelledCheck actions already performed

active_run_id identifies unfinished work. last_run_id identifies the latest run. Check the specific run before publishing its result. Final text can appear before after_run finishes.

Sandbox state is separate: not_created, provisioning, ready, pausing, paused, resuming, deleting, deleted, unavailable. A retained sandbox ID does not guarantee accessibility.

Errors contain code, message, phase and details. Error phases are preparation, execution, finalization and recovery. Execution phase can identify after_create, before_run, agent or after_run.

With allow_multiple_runs: false, the sandbox is deleted after its only run completes, fails or is cancelled. Session history remains available. With true, the sandbox is paused, and the session can accept another run when context and budget remain available. If context is lost, create a new session with the necessary history from your system.

A sandbox whose initial provisioning was cancelled or timed out is deleted even for a reusable session. The sandbox state remains unavailable, and session history stays readable. Resource cleanup can finish after the run is terminal. See provisioning limits and troubleshooting.

Paused reusable sandboxes expire under the retention policy, by default after 14 days since the latest run finished. Deletion preserves the run result. Check the sandbox state before choosing a continuation target and still handle 409 session_unavailable: it can change before the request.