Session and run states
| Run state | Meaning | Integration action |
|---|---|---|
accepted | Task accepted | Store identifiers and wait |
starting | Environment preparation | Observe preparation and hooks |
running | Agent executing | Clarifications can be sent |
cancelling | Cancellation in progress | Wait for cancellation to finish |
finalizing | Finalization and hooks | Wait for delivery outcome |
completed | Run succeeded | Read the result |
failed | Run failed | Inspect error, phase and hooks |
cancelled | Run cancelled | Check 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.