---
title: "Query agent sessions"
method: GET
path: "/agentSession"
tags: ["AgentSession"]
---

# Query agent sessions

`GET /agentSession`

Query agent sessions with optional filters

## Query parameters

- `workspace_id` string, required
- `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'
- `agent_types` AgentType[]
- `latest_instance_status` AgentInstanceStatus[]
- `created_by_id` string
- `test_variant_id` string
- `test_id` string
- `branch_id` string
- `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.
- `limit` integer
- `cursor` string

## Response `200`

Query results

- AgentSessionQueryResult — Result of querying agent sessions
  - `items` AgentSessionSummary[], required — The agent sessions matching the query
    - `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
              - …
            - `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.
    - `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` on the full AgentSession for private content.
      - union
        - BaseArtifact
          - `artifact_type` 'inline' | 'remote', required — The type of artifact
        - BaseArtifact
          - `artifact_type` 'inline' | 'remote', required — The type of artifact
  - `cursor` string — Cursor for the next page of results

## Other responses

- `400` — Invalid or missing parameter
- `401` — User not authenticated
- `403` — User not authorized
- `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)