> ## 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.

# Get batch status

> Retrieve the aggregate status of a group-run batch with per-run verdicts. Poll this endpoint to track batch completion, then fetch individual runs (or `GET /v1/runs?batchId=...`) for details.



## OpenAPI

````yaml /openapi.json get /v1/batches/{batchId}
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/batches/{batchId}:
    get:
      tags:
        - Test Runs
      summary: Get batch status
      description: >-
        Retrieve the aggregate status of a group-run batch with per-run
        verdicts. Poll this endpoint to track batch completion, then fetch
        individual runs (or `GET /v1/runs?batchId=...`) for details.
      parameters:
        - schema:
            type: string
            format: uuid
            description: Batch ID
          required: true
          description: Batch ID
          name: batchId
          in: path
      responses:
        '200':
          description: Batch status summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatusResponse'
        '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
        '404':
          description: Batch not found
          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:
    BatchStatusResponse:
      type: object
      properties:
        batchId:
          type: string
          format: uuid
          description: Batch ID
        status:
          type: string
          enum:
            - queued
            - running
            - completed
            - failed
            - cancelled
          description: >-
            Aggregate batch status: running while any run is in flight, failed
            when any finished run failed, completed when all finished runs
            passed, cancelled when every run was cancelled
        counts:
          type: object
          properties:
            total:
              type: integer
              minimum: 0
            queued:
              type: integer
              minimum: 0
            running:
              type: integer
              minimum: 0
            completed:
              type: integer
              minimum: 0
            failed:
              type: integer
              minimum: 0
            cancelled:
              type: integer
              minimum: 0
          required:
            - total
            - queued
            - running
            - completed
            - failed
            - cancelled
          description: Run counts by status
        runs:
          type: array
          items:
            $ref: '#/components/schemas/BatchStatusRun'
          description: Child runs ordered by creation time
      required:
        - batchId
        - status
        - counts
        - runs
    BatchStatusRun:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Run ID
        testId:
          type: string
          nullable: true
          format: uuid
          description: Saved test the run executed
        status:
          type: string
          enum:
            - queued
            - running
            - completed
            - failed
            - cancelled
          description: Run status
        result:
          type: string
          nullable: true
          enum:
            - PASS
            - FAILED
            - BLOCKED
            - null
          description: >-
            Test verdict when the run finished with an output. BLOCKED means an
            environment or setup problem prevented a product verdict
        errorCode:
          type: string
          nullable: true
          description: Run error code when execution failed
        durationMs:
          type: integer
          nullable: true
          description: Execution time in milliseconds
        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
        - testId
        - status
        - result
        - errorCode
        - durationMs
        - createdAt
        - startedAt
        - completedAt
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key authentication using Bearer token format

````