---
title: "Start a cloud instance"
method: POST
path: "/agentSession/{agent_session_id}/cloudInstance/{cloud_instance_id}/start"
tags: ["AgentSession"]
---

# Start a cloud instance

`POST /agentSession/{agent_session_id}/cloudInstance/{cloud_instance_id}/start`

Transitions a cloud instance from queued to running status. Requires orchestration authorization.

## Path parameters

- `agent_session_id` string, required
- `cloud_instance_id` string, required

## Headers

- `If-Match` string

## Response `200`

The updated cloud instance

- AgentCloudInstance
  - `id` string, required — The id of the cloud instance
  - `workspace_id` string, required — The id of the workspace
  - `agent_session_id` string, 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', 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' | '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.
  - `queued_time` integer — The timestamp when the cloud instance entered the queued status in epoch milliseconds
  - `started_time` integer — The timestamp when the cloud instance started running in epoch milliseconds
  - `termination_time` integer — The timestamp when the cloud instance entered the terminating status in epoch milliseconds
  - `end_time` integer — The timestamp when the cloud instance entered a terminal status (completed, failed, or terminated) in epoch milliseconds
  - `startup_params` CreateAgentCloudInstanceRequest — Request to create a new cloud instance
    - `impersonate_user_id` string — The ID of the user that the cloud instance should impersonate when running
    - `platform` 'none' | 'web' — The platform the agent operates on
    - `snapshot` string — 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.
    - `api_image` string — 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.
    - `resume_attempt_id` string — 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.
  - `session_startup_params_snapshot` union
    - object
      - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'app_modeling' | 'app_modeling_run' | 'file_assertion', required
      - `parent_session_id` string — The id of the parent session to review
      - `system_prompt` string — The system prompt that defines the review goals and instructions
      - `agent_subtype` 'test_authoring_analysis' | 'results_analysis_analysis' | 'failure_categorization_analysis' | 'failure_categorization_override_analysis' — Subtype for agent_review agents to distinguish different review purposes
      - `test_id` string — Optional test ID to give the review agent access to test definition and analysis tools
      - `test_run_id` string — Optional test run ID to give the review agent access to test run analysis tools
      - `plan_run_id` string — Optional plan run ID for results-analysis reviews of plan-run RAA sessions
      - `deployment_event_id` string — Optional deployment event ID for results-analysis reviews of deployment RAA sessions
      - `batch_id` string — Optional identifier linking reviews from the same backfill or batch run
    - object
      - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'app_modeling' | 'app_modeling_run' | 'file_assertion', required
      - `application_id` string — The id of the application to analyze
    - object
      - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'app_modeling' | 'app_modeling_run' | 'file_assertion', required
      - `agent_state` NextStepGenerationState — Agent model state tracked between generation requests
        - `entireTestPlan` TestCreationOutline — A test outline with tasks and suggested flows and snippets
          - `test_case` string, required — A clear description of the test case to be performed
          - `tasks` TestCreationTaskPlan[], required — A list of tasks to be performed
            - `task` string, required — A clear description of the task to be performed
            - `suggested_validation` string, required — Description of what to validate when this task is complete
            - `suggested_flow_options` TestCreationFlowOption[], required — List of recommended flow options for this task
              - …
            - `suggested_snippet_options` TestCreationSnippetOption[], required — List of recommended code snippet options for this task
              - …
            - `implementation_notes` string — Notes about how to create a good task for the plan, including information from relevant screenshots if available
            - `screenshots_cited` TestGenerationScreenshotReference[], required — List of screenshots cited in the implementation notes
              - …
          - `implementation_notes` string — Notes about how to create a good test from the plan, including when to use variables and important validations
        - `testInformation` TestCreationPlanningTestInformation — Test configuration and metadata selected during planning
          - `test_id` string — The ID of an existing test to edit instead of creating a new one
          - `test_variant_id` string — The variant (version) ID of the test being edited. Distinct from `test_id`, which is the invariant test identity — `test_variant_id` pins a specific snapshot. Set when the caller wants the edit applied against a known version (for example, to dedup auto-triggered edits for the same version).
          - `source_test_id` string — The invariant ID of an existing test to COPY as the starting point for a brand new test. The source test is only read — it is never modified — and the test that gets created is a new, independent test. Mutually exclusive with `test_id`, which edits an existing test in place rather than copying it. Set this when the user wants to start from an existing test ("make a copy of X and then ...") and leave `test_id` unset.
          - `name` string — The name of the test
          - `description` string — The description of the test
          - `application_id` string — The ID of the application for the test
          - `environment_id` string — The ID of the environment for the test
          - `deployment_id` string — The ID of the deployment for the test
          - `test_case` string — The test case for the test
          - `url_override` string — The base URL for the test, if there is no application or if the application's base URL should be overridden for this test
          - `credentials_id` string — The ID of the credentials for the test
          - `test_type` 'api' | 'browser' | 'performance' | 'mobile' — Type of test
          - `viewport_width` integer — Browser viewport width in pixels
          - `viewport_height` integer — Browser viewport height in pixels
          - `datatable_id` string — The ID of the data table for data-driven tests
          - `scenario_id` string — The ID of a specific scenario within the data table
          - `labels` string[] — Labels to apply to the test
          - `branch_id` string — The ID of the branch to save the test to (the save-to / destination branch)
          - `source_branch_id` string — The ID of the branch to load the test from as the starting point for edits. Only meaningful when test_id is set (editing an existing test). When unset, the test is loaded from master (it does NOT fall back to branch_id). This is the load-from branch; branch_id remains the save-to (destination) branch.
          - `plan_id` string — The ID of the plan to add the test to after creation
          - `device_preset` 'blackberry_playbook' | 'blackberry_z30' | 'galaxy_fold' | 'galaxy_note_3' | 'galaxy_note_ii' | 'galaxy_s5' | 'galaxy_s6' | 'galaxy_s8' | 'galaxy_s21' | 'galaxy_s22' | 'galaxy_s23' | 'galaxy_s_iii' | 'galaxy_tab_s7' | 'ipad' | 'ipad_air_2020' | 'ipad_mini' | 'ipad_mini_4' | 'ipad_pro' | 'ipad_ten_point_two' | 'iphone_11_pro_max' | 'iphone_11' | 'iphone_12' | 'iphone_12_pro_max' | 'iphone_13_mini' | 'iphone_13' | 'iphone_13_pro' | 'iphone_13_pro_max' | 'iphone_14' | 'iphone_14_pro' | 'iphone_14_plus' | 'iphone_14_pro_max' | 'iphone_15' | 'iphone_15_plus' | 'iphone_15_pro' | 'iphone_15_pro_max' | 'iphone_4' | 'iphone_5_se' | 'iphone_6_7_8' | 'iphone_6_7_8_plus' | 'iphone_x' | 'jiophone_2' | 'kindle_fire_hdx' | 'laptop_with_hidpi_screen' | 'laptop_with_mdpi_screen' | 'laptop_with_touch' | 'lg_optimus_l70' | 'microsoft_lumia_550' | 'microsoft_lumia_950' | 'moto_g4' | 'nexus_4' | 'nexus_5' | 'nexus_5x' | 'nexus_6' | 'nexus_6p' | 'nexus_7' | 'nexus_10' | 'nokia_lumia_520' | 'nokia_n9' | 'pixel_2' | 'pixel_2_xl' | 'pixel_6' | 'surface_duo' — Preset device configuration
          - `device_orientation` 'portrait_primary' | 'portrait_secondary' | 'landscape_primary' | 'landscape_secondary' — Device orientation
      - `application_id` string — The ID of the application being tested
      - `environment_id` string — The ID of the environment being tested
      - `url` string — The URL to start testing from
      - `agent_session_source` 'user_web' | 'user_mcp' | 'user_cli' | 'auto_tra' | 'user_tra' | 'unknown' — Origin of an agent session — who or what initiated it. `user_web`, `user_mcp`, `user_cli` distinguish the human-driven entry point. `auto_tra` marks sessions automatically started by the Test Recovery Agent (runtime recovery). `user_tra` marks edits the user explicitly accepted from a TRA suggestion. `unknown` is used when no source was provided.
      - `test_variant_id` string — The variant (version) ID of the test being edited, when this session is an edit of a specific known version. Set in conjunction with `test_information.test_id`.
      - `resume_cursor` string — Optional 1-based-inclusive index of the last saved step the next instance replays before continuing the LLM loop (e.g. "5" replays steps 1–5; absent or "0" replays nothing). Set by the resume planner on continue via `PATCH /agentSession/{id}/startupParams`; not used at session creation.
      - `test_id` string — The invariant id of the test this authoring session operates on. Set at session creation for edits (mirrored from `test_information.test_id`) and rolled forward by the cloud TAA continuation flow at each save/pause via `PATCH /agentSession/{id}/startupParams`, so a resuming instance continues the same test rather than authoring a new one.
      - `branch_id` string — (Optional) The id of the save-to branch — every test and flow version the agent writes lands on it, leaving master untouched. Set once at session creation and mirrored from `test_information.branch_id`; a supplied name is canonicalized to the id, which must resolve inside the session's workspace. An edit session (`test_id` set) that omits it gets a server-created feature branch unless the workspace sets `require_agent_edits_on_branches: false`; creation sessions author on master. Absent on local sessions, which carry the value on `test_information`. A resume reuses it. The branch outlives the session and is closed only by a merge into master (via the branch merge endpoint or `auto_merge`), which is also what flips the session to `merged`.
      - `source_branch_id` string — (Optional) The id of the load-from branch — the branch the agent reads the starting test version from. Mirrored from `test_information.source_branch_id` at session creation. The agent never saves to it (it saves to `branch_id`); when unset, the version loads from master (it does NOT fall back to `branch_id`). Only meaningful for edit sessions.
      - `base_version` integer — (Optional) The immutable source-branch version number the edit LOADED FROM — the variant of the `source_branch_id` branch (or master, when unset) at the moment the runtime fetched the starting test. Written once by the runtime at initial load and never rolled forward, so it pins the "Review changes" diff baseline to the version actually edited rather than the source branch's current tip (which can advance while the edit is in flight). Only meaningful for edit sessions; absent on older sessions, where consumers fall back to the source branch's current version tag.
      - `auto_merge` boolean — When true, the session's `branch_id` is merged into master on a successful session completion (provided the branch still resolves to this workspace and has new versions). Defaults to absent/false — the branch is left open for human review.
    - object
      - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'app_modeling' | 'app_modeling_run' | 'file_assertion', required
      - `test_run_id` string — The ID of the test run to analyze
    - object
      - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'app_modeling' | 'app_modeling_run' | 'file_assertion', required
      - `plan_run_id` string — The ID of the plan run to analyze
    - object
      - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'app_modeling' | 'app_modeling_run' | 'file_assertion', required
      - `deployment_event_id` string — The ID of the deployment event to analyze
    - object
      - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'app_modeling' | 'app_modeling_run' | 'file_assertion', required
      - `training_session_id` string — Optional training session ID for tracing
    - object
      - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'app_modeling' | 'app_modeling_run' | 'file_assertion', required
      - `application_id` string — The id of the application the app modeling session builds a knowledge graph for
    - object
      - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'app_modeling' | 'app_modeling_run' | 'file_assertion', required
      - `application_id` string — The id of the application this coordinator run models
    - object
      - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'app_modeling' | 'app_modeling_run' | 'file_assertion', required
      - `test_run_id` string — The ID of the test run this file assertion evaluation belongs to.
  - `created_time` integer, required — The timestamp of the cloud instance creation in epoch milliseconds
  - `created_by_id` string, required — The id of the user who created the cloud instance
  - `last_updated_time` integer, required — The timestamp of the cloud instance last update in epoch milliseconds
  - `last_updated_by_id` string, required — The id of the user who last updated the cloud instance

## Other responses

- `400` — Invalid or missing parameter
- `401` — User not authenticated
- `403` — User not authorized
- `404` — Entity not found
- `409` — unresolved $ref
- `429` — Rate limited - instance is in rate_limited status awaiting quota
- `default` — Unknown error

---

[API](https://skmtc.net/mabl/apis/mabl-api.md) · [All operations](https://skmtc.net/mabl/apis/mabl-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mabl/mabl-api/revisions/d0fc0114da66/schema)