> ## Documentation Index
> Fetch the complete documentation index at: https://docs.techslayers.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# Get run status

> Fetch status, timestamps, and step state for a run ID.

# Get run status

## Status transitions

Observed values:

* `pending`
* `running`
* `completed`

Internal run pages also account for `failed` and `cancelled`, and callers should handle those states as well.

## Related schemas

* [RunStatusResponse](/rts-builder/schemas/run-status-response)
* [ErrorResponse](/rts-builder/schemas/error-response)


## OpenAPI

````yaml openapi/rts-builder.json GET /api/v1/external/status/{runId}
openapi: 3.0.3
info:
  title: RTS Builder External API
  version: '2026-03-29'
  description: >-
    Public API for listing externally accessible RTS Builder kits, starting
    runs, polling run status, and retrieving parsed results. Verified against
    the live service on March 28, 2026 Pacific / March 29, 2026 UTC. The 201
    response for POST /api/v1/external/{kitSlug} is inferred from the internally
    verified builder run endpoint because external start access returned 403
    during live testing.
servers:
  - url: https://rts-builder.slayers.tech
    description: RTS Builder production
security:
  - ApiKeyAuth: []
tags:
  - name: External Kits
    description: Kit discovery and run creation.
  - name: Runs
    description: Run lifecycle and result retrieval.
paths:
  /api/v1/external/status/{runId}:
    get:
      tags:
        - Runs
      summary: Get run status
      description: >-
        Returns top-level run state plus per-step status for a run owned by the
        same tenant as the API key.
      operationId: getExternalRunStatus
      parameters:
        - name: runId
          in: path
          required: true
          description: Run UUID.
          schema:
            type: string
            format: uuid
            example: 9bdeb4af-cab4-4de3-9f0f-758771d10991
      responses:
        '200':
          description: Run status retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunStatusResponse'
              examples:
                completed:
                  summary: Observed completed run status
                  value:
                    error: ''
                    finished_at: '2026-03-29T02:33:41.139079Z'
                    run_id: 9bdeb4af-cab4-4de3-9f0f-758771d10991
                    started_at: '2026-03-29T02:32:54.167691Z'
                    status: completed
                    steps:
                      - id: 993af399-0e1a-456e-ba12-d465e7f9a5e6
                        node_id: tool-1
                        tool: crt
                        status: completed
                        exit_code: 0
        '400':
          description: Run ID format is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidRunId:
                  value:
                    error: invalid run ID
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingHeader:
                  value:
                    error: missing X-API-Key header
                invalidKey:
                  value:
                    error: invalid API key
        '404':
          description: Run UUID was valid but not visible to the caller's tenant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  value:
                    error: run not found
components:
  schemas:
    RunStatusResponse:
      type: object
      required:
        - error
        - run_id
        - status
        - steps
      properties:
        error:
          type: string
          description: Empty string on success.
        finished_at:
          type: string
          format: date-time
          nullable: true
        run_id:
          type: string
          format: uuid
        started_at:
          type: string
          format: date-time
          nullable: true
        status:
          $ref: '#/components/schemas/RunState'
        steps:
          type: array
          items:
            $ref: '#/components/schemas/RunStatusStep'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
    RunState:
      type: string
      enum:
        - pending
        - running
        - completed
        - failed
        - cancelled
    RunStatusStep:
      type: object
      required:
        - id
        - node_id
        - tool
        - status
        - exit_code
      properties:
        id:
          type: string
          format: uuid
        node_id:
          type: string
          example: tool-1
        tool:
          type: string
          example: crt
        status:
          $ref: '#/components/schemas/RunState'
        exit_code:
          type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Team-scoped RTS Builder API key.

````