---
title: "Get test run status"
method: GET
path: "/v1/runs/{id}"
tags: ["testRuns"]
---

# Get test run status

`GET /v1/runs/{id}`

Retrieve the current status and result of a test run. Poll this endpoint to check for completion.

## Path parameters

- `id` string, uuid, required

## Headers

- `Authorization` string, required

## Response `200`

Run details

- RunResponse
  - `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
            - `order` integer, required
            - `toolName` string, required
            - `summary` string, required
            - `target` ReusableActionTarget
              - …
            - `input` ReusableActionStepInput
              - …
          - `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

## Other responses

- `400` — Bad Request - Invalid input parameters
- `401` — Unauthorized - Invalid or missing API key
- `404` — Run not found
- `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)