> ## Documentation Index > Fetch the complete documentation index at: https://docs.tester.army/llms.txt > Use this file to discover all available pages before exploring further. # List test runs > List test runs for the authenticated team with optional project/status filtering and cursor pagination. ## OpenAPI ````yaml /openapi.json get /v1/runs openapi: 3.0.0 info: title: TestArmy API version: 1.0.0 description: >- AI-powered browser automation API for QA testing. Automate web testing workflows using natural language prompts. servers: - url: https://tester.army/api description: Production API server security: [] paths: /v1/runs: get: tags: - Test Runs summary: List test runs description: >- List test runs for the authenticated team with optional project/status filtering and cursor pagination. parameters: - schema: type: string pattern: ^(?:[1-9]|[1-9][0-9]|100)$ description: Max results per page (default 20, max 100) required: false description: Max results per page (default 20, max 100) name: limit in: query - schema: type: string enum: - queued - running - completed - failed - cancelled description: Filter by status required: false description: Filter by status name: status in: query - schema: type: string format: uuid description: Filter by project ID required: false description: Filter by project ID name: projectId in: query - schema: type: string format: uuid description: Filter by test ID required: false description: Filter by test ID name: testId in: query - schema: type: string format: uuid description: Filter by group-run batch ID required: false description: Filter by group-run batch ID name: batchId in: query - schema: type: string description: Cursor for pagination required: false description: Cursor for pagination name: cursor in: query responses: '200': description: List of runs content: application/json: schema: $ref: '#/components/schemas/RunListResponse' '400': description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: error: type: string description: Error code or type message: type: string description: Human-readable error message required: - error - message '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: type: object properties: error: type: string description: Error code or type message: type: string description: Human-readable error message required: - error - message '429': description: Too Many Requests - Usage limit exceeded content: application/json: schema: type: object properties: error: type: string description: Error code or type message: type: string description: Human-readable error message required: - error - message '500': description: Internal Server Error content: application/json: schema: type: object properties: error: type: string description: Error code or type message: type: string description: Human-readable error message required: - error - message '504': description: Gateway Timeout - Test execution exceeded time limit content: application/json: schema: type: object properties: error: type: string description: Error code or type message: type: string description: Human-readable error message required: - error - message security: - bearerAuth: [] components: schemas: RunListResponse: type: object properties: runs: type: array items: $ref: '#/components/schemas/RunResponse' description: List of runs nextCursor: type: string nullable: true description: Cursor for fetching the next page required: - runs RunResponse: type: object properties: id: type: string format: uuid description: Unique run identifier type: type: string enum: - ci - test - discovery description: Run type status: type: string enum: - queued - running - completed - failed - cancelled description: Current run status platform: type: string nullable: true enum: - web - ios - android - null description: Target platform deviceModel: type: string nullable: true enum: - iphone - ipad - null description: >- 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: type: string nullable: true enum: - api - github_action - github_app - scheduled - webhook - structured_test - null description: Run source projectId: type: string nullable: true format: uuid description: Linked project ID input: type: object additionalProperties: nullable: true description: Original request input output: anyOf: - $ref: '#/components/schemas/TestOutput' - $ref: '#/components/schemas/PlannerSkippedOutput' - nullable: true description: Run output when completed or skipped testPlan: type: object nullable: true properties: instructions: type: string description: Natural language instructions for the QA agent focusAreas: type: array items: type: string description: Focus areas derived from changed files complexity: type: string enum: - simple - moderate - complex description: Estimated test complexity (affects timeout) changeType: type: string enum: - frontend - backend - mixed - infra description: >- 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: type: array items: oneOf: - type: object properties: title: type: string minLength: 1 maxLength: 500 description: Concise description of what to do or verify type: type: string enum: - act description: Perform an action required: - title - type - type: object properties: title: type: string minLength: 1 maxLength: 500 description: Concise description of what to do or verify type: type: string enum: - assert description: Verify a condition required: - title - type - type: object properties: title: type: string minLength: 1 maxLength: 500 description: Concise description of the login step type: type: string enum: - login description: Authenticate using a credential credentialId: type: string description: ID of the credential to use temporaryEmail: type: boolean description: >- Set to true to create a temporary email inbox at run time required: - title - type - type: object properties: title: type: string minLength: 1 maxLength: 500 description: Description of what page state to capture type: type: string enum: - screenshot description: Capture visual evidence of the current page state required: - title - type minItems: 1 maxItems: 10 description: >- Ordered list of concrete test steps the agent must execute one-by-one executionConfig: type: object properties: viewport: type: object properties: width: type: integer minimum: 320 maximum: 3840 height: type: integer minimum: 240 maximum: 2160 required: - width - height description: Pre-run execution configuration selected by the planner. required: - instructions - focusAreas - complexity - changeType - steps description: Generated test plan (CI runs only) error: type: object nullable: true properties: code: type: string description: Stable machine-readable error code message: type: string description: Human-readable error message stage: type: string description: >- Run lifecycle stage where the error occurred (e.g. provider_acquisition) retryable: type: boolean description: Whether re-running the test could succeed without changes required: - code - message description: Error details when failed durationMs: type: number nullable: true description: Execution time in milliseconds webhookUrl: type: string nullable: true format: uri description: Webhook delivery URL webhookStatus: type: string nullable: true enum: - pending - delivered - failed - null description: Webhook delivery status testId: type: string nullable: true format: uuid description: Linked test ID stepResults: type: array nullable: true items: $ref: '#/components/schemas/StepResult' description: Step-level results for structured test runs userName: type: string nullable: true description: Display name of the user who triggered the run externalRef: type: object nullable: true additionalProperties: nullable: true description: External integration metadata (e.g. GitHub PR/deployment IDs) executionMode: type: string nullable: true enum: - fast - deep - null description: Execution mode used for this run autoRetryCount: type: integer nullable: true description: >- Number of times the run was automatically retried after a temporary failure. Failed attempts are not counted toward usage. createdAt: type: string format: date-time description: When the run was created startedAt: type: string nullable: true format: date-time description: When execution started completedAt: type: string nullable: true format: date-time description: When execution finished required: - id - type - status - input - createdAt TestOutput: type: object properties: featureName: type: string description: Name of the feature being tested result: type: string enum: - PASS - FAILED - BLOCKED description: >- Test result - PASS if no issues found, FAILED if any issues were reported, BLOCKED if an environment/setup problem or an agent automation limit prevented a product verdict blockedReason: $ref: '#/components/schemas/BlockedReason' description: type: string description: >- 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: type: array items: $ref: '#/components/schemas/Issue' default: [] description: Issues reported during the session via the report_issue tool screenshots: type: array items: type: string description: Array of screenshot URLs captured during testing steps: type: array items: $ref: '#/components/schemas/TestOutputStep' description: Per-step summaries with timing information uiActionIntervals: type: array items: $ref: '#/components/schemas/UiActionInterval' description: >- Recording-time windows when the agent was visibly acting on screen (clicks, typing, scrolling, navigation); used by replay smart speed recording: type: object properties: storageKey: type: string description: Internal storage key of the recording artifact fileName: type: string description: Recording file name mediaType: type: string description: Recording media type (video/mp4) required: - storageKey - fileName - mediaType description: >- 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. required: - featureName - result - description - screenshots PlannerSkippedOutput: type: object properties: kind: type: string enum: - planner_skipped reason: type: string minLength: 1 maxLength: 2000 required: - kind - reason StepResult: type: object properties: stepIndex: type: integer description: Zero-based index of the saved test step status: type: string enum: - pending - running - passed - failed - skipped - cancelled description: Step execution status startedAt: type: string nullable: true description: ISO timestamp when the step started completedAt: type: string nullable: true description: ISO timestamp when the step completed error: type: string nullable: true description: Human-readable step failure description errorCode: type: string nullable: true enum: - 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 - null description: Machine-readable step failure code summary: type: string nullable: true description: Agent summary of what happened retried: type: boolean description: Whether the step was retried startedAtMs: type: integer nullable: true description: Milliseconds elapsed since recording reference when the step started completedAtMs: type: integer nullable: true description: >- Milliseconds elapsed since recording reference when the step completed required: - stepIndex - status - startedAt - completedAt - error - retried BlockedReason: type: object properties: category: type: string enum: - environment - seed_data - credentials - test_setup - automation description: >- Why the run was blocked: environment outage, missing seed data, or an agent automation limit summary: type: string description: Plain-language explanation of what blocked the run errorCodes: type: array items: type: string enum: - 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 description: Step error codes that produced the blocked verdict required: - category - summary - errorCodes description: Structured explanation, present only when result is BLOCKED Issue: type: object properties: type: type: string enum: - issue - warning default: issue description: issue = confirmed bug, warning = non-blocking observation name: type: string description: Short name of the issue (e.g. 'Login form rejects valid email') description: type: string description: What was tested, what happened, and what was expected url: type: string minLength: 1 maxLength: 2048 description: >- Where the issue happened: the exact page URL on web, or the app identifier and screen on mobile (e.g. com.example.app/login) severity: type: integer minimum: 1 maximum: 5 description: Issue severity from 1 (minor) to 5 (critical) reproductionSteps: type: array items: type: string description: Short reproduction steps in execution order expectedBehavior: type: string description: What should have happened actualBehavior: type: string description: What actually happened screenshotUrl: type: string description: Screenshot URL showing the issue tMs: type: integer description: >- Milliseconds elapsed since the recording reference time when the issue was reported accessibility: $ref: '#/components/schemas/IssueAccessibilityDetail' required: - name - description - url TestOutputStep: type: object properties: stepIndex: type: integer title: type: string type: type: string enum: - act - assert - login - files - screenshot - javascript - microphone status: type: string enum: - passed - failed summary: type: string error: type: string nullable: true errorCode: type: string enum: - 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: type: integer description: Milliseconds elapsed since recording reference when the step started completedAtMs: type: integer description: >- Milliseconds elapsed since recording reference when the step completed reusableActionTrace: $ref: '#/components/schemas/ReusableActionTrace' required: - stepIndex - title - status UiActionInterval: type: object properties: startMs: type: integer minimum: 0 description: >- Milliseconds elapsed since the recording reference time when the action began endMs: type: integer minimum: 0 description: >- Milliseconds elapsed since the recording reference time when the action finished kind: type: string enum: - click - type - scroll - navigate - other description: >- Coarse action category; absent on runs recorded before kinds were tracked required: - startMs - endMs IssueAccessibilityDetail: type: object properties: ruleId: type: string description: axe-core rule id, e.g. image-alt impact: type: string enum: - minor - moderate - serious - critical helpUrl: type: string description: Deque University fix-guidance URL wcagTags: type: array items: type: string description: axe rule tags (wcag2a, wcag21aa, ...) nodeCount: type: integer minimum: 0 description: Total failing nodes across pages pageCount: type: integer minimum: 0 description: >- Total distinct pages where the rule failed; `urls` is a bounded sample urls: type: array items: type: string description: Pages where the rule failed (bounded sample) sampleTargets: type: array items: type: string description: CSS selector paths to example failing elements (bounded sample) required: - ruleId - impact - helpUrl - wcagTags - nodeCount - urls - sampleTargets description: >- Structured detail present on warnings produced by the automated axe-core accessibility audit ReusableActionTrace: type: object properties: version: type: number enum: - 1 stepKey: type: string maxLength: 160 stepTitle: type: string maxLength: 200 stepType: type: string enum: - act - assert - login - files - screenshot - javascript - microphone actions: type: array items: $ref: '#/components/schemas/ReusableActionStep' minItems: 1 maxItems: 50 truncated: type: boolean description: >- Actions were dropped at a cap; the trace is guidance-only, never replayable startPath: type: string maxLength: 300 description: Pathname where the step began at record time startScreen: type: string maxLength: 120 description: >- Mobile: app under test (bundle id / package name) when the step began startScreenSignature: type: string maxLength: 32 description: >- Mobile: hashed structural signature of the starting screen (shadow data in v1) confidence: type: string enum: - medium - high required: - version - stepKey - stepTitle - actions - confidence ReusableActionStep: type: object properties: order: type: integer minimum: 0 toolName: type: string maxLength: 64 summary: type: string maxLength: 300 gap: type: boolean description: >- Placeholder for a tool the recorder saw run but did not capture (tool name only, no payload) - e.g. a file upload or a failed state-changing attempt. Gaps keep the trace honest about what actually happened: during cached replay, read-only gaps are skipped and state-changing gaps stop the replay so the agent performs that part live instead of it being silently skipped navigated: type: boolean description: >- The action changed the page URL at record time; replay keeps its full settle pipeline target: $ref: '#/components/schemas/ReusableActionTarget' source: allOf: - $ref: '#/components/schemas/ReusableActionTarget' - description: Drag-and-drop source endpoint, when the action has two targets input: type: object properties: url: type: string maxLength: 300 field: type: string enum: - username - password - totp option: type: string maxLength: 120 key: type: string maxLength: 60 direction: type: string enum: - up - down - left - right amount: type: integer deltaX: type: number deltaY: type: number targetPosition: type: string enum: - center - top - bottom - left - right focused: type: boolean sequentially: type: boolean text: type: string maxLength: 140 assertion: type: string maxLength: 300 role: type: string maxLength: 60 name: type: string maxLength: 120 durationMs: type: integer minimum: 0 exclusiveMinimum: true latitude: type: number longitude: type: number state: type: string enum: - offline - online required: - order - toolName - summary ReusableActionTarget: type: object properties: kind: type: string enum: - role - css - vision - focused - none - mobile role: type: string maxLength: 60 name: type: string maxLength: 120 nth: type: integer minimum: 0 selector: type: string maxLength: 240 element: type: string maxLength: 140 type: type: string maxLength: 80 description: >- Mobile: raw platform element class (XCUIElementTypeButton, android.widget.Button) identifier: type: string maxLength: 120 description: >- Mobile: platform identifier when the app sets one (AXUniqueId / resource-id) label: type: string maxLength: 120 description: >- Mobile: stable accessible label (labels mirroring a typed value are excluded) matchCount: type: integer minimum: 0 description: >- Mobile: same-signature match count at record time; relocation rejects when the live count differs required: - kind securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: API key authentication using Bearer token format ````