--- title: "Update an agent session's startup params" method: PATCH path: "/agentSession/{id}/startupParams" tags: ["AgentSession"] --- # Update an agent session's startup params `PATCH /agentSession/{id}/startupParams` Partial update of the resumable subset of an agent session's `startup_params` field, used by the cloud Test Authoring Agent (TAA) continuation flow to roll the session's "latest used / next to be used" authoring context forward. All fields are optional; only fields present in the body are written. Creation-attribution fields on the underlying `startup_params` (`agent_session_source`, `test_variant_id`) and the polymorphic discriminator (`type`) are preserved unchanged across every call — this endpoint is NOT a full partial-update of the `startup_params` JSON object. Only sessions whose `agent_type` is `test_authoring` accept this update; other agent types receive a 409. Uses If-Match for optimistic locking against concurrent updates. ## Path parameters - `id` string, required ## Headers - `If-Match` string ## Request body - UpdateAgentSessionStartupParamsRequest — Partial update of the resumable subset of an agent session's `startup_params` field, used by the cloud TAA continuation flow to roll the session's "latest used / next to be used" authoring context forward. All fields are optional; only fields present in the body are written. Creation-attribution fields on the underlying `startup_params` (`agent_session_source`, `test_variant_id`) and the polymorphic discriminator (`type`) are preserved unchanged — this endpoint is NOT a full partial-update of the `startup_params` JSON object. - `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 - `flow_id` string, required — The unique identifier of the flow to be used - `flow_name` string, required — The provided human-readable name of the flow - `reasoning` string, required — Explanation of why this flow is recommended for the task - `preference` 'primary' | 'secondary', required — Whether this is a primary or secondary flow option - `suggested_snippet_options` TestCreationSnippetOption[], required — List of recommended code snippet options for this task - `snippet_id` string, required — The unique identifier of the code snippet to be used - `snippet_name` string, required — The human-readable name of the code snippet - `reasoning` string, required — Explanation of why this snippet is recommended for the task - `preference` 'primary' | 'secondary', required — Whether this is a primary or secondary snippet option - `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 - `test_run_id` string, required — The ID of the test run that contains the screenshot - `entry_id` integer, required — The entry ID for the log line that contains the screenshot - `image_url` string — Unsigned URL to the screenshot image - `message` string — The step description or message associated with this screenshot - `url` string — The page URL where this screenshot was taken - `step_name` string — The name of the test step where this screenshot was captured - `success` boolean — Whether the step that generated this screenshot was successful - `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 - `resume_cursor` string — 1-based-inclusive index of the last saved step to replay before the resumed instance continues (absent or "0" replays nothing). Set by the resume planner on continue. - `test_id` string — The invariant id of the test the session operates on. Set by the resume flow at pause (and at each save) so the next instance continues the same test. - `url` string — The URL the next instance should boot against (the pausing pod's most recent URL). - `application_id` string — Refined application id if the pausing pod resolved a previously-unknown application. - `environment_id` string — Refined environment id if the pausing pod resolved a previously-unknown environment. - `branch_id` string — The id of the branch the agent operates on. Lifecycle is documented on `TestAuthoringSessionStartupParams.branch_id`. - `base_version` integer — The source-branch version the edit actually LOADED FROM, reported by the runtime once at initial load (see `TestAuthoringSessionStartupParams.base_version`). This is the server-computed `entity_version` the load returned, not a value the caller derives. Write-once and validated: it is stored only when the session has no `base_version` yet and the supplied version is >= 0 (versions are zero-indexed, so 0 is a valid initial-version baseline; a negative sentinel is dropped). A later pause/save that re-sends it (or a newer value) is ignored, so the baseline can never drift off the loaded version. - `auto_merge` boolean — Whether the session's branch should be auto-merged into master on clean completion. - `test_information_updates` ResumableTestInformationUpdates — The allowlisted subset of `agent_state.testInformation` that the cloud TAA resume flow may merge field-by-field. Security-reviewed: these are the only nested fields the startup-params setter will write. References/ids only — never secret values. Keep in sync with `RESUMABLE_TEST_INFORMATION_FIELDS` in `AgentSessionServiceImpl`. - `credentials_id` string — The id of the credential to bind for the resumed session (an id only — the secret is resolved + pre-fetched by the pod, never stored here). - `datatable_id` string — The id of the data table for data-driven steps. - `scenario_id` string — The id of the scenario (a named row) within the data table. Must belong to the effective data table — the setter rejects an incoherent pair. - `url_override` string — The base/start URL the resumed session should use (kept coherent with the top-level `url`). - `application_id` string — The application id (kept coherent with the top-level `application_id`). - `environment_id` string — The environment id (kept coherent with the top-level `environment_id`). ## Response `200` The updated agent session - AgentSession - `id` string, required — The id of the agent session - `workspace_id` string, required — The id of the workspace - `created_time` integer, required — The timestamp of the agent session creation in epoch milliseconds - `created_by_id` string, required — The id of the user who created the agent session - `last_updated_time` integer, required — The timestamp of the agent session last update in epoch milliseconds - `last_updated_by_id` string, required — The id of the user who last updated the agent session - `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 - `is_trial` boolean, required — Whether this agent session is associated with a trial account - `parent_session_id` string — The id of the parent agent session - `initiating_request_id` string — A unique identifier for the request that initiated this agent session. If set, this must be globally unique and requests to create a new agent session with the same initiating_request_id will fail. - `startup_params` 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. - `messages` AgentSessionMessage[], required — The messages in the agent session - union - BaseMessage - `id` string, required — The id of the message - `message_index` integer — The index of the message in the session (used for ordering) - `timestamp` integer, required — The timestamp of the message in epoch milliseconds - `metadata` object — The metadata of the message - `parts` MessagePart[], required - union - object - … - object - … - object - … - object - … - object - … - object — Code the model asked the Gemini built-in Python execution sandbox to run. Emitted alongside a matching CodeExecutionResultPart on the same model turn — the sandbox runs synchronously and returns its result in the same response. Only appears when the agent enables the code execution tool and the model chooses to use it. - … - object — The result of the sandbox executing the immediately preceding CodeExecutionCallPart. Bundled with the call on the same model turn; there is no separate tool-output round-trip. - … - `role` 'user' | 'model' | 'tool_output' | 'special', required - BaseMessage - `id` string, required — The id of the message - `message_index` integer — The index of the message in the session (used for ordering) - `timestamp` integer, required — The timestamp of the message in epoch milliseconds - `metadata` object — The metadata of the message - `parts` MessagePart[], required - union - object - … - object - … - object - … - object - … - object - … - object — Code the model asked the Gemini built-in Python execution sandbox to run. Emitted alongside a matching CodeExecutionResultPart on the same model turn — the sandbox runs synchronously and returns its result in the same response. Only appears when the agent enables the code execution tool and the model chooses to use it. - … - object — The result of the sandbox executing the immediately preceding CodeExecutionCallPart. Bundled with the call on the same model turn; there is no separate tool-output round-trip. - … - `role` 'user' | 'model' | 'tool_output' | 'special', required - BaseMessage - `id` string, required — The id of the message - `message_index` integer — The index of the message in the session (used for ordering) - `timestamp` integer, required — The timestamp of the message in epoch milliseconds - `metadata` object — The metadata of the message - `parts` MessagePart[], required - union - object - … - object - … - object - … - object - … - object - … - object — Code the model asked the Gemini built-in Python execution sandbox to run. Emitted alongside a matching CodeExecutionResultPart on the same model turn — the sandbox runs synchronously and returns its result in the same response. Only appears when the agent enables the code execution tool and the model chooses to use it. - … - object — The result of the sandbox executing the immediately preceding CodeExecutionCallPart. Bundled with the call on the same model turn; there is no separate tool-output round-trip. - … - `role` 'user' | 'model' | 'tool_output' | 'special', required - BaseMessage - `id` string, required — The id of the message - `message_index` integer — The index of the message in the session (used for ordering) - `timestamp` integer, required — The timestamp of the message in epoch milliseconds - `metadata` object — The metadata of the message - `parts` MessagePart[], required - union - object - … - object - … - object - … - object - … - object - … - object — Code the model asked the Gemini built-in Python execution sandbox to run. Emitted alongside a matching CodeExecutionResultPart on the same model turn — the sandbox runs synchronously and returns its result in the same response. Only appears when the agent enables the code execution tool and the model chooses to use it. - … - object — The result of the sandbox executing the immediately preceding CodeExecutionCallPart. Bundled with the call on the same model turn; there is no separate tool-output round-trip. - … - `role` 'user' | 'model' | 'tool_output' | 'special', required - `instance_ids` string[] — IDs of all cloud instances created for this session (in chronological order). Empty for local-client-driven sessions. - `instance_type` 'cloud' | 'local' — Indicates what kind of agent instance is driving a session. `cloud` means a server-managed cloud instance owns the lifecycle (created via the cloudInstance endpoints). `local` means a local client (e.g. mabl CLI) is driving the session via updateAgentSession. - `latest_instance_status` 'queued' | 'running' | 'needs_attention' | 'completed' | 'failed' | 'terminated' | 'terminating' | 'rate_limited' | 'skipped' | 'merged' | 'accepted' | 'closed' | 'resuming' | 'none' — 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. - `latest_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. - `related_artifacts` Artifact[] — Artifacts related to this agent session (e.g., generated tests, flows, etc.). Visible to all workspace members via queryAgentSessions — do not store creator-private content here; use `messages` for private content. - union - BaseArtifact - `artifact_type` 'inline' | 'remote', required — The type of artifact - BaseArtifact - `artifact_type` 'inline' | 'remote', required — The type of artifact - `agent_variant` string — The authoring-agent arm assigned to this session at creation time (values: `generic` or `flexible`). Records which test-authoring agent variant the runtime should use for the session. Only set for `test_authoring` sessions; unset for other agent types. ## Other responses - `400` — Invalid or missing parameter - `401` — User not authenticated - `403` — User not authorized - `404` — Entity not found - `409` — unresolved $ref - `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)