---
title: "Begin resuming an agent session (flip it to the transient `resuming` status)"
method: POST
path: "/agentSession/{id}/beginResume"
tags: ["AgentSession"]
---

# Begin resuming an agent session (flip it to the transient \`resuming\` status)

`POST /agentSession/{id}/beginResume`

Atomically transitions a resumable test-authoring session to the transient `resuming` status, BEFORE the resume planner runs. This is the concurrency guard for the cloud TAA continuation flow: two concurrent answers to the same `needs_attention` session cannot both run a planner or spawn competing cloud instances, because only one wins the flip to `resuming` and the loser gets a 409. Granted only when the session's `latest_instance_status` is resumable (`needs_attention`, `failed`, or `completed`), or it is already `resuming` but stale (last updated longer ago than the server-side TTL — a crashed attempt, safe to steal). A live (non-stale) `resuming` session returns 409. The session leaves `resuming` when the resume spawns a new instance (→ `queued`) or via a `status_update` on the messages endpoint (re-clarification / error restore); a crashed attempt is reclaimed by the next answer's TTL steal. Only `test_authoring` sessions accept this call.

## Path parameters

- `id` string, required

## Response `200`

The agent session, now in the `resuming` status

- 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' — 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).
          - `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 branch the agent operates on. Lifecycle is documented on `TestAuthoringSessionStartupParams.branch_id`.
      - `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.
      - `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' | '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`. `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.
  - `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.dev/mabl/apis/mabl-api.md) · [All operations](https://skmtc.dev/mabl/apis/mabl-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mabl/mabl-api/revisions/97321e29d020/schema)