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

# Get run

> Requires the runs:read scope.

Accepts a scoped bearer token or interactive owner session.



## OpenAPI

````yaml /openapi.yaml get /api/v1/runs/{runId}
openapi: 3.1.0
info:
  title: Factorize API
  version: 1.0.0
  description: >-
    Versioned Factorize REST API. See the hosted docs for examples and OAuth
    discovery.
  x-dashboard-auth: >-
    Access-token and authorized-client management and trace replay operations
    require an interactive owner session; all other operations accept a suitably
    scoped bearer token or owner session.
servers:
  - url: https://app.factorize.sh
security:
  - bearerAuth: []
paths:
  /api/v1/runs/{runId}:
    get:
      tags:
        - runs
      summary: Get run
      description: |-
        Requires the runs:read scope.

        Accepts a scoped bearer token or interactive owner session.
      operationId: get_api_v1_runs_runId
      parameters:
        - name: runId
          in: path
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        '200':
          description: >-
            Run including durable execution diagnostics and harness artifact
            location
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunDetail'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
      security:
        - bearerAuth: []
components:
  schemas:
    RunDetail:
      allOf:
        - $ref: '#/components/schemas/Run'
      type: object
      required:
        - id
        - state
        - execution_diagnostics
        - harness_log
      properties:
        id:
          type: string
        state:
          type: string
        trace_generation:
          type:
            - string
            - 'null'
          description: >-
            Live file generation; clients reset trace pagination when it
            changes.
        trace_projection:
          $ref: '#/components/schemas/TraceProjection'
        trace_sources:
          $ref: '#/components/schemas/TraceSources'
        execution_diagnostics:
          $ref: '#/components/schemas/ExecutionDiagnostics'
        harness_log:
          $ref: '#/components/schemas/HarnessLog'
        artifact_error:
          type:
            - string
            - 'null'
          description: >-
            Secondary artifact or cleanup error; does not replace
            execution_diagnostics
        job_name:
          type: string
          description: >-
            Current job name, included so run content does not require a
            separate job request.
    Run:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
          description: Time the run was created and queued.
        started_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Time execution launch succeeded. Null until started or when unknown.
            Runtime starts here; the difference from created_at is queue time
            including launch preparation.
        updated_at:
          type: string
          format: date-time
          description: >-
            Last run update; used as the elapsed runtime endpoint for terminal
            runs.
    TraceProjection:
      type:
        - object
        - 'null'
      description: >-
        Committed projection receipt. Null means no durable reconciliation
        evidence; it does not mean complete.
      properties:
        source_kind:
          type: string
          enum:
            - execution_stream
            - native_session
        artifact_sha256:
          type: string
        parser_version:
          type: string
        updated_at:
          type: string
          format: date-time
        reconciliation:
          type: object
          properties:
            state:
              type: string
              enum:
                - matched
                - mismatch
                - no_live_cursor
                - reprojected
            events:
              type: integer
            liveEvents:
              type: integer
            mismatches:
              type: integer
            liveOffset:
              type:
                - integer
                - 'null'
            artifactBytes:
              type: integer
            generation:
              type:
                - string
                - 'null'
            codexCompletion:
              type: string
              enum:
                - turn.completed
                - missing_turn_completed
              description: >-
                Completion evidence from the exact retained canonical Codex
                bytes.
    TraceSources:
      type:
        - object
        - 'null'
      properties:
        primary:
          $ref: '#/components/schemas/TraceSource'
        nativeSession:
          $ref: '#/components/schemas/TraceSource'
    ExecutionDiagnostics:
      type:
        - object
        - 'null'
      description: >-
        First terminal backend observation, retained independently of collection
        and cleanup errors. Null for older or nonterminal runs. Commands and raw
        backend responses are never included.
      required:
        - state
        - detail
        - systemd
      properties:
        state:
          type: string
          enum:
            - succeeded
            - failed
            - stopped
        detail:
          type:
            - string
            - 'null'
          maxLength: 2048
          description: Bounded credential-redacted backend observation detail
        systemd:
          type:
            - object
            - 'null'
          required:
            - loadState
            - activeState
            - subState
            - result
            - execMainCode
            - execMainStatus
          properties:
            loadState:
              type: string
              maxLength: 64
            activeState:
              type: string
              maxLength: 64
            subState:
              type: string
              maxLength: 64
            result:
              type: string
              maxLength: 64
            execMainCode:
              type:
                - integer
                - 'null'
              description: systemd ExecMainCode (for example 1 for exit and 2 for signal)
            execMainStatus:
              type:
                - integer
                - 'null'
              description: systemd exit status or signal number; null if unavailable
    HarnessLog:
      type:
        - object
        - 'null'
      description: >-
        Stored redacted harness stderr artifact, or null if unavailable. Uses
        the combined log for older VMs. Retains at most the first 64 KiB, drops
        a truncated final line, and redacts recognizable credentials before
        storage. The object key is a storage locator, not a public or signed
        URL. This artifact remains available after VM deletion.
      required:
        - id
        - kind
        - object_key
        - provider
        - format
        - byte_size
        - sha256
        - state
        - created_at
      properties:
        id:
          type: string
        kind:
          type: string
          const: terminal_log
        object_key:
          type: string
        provider:
          type: string
        format:
          type: string
          const: text
        format_version:
          type:
            - string
            - 'null'
        cli_version:
          type:
            - string
            - 'null'
        source_generation:
          type:
            - string
            - 'null'
          description: >-
            Live source generation bound to the terminal snapshot; unknown for
            historical receipts.
        native_session_id:
          type:
            - string
            - 'null'
        byte_size:
          type:
            - integer
            - string
          description: Byte count (PostgreSQL bigint may serialize as a decimal string)
          maximum: 65536
        sha256:
          type: string
          pattern: ^[a-f0-9]{64}$
        state:
          type: string
          enum:
            - stored
        created_at:
          type: string
          format: date-time
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
    TraceSource:
      type: object
      required:
        - kind
        - path
        - mediaType
        - provider
      properties:
        kind:
          type: string
          enum:
            - execution_stream
            - native_session
        path:
          type: string
          description: >-
            Guest source path; historical native sources may use a discovery
            root
        mediaType:
          type: string
          const: application/x-ndjson
        provider:
          type: string
          enum:
            - codex
            - claude
            - pi
        formatVersion:
          type: string
        cliVersion:
          type: string
        harnessVersion:
          type: string
        discoverCommand:
          type: string
          description: Native session discovery only
  responses:
    Error400:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error401:
      description: Invalid or revoked credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error403:
      description: Missing scope or required owner session
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error404:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error409:
      description: Operation conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error429:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error500:
      description: Internal error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error503:
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: OAuth2

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.