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

# Get the customer-readable trace for a v2 conversation, nested Session→Turn→node→step

> The nested tree variant of the session trace (Phase D), paginated by TURN. Same auth
(TRACE_READ) + org scoping + terminal-session cache as the flat read. The full tree is built +
cached once, then a window of ``limit`` turns from ``cursor`` is returned with a ``next_cursor``
for the next block (``None`` on the last page). ``header`` + session lane ride every page.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/conversations/{conversation_id}/trace/grouped
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.87.0
servers:
  - url: https://api-sandbox.featherhq.com
    description: Sandbox
  - url: http://localhost:8000
    description: Local dev
security: []
paths:
  /v1/conversations/{conversation_id}/trace/grouped:
    get:
      tags:
        - conversations
      summary: >-
        Get the customer-readable trace for a v2 conversation, nested
        Session→Turn→node→step
      description: >-
        The nested tree variant of the session trace (Phase D), paginated by
        TURN. Same auth

        (TRACE_READ) + org scoping + terminal-session cache as the flat read.
        The full tree is built +

        cached once, then a window of ``limit`` turns from ``cursor`` is
        returned with a ``next_cursor``

        for the next block (``None`` on the last page). ``header`` + session
        lane ride every page.
      operationId: getV2ConversationTraceGrouped
      parameters:
        - name: conversation_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Conversation Id
        - name: turn_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: 'null'
            title: Turn Id
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Turn-pagination cursor: pass the previous page's ``next_cursor``
              to load the next block of turns. Omit for the first page.
            title: Cursor
          description: >-
            Turn-pagination cursor: pass the previous page's ``next_cursor`` to
            load the next block of turns. Omit for the first page.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 200
            minimum: 1
            description: >-
              Max TURNS per page (the grouped tree paginates by turn, not by raw
              step).
            default: 25
            title: Limit
          description: >-
            Max TURNS per page (the grouped tree paginates by turn, not by raw
            step).
        - name: category
          in: query
          required: false
          schema:
            enum:
              - product
              - engineering
              - all
            type: string
            default: product
            title: Category
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionTraceGroupedResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    SessionTraceGroupedResponse:
      properties:
        header:
          anyOf:
            - $ref: '#/components/schemas/TraceSessionHeader'
            - type: 'null'
        session:
          items:
            $ref: '#/components/schemas/TraceStep'
          type: array
          title: Session
        turns:
          items:
            $ref: '#/components/schemas/TraceTurn'
          type: array
          title: Turns
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
      additionalProperties: false
      type: object
      required:
        - session
        - turns
      title: SessionTraceGroupedResponse
      description: >-
        Nested envelope (Phase D): Session → Turn → node → step.


        ``header`` holds the session-level facts (who / channel / agent /
        outcome / memory) shown once.

        ``session`` holds any remaining session-lane steps not folded into the
        header. ``turns`` holds

        the per-turn trees, ordered by turn start. A read alternative to the
        flat

        :class:`SessionTraceResponse`; the flat shape stays for back-compat.
    ErrorResponse:
      properties:
        error:
          type: string
          title: Error
        message:
          type: string
          title: Message
        retryable:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Retryable
        retry_after:
          anyOf:
            - type: integer
            - type: 'null'
          title: Retry After
      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
    TraceSessionHeader:
      properties:
        channel:
          anyOf:
            - type: string
            - type: 'null'
          title: Channel
        customer:
          anyOf:
            - type: string
            - type: 'null'
          title: Customer
        agent:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started At
        ended_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Ended At
        outcome:
          anyOf:
            - type: string
            - type: 'null'
          title: Outcome
        memory:
          anyOf:
            - type: string
            - type: 'null'
          title: Memory
      additionalProperties: false
      type: object
      title: TraceSessionHeader
      description: >-
        Session-level facts shown ONCE at the top of the trace (never repeated
        per turn).


        Derived from the conversation row + the session-lane steps, so the
        timeline opens with a single

        'who / what / outcome' block instead of burying identity / memory /
        start / end events inside

        the turn stream.
    TraceStep:
      properties:
        kind:
          type: string
          title: Kind
        actor:
          type: string
          enum:
            - Customer
            - Agent
            - System
          title: Actor
        title:
          type: string
          title: Title
        summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Summary
        status:
          type: string
          enum:
            - Succeeded
            - Failed
            - Skipped
            - In Progress
          title: Status
        started_at:
          type: string
          format: date-time
          title: Started At
        ended_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Ended At
        duration_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Duration Ms
        turn_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Turn Id
        details:
          additionalProperties: true
          type: object
          title: Details
      additionalProperties: false
      type: object
      required:
        - kind
        - actor
        - title
        - status
        - started_at
      title: TraceStep
      description: One row in the customer-readable session trace.
    TraceTurn:
      properties:
        turn_id:
          type: string
          title: Turn Id
        started_at:
          type: string
          format: date-time
          title: Started At
        customer_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Customer Message
        ttft_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Ttft Ms
        duration_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Duration Ms
        groups:
          items:
            $ref: '#/components/schemas/TraceNodeGroup'
          type: array
          title: Groups
      additionalProperties: false
      type: object
      required:
        - turn_id
        - started_at
        - groups
      title: TraceTurn
      description: >-
        One turn's steps, ordered chronologically and clustered into node
        sub-groups (Phase D).


        ``customer_message`` is the inbound message that opened the turn
        (surfaced in the turn HEADER

        rather than as a step). ``ttft_ms`` (time to the model's first token)
        and ``duration_ms`` (the

        turn's total end-to-end duration) are the two per-turn latencies — both
        surfaced in the header

        rather than as a standalone Turn Latency step — so the timeline reads

        ``Turn N · Customer: "…" · first token 0.4s · 1.2s`` above the work the
        agent did. Both are

        reported on EVERY channel (text via the product projector, voice via the
        live latency observer),

        so the frontend renders one shape regardless of channel.
    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
    TraceNodeGroup:
      properties:
        node:
          anyOf:
            - type: string
            - type: 'null'
          title: Node
        steps:
          items:
            $ref: '#/components/schemas/TraceStep'
          type: array
          title: Steps
      additionalProperties: false
      type: object
      required:
        - steps
      title: TraceNodeGroup
      description: >-
        A node-level sub-group within a turn (Phase D): a run of consecutive
        steps that share the

        same enclosing workflow node, so a multi-node turn reads as a tree
        instead of a flat list.


        ``node`` is the resolved node label (from the step's ``customer.step``
        detail) or ``None`` for

        turn-level steps with no enclosing node (a plain agent turn, a routing
        decision). The reply and

        the "asked for more information" step ARE attributed to the node whose
        responder produced them,

        so a workflow trace answers "which node said this?".

        The leaf stays a flat :class:`TraceStep` — grouping only adds structure,
        never rewrites a row.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key

````