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

> Retrieve aggregate findings and per-step parsed results for a completed run.

# Get run results

## Top-level fields

* `aggregate`: Summary counters across the run
* `run_id`: Run UUID
* `status`: Terminal or in-progress run state
* `steps`: Per-tool parsed result payloads

## Aggregate fields

* `findings_by_severity`
* `risk_score`
* `total_findings`
* `unique_hosts`
* `unique_subdomains`

## Per-step fields

* `exit_code`
* `id`
* `status`
* `tool`
* `parsed_results`

`parsed_results` is tool-specific. In the `crt` runs tested for these docs, it contained:

* `tool`
* `type`
* `summary`
* `findings`

## Parser caveat

The current `crt` adapter did not fully clean its CLI output before building findings. Decorative table rows and one database recovery error line were surfaced as `finding.host` values during live testing. If you consume results programmatically, sanitize entries instead of assuming every `host` value is a valid hostname.

## Related schemas

* [RunResultsResponse](/rts-builder/schemas/run-results-response)
* [ErrorResponse](/rts-builder/schemas/error-response)


## OpenAPI

````yaml openapi/rts-builder.json GET /api/v1/external/results/{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/results/{runId}:
    get:
      tags:
        - Runs
      summary: Get run results
      description: >-
        Returns aggregate counters plus per-step parsed results for a run owned
        by the same tenant as the API key.
      operationId: getExternalRunResults
      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 results retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunResultsResponse'
              examples:
                completed:
                  summary: Observed result payload
                  value:
                    aggregate:
                      findings_by_severity:
                        critical: 0
                        high: 0
                        info: 6
                        low: 0
                        medium: 0
                      risk_score: 0
                      total_findings: 6
                      unique_hosts: 6
                      unique_subdomains: 6
                    run_id: 9bdeb4af-cab4-4de3-9f0f-758771d10991
                    status: completed
                    steps:
                      - exit_code: 0
                        id: 993af399-0e1a-456e-ba12-d465e7f9a5e6
                        status: completed
                        tool: crt
                        parsed_results:
                          tool: crt
                          type: ct_enumeration
                          summary:
                            total_subdomains: 6
                          findings:
                            - type: subdomain
                              severity: info
                              title: '| docs.techslayers.ca |'
                              detail: 'CT log subdomain: | docs.techslayers.ca |'
                              host: '| docs.techslayers.ca |'
                              port: 0
                              extra:
                                source: certificate_transparency
        '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:
    RunResultsResponse:
      type: object
      required:
        - aggregate
        - run_id
        - status
        - steps
      properties:
        aggregate:
          $ref: '#/components/schemas/AggregateSummary'
        run_id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/RunState'
        steps:
          type: array
          items:
            $ref: '#/components/schemas/RunResultStep'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
    AggregateSummary:
      type: object
      required:
        - findings_by_severity
        - risk_score
        - total_findings
        - unique_hosts
        - unique_subdomains
      properties:
        findings_by_severity:
          $ref: '#/components/schemas/SeverityCounts'
        risk_score:
          type: integer
          minimum: 0
        total_findings:
          type: integer
          minimum: 0
        unique_hosts:
          type: integer
          minimum: 0
        unique_subdomains:
          type: integer
          minimum: 0
    RunState:
      type: string
      enum:
        - pending
        - running
        - completed
        - failed
        - cancelled
    RunResultStep:
      type: object
      required:
        - exit_code
        - id
        - status
        - tool
        - parsed_results
      properties:
        exit_code:
          type: integer
        id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/RunState'
        tool:
          type: string
          example: crt
        parsed_results:
          $ref: '#/components/schemas/ParsedResults'
    SeverityCounts:
      type: object
      required:
        - critical
        - high
        - medium
        - low
        - info
      properties:
        critical:
          type: integer
          minimum: 0
        high:
          type: integer
          minimum: 0
        medium:
          type: integer
          minimum: 0
        low:
          type: integer
          minimum: 0
        info:
          type: integer
          minimum: 0
    ParsedResults:
      type: object
      description: >-
        Tool-specific parsed result envelope. The shape below reflects the
        live-tested `crt` adapter; other tools may return different fields
        inside `summary`, `findings`, or additional top-level keys.
      required:
        - tool
        - type
        - summary
        - findings
      properties:
        tool:
          type: string
        type:
          type: string
        summary:
          type: object
          additionalProperties: true
        findings:
          type: array
          items:
            $ref: '#/components/schemas/Finding'
    Finding:
      type: object
      required:
        - type
        - severity
        - title
        - detail
        - host
        - port
      properties:
        type:
          type: string
          example: subdomain
        severity:
          type: string
          example: info
        title:
          type: string
        detail:
          type: string
        host:
          type: string
        port:
          type: integer
          minimum: 0
        extra:
          type: object
          additionalProperties: true
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Team-scoped RTS Builder API key.

````