---
title: "Queue test runs for execution"
method: POST
path: "/v1/test-cases/run"
tags: ["test-cases"]
---

# Queue test runs for execution

`POST /v1/test-cases/run`

Queue one or more test runs for execution on specified or auto-selected devices.

    **Smart Defaults:**
    - Specify `platform` (ios/android) to auto-select the most recent app file and default device
    - Or provide explicit `app_file_id` and/or `device` configuration
    - Platform is required if app_file_id or device is not specified

    **Device / SIM:**
    - Optional `device.sms_enabled` (true/false): set when the user picks an SMS-enabled device (e.g. from GET /v1/devices).
    - Optional `use_sim` (true/false): use simulator/SIM for SMS; if omitted, derived from `device.sms_enabled`.

    **Limits:**
    - Minimum: 1 job per request

    **Process:**
    1. Validates that the requested device exists in the devices table with availability=True
    2. Validates that test_case_id and app_file_id belong to your organization
    3. Creates test_run records with 'queued' status
    4. Creates job records for the test execution queue

    **Returns:**
    - Links to view each test run at https://app.qualgent.ai/test-runs/{id}

    **Transaction Handling:**
    - If any job fails, all jobs in the batch are rolled back
    - Ensures data consistency across test_runs and test_jobs_pgqueuer tables

## Headers

- `x-api-key` string

## Request body

- RunTestRequest — Request to queue one or more test runs
  - `jobs` JobRequest[], required — List of test run jobs to queue
    - `test_case_id` string, required — ID of the test case to execute
    - `platform` string, nullable — Platform to use for auto-selecting app and device (ios/android). Required if app_file_id or device not specified.
    - `app_file_id` string, nullable — ID of the uploaded application file to test. If not provided, uses most recent file for specified platform.
    - `device` AppRoutersTestCasesDeviceConfig — Device configuration for test execution
      - `name` string, required — Device name or identifier
      - `platform` string, required — Device platform
      - `os_version` string, nullable — Operating system version
      - `orientation` string, nullable — Device orientation
      - `sms_enabled` boolean, nullable — Whether the device has SMS capability (e.g. for OTP). Set when user picks an SMS-enabled device.
    - `execution_mode` string, nullable — Execution mode: 'agent' (AI-driven) or 'maestro' (replay cached YAML). Defaults to 'agent'.
    - `test_case_version_id` string, nullable — ID of the test case version (test_case_versions.id) to run. If provided, test_runs will store test_case_version_id and test_case_version_number.
    - `use_sim` boolean, nullable — Whether to use simulator / SIM (e.g. for SMS). Can be derived from device.sms_enabled when not set.
    - `audit_source_run_id` string, nullable — Test run ID of a previously audited run; when set, audit feedback is injected into agent context on rerun.
    - `additional_app_file_ids` string[], nullable — IDs of additional app files for multi-app testing (max 3). Linked via test_run_additional_apps junction table.
    - `vars` object, nullable — Supplied values for the test case's declared variables. Keys must match variable names declared on the test case; values must match declared types. Unknown keys are ignored with a warning; missing required variables (with no default) cause a 400.

## Response `200`

Test runs successfully queued

- RunTestResponse — Response after queuing test runs
  - `success` boolean, required — Whether the operation succeeded
  - `jobs` TestRunLink[], required — Links to created test runs
    - `link` string, required — URL to view test run
  - `warnings` VariableWarning[], nullable — Non-fatal signals about variables supplied on the run. Currently used to report supplied keys that are not declared on the test case and were ignored.
    - `code` string, required — One of: 'undeclared_reference' (step references a name not declared), 'literal_collision' (declaring a new variable turns existing literal `{{x}}` text into a substitution), 'unknown_variable' (run supplied a variable not declared on the test case; dropped silently).
    - `message` string, required — Human-readable explanation

## Other responses

- `400` — Bad request - empty jobs list, invalid device, invalid test_case_id/app_file_id, or invalid test_case_version_id
- `401` — Invalid or missing API key
- `422` — Validation Error
- `500` — Internal server error

---

[API](https://skmtc.dev/qualgent/apis/qualgent-api-service.md) · [All operations](https://skmtc.dev/qualgent/apis/qualgent-api-service/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/qualgent/qualgent-api-service/revisions/2372ed4904a6/schema)