Create a new cloud instance for a session

The ID of the user that the cloud instance should impersonate when running. Defaults to the launching person; the stored value is the person the instance acts for, or empty when it acts as the workspace agent user.

Set by the server, ignored on input. True when the instance acts for a support admin who is not a member of the workspace.

Set by the server, ignored on input. True when impersonate_user_id holds the resolved principal the instance acts for rather than the requested target.

The platform the agent operates on

Optional. A specific snapshot Docker image tag — the commit SHA of a published agent build — to launch this agent type from instead of its standard deployed image. Used to exercise a pre-release/preview build within a session. Leave unset to use the agent type's normal deployed image.

Optional. A mabl API deploy-preview tag (e.g. dp-my-branch) that routes the launched cloud agent's own API calls through https://<tag>.api-preview.mabl.com instead of the standard API. Used to exercise API changes end-to-end within an authoring session. Non-prod, cloud-mode only. Leave unset to use the standard API.

Optional. The resume attempt id (the resume cycle's user_message_id). When present, the create transaction atomically binds this attempt's resume_payload_<cycle> artifact to the new instance (spawn_resolution='spawned' plus spawned_instance_id) in the same commit that creates the instance and flips the session status. Test-authoring resume spawns only; ignored otherwise.

The id of the cloud instance

The id of the workspace

The id of the agent session this instance belongs to

The status of the latest agent instance driving a session. The same enum is used for cloud and local instances. Cloud-only values (queued, terminating, rate_limited, skipped) are set by the cloud instance lifecycle (start/terminate/end). Common values (running, needs_attention, completed, failed, terminated) are written by either cloud or local clients. merged is a session-level state applied after a completed authoring task's branch is merged into master (via the branch merge endpoint or the session's auto_merge setting); the underlying cloud instance stays completed. accepted and closed are session-level review outcomes for a finished authoring task, set only through the review endpoint; the underlying cloud instance keeps its own status. accepted records that the user kept the authored test. closed records that the user discarded it; the session's test is left in place unless the caller asked for it to be deleted (delete_test on the review request), no branch is deleted either way, and the session's conversation is retained so the task can be regenerated from it. Both are terminal in the same sense as merged — neither is resumable, and no lifecycle transition leaves them. resuming is a transient, server-set-only state on the session (no instance holds it) — the cloud TAA continuation flow flips a resumable session to resuming while it plans the answer, then to queued when the new instance spawns (or back to a resumable status on re-clarification, or failed on error). It is the concurrency guard, so a second answer to a resuming session is rejected. The session's instance_type field indicates which kind of instance owns the session. Use none in query parameters to match sessions without any status.

The platform the agent operates on

The reason for terminating a cloud instance. 'infra_shutdown' covers any shutdown signal from the runtime environment (K8s pod eviction, Cloud Run instance cycling, etc.) — kept generic so it applies regardless of where the agent runs. 'dispatch_failed' means the instance never started — its start message failed to publish, or expired in the queue before any runner claimed it. 'agent_stalled' means the agent was still alive but stopped making progress, so a watchdog hard-killed it. 'agent_error' means the agent threw or exited unexpectedly while its work was still in flight.

The timestamp when the cloud instance entered the queued status in epoch milliseconds

The timestamp when the cloud instance started running in epoch milliseconds

The timestamp when the cloud instance entered the terminating status in epoch milliseconds

The timestamp when the cloud instance entered a terminal status (completed, failed, or terminated) in epoch milliseconds

The timestamp of the cloud instance creation in epoch milliseconds

The id of the user who created the cloud instance

The timestamp of the cloud instance last update in epoch milliseconds

The id of the user who last updated the cloud instance