---
title: "List test runs"
method: GET
path: "/v1/runs"
tags: ["testRuns"]
---

# List test runs

`GET /v1/runs`

List test runs for the authenticated team with optional project/status filtering and cursor pagination.

## Query parameters

- `limit` string
- `status` 'queued' | 'running' | 'completed' | 'failed' | 'cancelled' — Filter by status
- `projectId` string, uuid
- `testId` string, uuid
- `batchId` string, uuid
- `cursor` string

## Headers

- `Authorization` string, required

## Response `200`

List of runs

- RunListResponse
  - `runs` RunResponse[], required — List of runs
    - `id` string, uuid, required — Unique run identifier
    - `type` 'ci' | 'test', required — Run type
    - `status` 'queued' | 'running' | 'completed' | 'failed' | 'cancelled', required — Current run status
    - `platform` 'web' | 'ios' | 'android' — Target platform
    - `deviceModel` 'iphone' | 'ipad' — Non-default mobile device variant within the run platform (e.g. ipad on iOS). Null means the platform default phone-sized device; explicitly requested defaults are stored as null.
    - `source` 'api' | 'github_action' | 'github_app' | 'scheduled' | 'webhook' | 'structured_test' — Run source
    - `projectId` string, uuid, nullable — Linked project ID
    - `input` object, required — Original request input
    - `output` union — Run output when completed or skipped
      - TestOutput
        - `featureName` string, required — Name of the feature being tested
        - `result` 'PASS' | 'FAILED' | 'BLOCKED', required — Test result - PASS if no issues found, FAILED if any issues were reported, BLOCKED if an environment or setup problem prevented a product verdict
        - `blockedReason` BlockedReason — Structured explanation, present only when result is BLOCKED
          - `category` 'environment' | 'seed_data' | 'credentials' | 'test_setup', required — Why the run was blocked: environment outage, missing seed data, etc.
          - `summary` string, required — Plain-language explanation of what blocked the run
          - `errorCodes` BlockedReasonErrorCodesItems[], required — Step error codes that produced the blocked verdict
        - `description` string, required — Short summary of what was tested and the final result; include a compact grouped issue summary only when the user explicitly asks for one
        - `issues` Issue[] — Issues reported during the session via the report_issue tool
          - `type` 'issue' | 'warning' — issue = confirmed bug, warning = non-blocking observation
          - `name` string, required — Short name of the issue (e.g. 'Login form rejects valid email')
          - `description` string, required — What was tested, what happened, and what was expected
          - `url` string, uri, required — URL where the issue happened
          - `severity` integer — Issue severity from 1 (minor) to 5 (critical)
          - `reproductionSteps` string[] — Short reproduction steps in execution order
          - `expectedBehavior` string — What should have happened
          - `actualBehavior` string — What actually happened
          - `screenshotUrl` string — Screenshot URL showing the issue
          - `tMs` integer — Milliseconds elapsed since the recording reference time when the issue was reported
        - `screenshots` string[], required — Array of screenshot URLs captured during testing
        - `steps` TestOutputStep[] — Per-step summaries with timing information
          - `stepIndex` integer, required
          - `title` string, required
          - `type` 'act' | 'assert' | 'login' | 'files' | 'screenshot' | 'javascript' | 'microphone'
          - `status` 'passed' | 'failed', required
          - `summary` string
          - `error` string, nullable
          - `errorCode` 'AUTH_CREDENTIAL_UNAVAILABLE' | 'AUTH_CREDENTIAL_INVALID' | 'AUTH_BASIC_REQUIRED' | 'VERCEL_BYPASS_REQUIRED' | 'ENVIRONMENT_UNAVAILABLE' | 'SEED_DATA_MISSING' | 'MOBILE_RELEASE_BUILD_REQUIRED' | 'VIEWPORT_RESIZE_UNSUPPORTED' | 'STEP_TOOL_LIMIT_EXHAUSTED' | 'STEP_DEADLINE_EXHAUSTED' | 'STEP_NO_CONCLUSION'
          - `startedAtMs` integer — Milliseconds elapsed since recording reference when the step started
          - `completedAtMs` integer — Milliseconds elapsed since recording reference when the step completed
          - `reusableActionTrace` ReusableActionTrace
            - `version` '1', required
            - `stepKey` string, required
            - `stepTitle` string, required
            - `stepType` 'act' | 'assert' | 'login' | 'files' | 'screenshot' | 'javascript' | 'microphone'
            - `actions` ReusableActionStep[], required
              - …
            - `confidence` 'medium' | 'high', required
        - `recording` TestOutputRecording — Pointer to the run's video recording artifact, present on completed runs that captured a recording. The bytes are not fetchable through the public API; use the dashboard or a share link to view the recording.
          - `storageKey` string, required — Internal storage key of the recording artifact
          - `fileName` string, required — Recording file name
          - `mediaType` string, required — Recording media type (video/mp4)
      - PlannerSkippedOutput
        - `kind` 'planner_skipped', required
        - `reason` string, required
      - unknown
    - `testPlan` RunResponseTestPlan — Generated test plan (CI runs only)
      - `instructions` string, required — Natural language instructions for the QA agent
      - `focusAreas` string[], required — Focus areas derived from changed files
      - `complexity` 'simple' | 'moderate' | 'complex', required — Estimated test complexity (affects timeout)
      - `changeType` 'frontend' | 'backend' | 'mixed' | 'infra', required — Classify this PR: frontend = UI/component changes, backend = API/DB/service changes with no visible UI effect, mixed = both, infra = CI/config/docs only
      - `steps` RunResponseTestPlanStepsItems[], required — Ordered list of concrete test steps the agent must execute one-by-one
        - union
          - RunResponseTestPlanStepsItems0
            - `title` string, required — Concise description of what to do or verify
            - `type` 'act', required — Perform an action
          - RunResponseTestPlanStepsItems1
            - `title` string, required — Concise description of what to do or verify
            - `type` 'assert', required — Verify a condition
          - RunResponseTestPlanStepsItems2
            - `title` string, required — Concise description of the login step
            - `type` 'login', required — Authenticate using a credential
            - `credentialId` string — ID of the credential to use
            - `temporaryEmail` boolean — Set to true to create a temporary email inbox at run time
          - RunResponseTestPlanStepsItems3
            - `title` string, required — Description of what page state to capture
            - `type` 'screenshot', required — Capture visual evidence of the current page state
      - `executionConfig` RunResponseTestPlanExecutionConfig — Pre-run execution configuration selected by the planner.
        - `viewport` RunResponseTestPlanExecutionConfigViewport
          - `width` integer, required
          - `height` integer, required
    - `error` RunResponseError — Error details when failed
      - `code` string, required — Stable machine-readable error code
      - `message` string, required — Human-readable error message
      - `stage` string — Run lifecycle stage where the error occurred (e.g. provider_acquisition)
      - `retryable` boolean — Whether re-running the test could succeed without changes
    - `durationMs` number, double, nullable — Execution time in milliseconds
    - `webhookUrl` string, uri, nullable — Webhook delivery URL
    - `webhookStatus` 'pending' | 'delivered' | 'failed' — Webhook delivery status
    - `testId` string, uuid, nullable — Linked test ID
    - `stepResults` StepResult[], nullable — Step-level results for structured test runs
      - `stepIndex` integer, required — Zero-based index of the saved test step
      - `status` 'pending' | 'running' | 'passed' | 'failed' | 'skipped' | 'cancelled', required — Step execution status
      - `startedAt` string, nullable, required — ISO timestamp when the step started
      - `completedAt` string, nullable, required — ISO timestamp when the step completed
      - `error` string, nullable, required — Human-readable step failure description
      - `errorCode` 'AUTH_CREDENTIAL_UNAVAILABLE' | 'AUTH_CREDENTIAL_INVALID' | 'AUTH_BASIC_REQUIRED' | 'VERCEL_BYPASS_REQUIRED' | 'ENVIRONMENT_UNAVAILABLE' | 'SEED_DATA_MISSING' | 'MOBILE_RELEASE_BUILD_REQUIRED' | 'VIEWPORT_RESIZE_UNSUPPORTED' | 'STEP_TOOL_LIMIT_EXHAUSTED' | 'STEP_DEADLINE_EXHAUSTED' | 'STEP_NO_CONCLUSION' — Machine-readable step failure code
      - `summary` string, nullable — Agent summary of what happened
      - `retried` boolean, required — Whether the step was retried
      - `startedAtMs` integer, nullable — Milliseconds elapsed since recording reference when the step started
      - `completedAtMs` integer, nullable — Milliseconds elapsed since recording reference when the step completed
    - `userName` string, nullable — Display name of the user who triggered the run
    - `externalRef` object, nullable — External integration metadata (e.g. GitHub PR/deployment IDs)
    - `executionMode` 'fast' | 'deep' — Execution mode used for this run
    - `autoRetryCount` integer, nullable — Number of times the run was automatically retried after a temporary failure. Failed attempts are not counted toward usage.
    - `createdAt` string, date-time, required — When the run was created
    - `startedAt` string, date-time, nullable — When execution started
    - `completedAt` string, date-time, nullable — When execution finished
  - `nextCursor` string, nullable — Cursor for fetching the next page

## Other responses

- `400` — Bad Request - Invalid input parameters
- `401` — Unauthorized - Invalid or missing API key
- `429` — Too Many Requests - Usage limit exceeded
- `500` — Internal Server Error
- `504` — Gateway Timeout - Test execution exceeded time limit

---

[API](https://skmtc.net/tester/apis/testerarmy-api.md) · [All operations](https://skmtc.net/tester/apis/testerarmy-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tester/testerarmy-api/versions/7fd19ca2a7fc/schema)