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

# Fetch the canonical analysis input for a completed session

> Returns the ``SessionAnalysisInput`` shape defined in
``src/knowledge_gap/analysis_schemas.py``.

- ``404`` — session not found, or owned by a different organization.
- ``409`` — session is not in a terminal state (still active /
  paused / waiting for human / etc.). The analyzer should only be run
  on completed sessions.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/sessions/{session_id}/analysis-input
openapi: 3.1.0
info:
  title: Feather API
  description: >-
    Unified customer experience platform API. Manages identity, conversations,
    memory, agents, procedures, policies, model routing, knowledge bases,
    integrations, and runtime execution.
  version: 1.21.0
servers:
  - url: https://api-sandbox.featherhq.com
    description: Sandbox
  - url: http://localhost:8000
    description: Local dev
security: []
paths:
  /v1/sessions/{session_id}/analysis-input:
    get:
      tags:
        - sessions
      summary: Fetch the canonical analysis input for a completed session
      description: |-
        Returns the ``SessionAnalysisInput`` shape defined in
        ``src/knowledge_gap/analysis_schemas.py``.

        - ``404`` — session not found, or owned by a different organization.
        - ``409`` — session is not in a terminal state (still active /
          paused / waiting for human / etc.). The analyzer should only be run
          on completed sessions.
      operationId: getSessionAnalysisInput
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionAnalysisInput'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    SessionAnalysisInput:
      properties:
        analyzer_input_schema_version:
          type: integer
          title: Analyzer Input Schema Version
          default: 2
        session_id:
          type: string
          format: uuid
          title: Session Id
        organization_id:
          type: string
          format: uuid
          title: Organization Id
        agent_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Agent Id
        channel:
          type: string
          title: Channel
        started_at:
          type: string
          format: date-time
          title: Started At
        ended_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Ended At
        completion_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Completion Reason
        knowledge_gap_analysis_outcome:
          anyOf:
            - $ref: '#/components/schemas/KnowledgeGapAnalysisOutcome'
            - type: 'null'
        messages:
          items:
            $ref: '#/components/schemas/MessageEntry'
          type: array
          title: Messages
        rag_traces:
          items:
            $ref: '#/components/schemas/RagTraceEntry'
          type: array
          title: Rag Traces
        citations:
          items:
            $ref: '#/components/schemas/CitedChunk'
          type: array
          title: Citations
        tool_calls:
          items:
            $ref: '#/components/schemas/ToolCallEntry'
          type: array
          title: Tool Calls
        handoff_events:
          items:
            $ref: '#/components/schemas/HandoffEvent'
          type: array
          title: Handoff Events
        kb_snapshot:
          anyOf:
            - $ref: '#/components/schemas/KbSnapshotEntry'
            - type: 'null'
        user_feedback:
          anyOf:
            - $ref: '#/components/schemas/FeedbackEntry'
            - type: 'null'
        csat:
          anyOf:
            - $ref: '#/components/schemas/CSATEntry'
            - type: 'null'
        reopen:
          anyOf:
            - $ref: '#/components/schemas/ReopenEntry'
            - type: 'null'
        customer_metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Customer Metadata
        missing_evidence_reasons:
          items:
            $ref: '#/components/schemas/MissingEvidenceReason'
          type: array
          title: Missing Evidence Reasons
      type: object
      required:
        - session_id
        - organization_id
        - agent_id
        - channel
        - started_at
        - ended_at
        - completion_reason
        - knowledge_gap_analysis_outcome
      title: SessionAnalysisInput
      description: |-
        Canonical analyzer input built from one completed session.

        Required fields are populated for every analysed completed session.
        Conditionally-required fields populate when the corresponding capture
        succeeded (e.g., ``rag_traces`` when retrieval ran). Nullable enrichment
        fields are best-effort.

        Consumers should consult ``missing_evidence_reasons`` before attempting
        evidence-backed classifications.
    ErrorResponse:
      properties:
        error:
          type: string
          title: Error
        message:
          type: string
          title: Message
      type: object
      required:
        - error
        - message
      title: ErrorResponse
      description: Standard error response returned by all API error handlers.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    KnowledgeGapAnalysisOutcome:
      type: string
      enum:
        - resolved
        - unresolved
        - transferred
        - expired
        - error
        - abandoned
        - voicemail
        - escalated
        - call_failed
      title: KnowledgeGapAnalysisOutcome
      description: |-
        Canonical, analyzer-friendly outcome of a completed session.

        Derived from ``(SessionStatus, SessionTerminationReason)`` at close time
        and persisted on ``ConvSessionMeta.knowledge_gap_analysis_outcome``.
        Free-form ``termination_reason`` is preserved alongside for forensic
        detail.
    MessageEntry:
      properties:
        turn_id:
          type: string
          format: uuid
          title: Turn Id
        role:
          type: string
          title: Role
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        content:
          type: string
          title: Content
        tool_calls:
          anyOf:
            - items:
                $ref: '#/components/schemas/ToolCall'
              type: array
            - type: 'null'
          title: Tool Calls
        tool_results:
          anyOf:
            - $ref: '#/components/schemas/ToolResult'
            - type: 'null'
        model_used:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Used
        latency_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Latency Ms
        truncated:
          type: boolean
          title: Truncated
          default: false
        original_char_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Original Char Count
      type: object
      required:
        - turn_id
        - role
        - timestamp
        - content
      title: MessageEntry
      description: One redacted message in the transcript view of a session.
    RagTraceEntry:
      properties:
        rag_query_id:
          type: string
          format: uuid
          title: Rag Query Id
        assistant_turn_id:
          type: string
          format: uuid
          title: Assistant Turn Id
        query_hash:
          anyOf:
            - type: string
            - type: 'null'
          title: Query Hash
        kb_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Kb Ids
        retrieved:
          items:
            $ref: '#/components/schemas/RetrievedChunk'
          type: array
          title: Retrieved
        top_score:
          anyOf:
            - type: number
            - type: 'null'
          title: Top Score
        hit:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Hit
        latency_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Latency Ms
        answerability:
          anyOf:
            - $ref: '#/components/schemas/RagTraceAnswerability'
            - type: 'null'
      type: object
      required:
        - rag_query_id
        - assistant_turn_id
      title: RagTraceEntry
      description: One retrieval that fed a specific assistant turn.
    CitedChunk:
      properties:
        assistant_turn_id:
          type: string
          format: uuid
          title: Assistant Turn Id
        kb_id:
          type: string
          format: uuid
          title: Kb Id
        doc_id:
          type: string
          title: Doc Id
        chunk_id:
          type: string
          title: Chunk Id
        version_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Version Id
      type: object
      required:
        - assistant_turn_id
        - kb_id
        - doc_id
        - chunk_id
      title: CitedChunk
      description: >-
        One chunk that the runtime exposed to the LLM (subset of retrieved).


        ``assistant_turn_id`` ties each citation back to the assistant turn that

        cited it. Required: the producer always has the turn in scope when

        building citations, and downstream stages (ENG-491 retrieval validation,

        ENG-490 ``ClaimEvidenceRef`` widening) need the per-turn linkage to
        scope

        doc-id subset constraints to a candidate's evidence_turn_ids.
    ToolCallEntry:
      properties:
        tool_call_id:
          type: string
          title: Tool Call Id
        assistant_turn_id:
          type: string
          format: uuid
          title: Assistant Turn Id
        name:
          type: string
          title: Name
        arguments:
          type: string
          title: Arguments
        arguments_parsed:
          anyOf:
            - {}
            - type: 'null'
          title: Arguments Parsed
        result:
          anyOf:
            - type: string
            - type: 'null'
          title: Result
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        latency_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Latency Ms
      type: object
      required:
        - tool_call_id
        - assistant_turn_id
        - name
        - arguments
      title: ToolCallEntry
      description: One tool invocation in the session.
    HandoffEvent:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        transferred_to_agent_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Transferred To Agent Id
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
      type: object
      required:
        - timestamp
      title: HandoffEvent
      description: Human handoff transition recorded against the session.
    KbSnapshotEntry:
      properties:
        captured_at:
          type: string
          format: date-time
          title: Captured At
        kb_versions:
          additionalProperties:
            type: integer
          propertyNames:
            format: uuid
          type: object
          title: Kb Versions
      type: object
      required:
        - captured_at
      title: KbSnapshotEntry
      description: |-
        KB state captured at the moment of the session's first retrieval.

        Maps each KB used in the session to the active document-version count
        (as a coarse fingerprint of "what was the KB at the time"). The
        fine-grained per-doc version of a retrieved chunk is on
        ``RetrievedChunk.version_id``.
    FeedbackEntry:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        rating:
          anyOf:
            - type: integer
            - type: 'null'
          title: Rating
        comment:
          anyOf:
            - type: string
            - type: 'null'
          title: Comment
      type: object
      required:
        - timestamp
      title: FeedbackEntry
      description: |-
        Free-form user feedback against a session.

        Nullable in v1 — no capture surface yet. Shape is reserved so downstream
        consumers can plan against it.
    CSATEntry:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        score:
          type: integer
          title: Score
        scale_max:
          type: integer
          title: Scale Max
          default: 5
      type: object
      required:
        - timestamp
        - score
      title: CSATEntry
      description: CSAT score against a session. Nullable in v1 (no capture surface).
    ReopenEntry:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
      type: object
      required:
        - timestamp
      title: ReopenEntry
      description: Ticket reopen event. Nullable in v1 (no capture surface).
    MissingEvidenceReason:
      type: string
      enum:
        - no_rag_trace
        - no_kb_snapshot
        - no_citations
        - no_tool_trace
        - no_csat
        - no_user_feedback
        - transcript_redaction_skipped
        - legacy_session
      title: MissingEvidenceReason
      description: |-
        Why a downstream classification may need to lower confidence or skip.

        Recorded on ``SessionAnalysisInput.missing_evidence_reasons`` by the
        assembler when expected traces are unavailable. Analyzer code consults
        this list to decide whether to attempt evidence-backed classifications.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ToolCall:
      properties:
        id:
          type: string
          title: Id
        type:
          type: string
          title: Type
          default: function
        function:
          $ref: '#/components/schemas/ToolCallFunction'
      type: object
      required:
        - id
        - function
      title: ToolCall
    ToolResult:
      properties:
        tool_call_id:
          type: string
          title: Tool Call Id
        output:
          type: string
          title: Output
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
      type: object
      required:
        - tool_call_id
        - output
      title: ToolResult
    RetrievedChunk:
      properties:
        chunk_id:
          type: string
          title: Chunk Id
        doc_id:
          type: string
          title: Doc Id
        version_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Version Id
        score:
          anyOf:
            - type: number
            - type: 'null'
          title: Score
      type: object
      required:
        - chunk_id
        - doc_id
      title: RetrievedChunk
      description: One chunk returned by a retrieval call.
    RagTraceAnswerability:
      properties:
        label:
          anyOf:
            - type: string
            - type: 'null'
          title: Label
        reason_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason Code
        raw_top_score:
          anyOf:
            - type: number
            - type: 'null'
          title: Raw Top Score
        score_basis:
          anyOf:
            - type: string
            - type: 'null'
          title: Score Basis
        mode:
          anyOf:
            - type: string
            - type: 'null'
          title: Mode
        action:
          anyOf:
            - type: string
            - type: 'null'
          title: Action
        threshold_low:
          anyOf:
            - type: number
            - type: 'null'
          title: Threshold Low
        threshold_high:
          anyOf:
            - type: number
            - type: 'null'
          title: Threshold High
      type: object
      title: RagTraceAnswerability
      description: >-
        Answerability verdict subset persisted on a RAG trace (ENG-671/672).


        Present only when the gate ran (mode shadow/enforce); legacy / off-mode

        traces leave :attr:`RagTraceEntry.answerability` ``None``. Every field
        is

        optional so a partial or older JSONB payload coerces rather than
        raising.

        ``raw_top_score`` is the pre-normalization top score the retro
        retrieval-

        failure detector prefers over the display ``top_score``.
    ToolCallFunction:
      properties:
        name:
          type: string
          title: Name
        arguments:
          type: string
          title: Arguments
      type: object
      required:
        - name
        - arguments
      title: ToolCallFunction
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key

````