> ## 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 credential-safe run lifecycle diagnostics

> Requires the runs:read scope.

Accepts a scoped bearer token or interactive owner session.



## OpenAPI

````yaml /openapi.yaml get /api/v1/runs/{runId}/diagnostics
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}/diagnostics:
    get:
      tags:
        - runs
      summary: Get credential-safe run lifecycle diagnostics
      description: |-
        Requires the runs:read scope.

        Accepts a scoped bearer token or interactive owner session.
      operationId: get_api_v1_runs_runId_diagnostics
      parameters:
        - name: runId
          in: path
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        '200':
          description: >-
            Credential-safe execution metadata and durable harness artifact
            location
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunDiagnostics'
        '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:
    RunDiagnostics:
      type: object
      required:
        - runId
        - jobId
        - state
        - execution
        - harnessLog
        - artifact
        - activity
      properties:
        runId:
          type: string
        jobId:
          type: string
        state:
          type: string
        provider:
          type: string
        backendKind:
          type: string
        trace:
          $ref: '#/components/schemas/TraceDiagnostics'
        traceSources:
          $ref: '#/components/schemas/TraceSources'
        execution:
          $ref: '#/components/schemas/ExecutionDiagnostics'
        harnessLog:
          $ref: '#/components/schemas/HarnessLog'
        artifact:
          type: object
          properties:
            state:
              type: string
            error:
              type:
                - string
                - 'null'
              description: >-
                Secondary collection or cleanup error. Collection is retried up
                to three times before cleanup proceeds with partial artifacts.
                Cleanup failures remain retryable.
        activity:
          type: array
          items:
            type: object
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    TraceDiagnostics:
      type: object
      required:
        - provider
        - primarySource
        - sourceVersion
        - projection
        - liveCursor
        - counts
        - artifacts
        - nativeArtifactState
        - fallbackUsed
        - lastReplay
      properties:
        provider:
          type:
            - string
            - 'null'
          description: >-
            Agent trace provider; the outer diagnostics provider remains the
            trigger provider.
        primarySource:
          type: string
          enum:
            - execution_stream
            - native_session
        sourceVersion:
          type:
            - string
            - 'null'
        projection:
          $ref: '#/components/schemas/TraceProjection'
        liveCursor:
          type:
            - object
            - 'null'
          properties:
            generation:
              type: string
            committed_offset:
              type:
                - integer
                - string
            pending_bytes:
              type: integer
            updated_at:
              type: string
              format: date-time
        counts:
          type: object
          properties:
            events:
              type: integer
            parse_warnings:
              type: integer
            unknown_events:
              type: integer
            unknownEventRate:
              type: number
              minimum: 0
              maximum: 1
        artifacts:
          type: array
          description: >-
            Tenant/run-scoped receipts; storage keys are locators, never public
            download URLs. Includes kind, provider, source_path,
            source_generation, format and source/CLI/harness versions, byte
            size, checksum and storage state.
          items:
            type: object
        nativeArtifactState:
          type: string
          enum:
            - stored
            - missing
            - not_applicable
          description: >-
            Canonical Codex runs do not capture native sessions. Historical
            native receipts remain readable.
        fallbackUsed:
          type: boolean
          description: >-
            Native projection selected for a run originally declared with an
            execution stream primary.
        lastReplay:
          type:
            - object
            - 'null'
          description: Latest completed replay request ID
          source: null
          result: null
          and timestamp; failed requests are retryable and logged.: null
    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
    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.
    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.