Sign in
AgentSession

Terminate a cloud instance

Transitions a cloud instance from a non-terminal status to terminating. Requires write authorization.

post/agentSession/{agent_session_id}/cloudInstance/{cloud_instance_id}/terminate

Path parameters

agent_session_idstring required

The ID of the agent session

cloud_instance_idstring required

The ID of the cloud instance

Query parameters

reason'execution_timeout' | 'stop_requested' | 'infra_shutdown' | 'dispatch_failed' | 'agent_stalled' | 'agent_error' | 'unknown'

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 reason for terminating the instance

Headers

If-Matchstring

If-Match header according to http/1.1 spec section 14.24

Response

The updated cloud instance

idstring required

The id of the cloud instance

workspace_idstring required

The id of the workspace

agent_session_idstring required

The id of the agent session this instance belongs to

agent_type'test_authoring' | 'test_creation_planning' | 'test_planning' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'test_recovery' | 'runtime_recovery_summary_agent' | 'plan_run_analysis' | 'deployment_analysis' | 'workspace_results_analysis' | 'results_auto_analysis' | 'app_modeling' | 'app_modeling_run' | 'file_assertion' | 'test_impact' required
status'queued' | 'running' | 'needs_attention' | 'completed' | 'failed' | 'terminated' | 'terminating' | 'rate_limited' | 'skipped' | 'merged' | 'accepted' | 'closed' | 'resuming' | 'none' required

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 their own endpoints; 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 authored test and its steps are deleted while the session's conversation is retained. 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.

platform'none' | 'web'

The platform the agent operates on

termination_reason'execution_timeout' | 'stop_requested' | 'infra_shutdown' | 'dispatch_failed' | 'agent_stalled' | 'agent_error' | 'unknown'

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.

queued_timeinteger

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

started_timeinteger

The timestamp when the cloud instance started running in epoch milliseconds

termination_timeinteger

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

end_timeinteger

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

created_timeinteger required

The timestamp of the cloud instance creation in epoch milliseconds

created_by_idstring required

The id of the user who created the cloud instance

last_updated_timeinteger required

The timestamp of the cloud instance last update in epoch milliseconds

last_updated_by_idstring required

The id of the user who last updated the cloud instance

Changes