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

# List Session Traces

> Retrieve a paginated list of Langfuse observability traces for a specific LiveKit session.

Retrieve deep observability metrics and execution traces for a specific voice session.

Powered by our Langfuse integration, traces provide a "under the hood" look at exactly what your Voice Agent was thinking and doing during a conversation. This endpoint is vital for debugging slow response times, auditing prompt logic, and tracking your exact LLM token costs per call.

<Info>
  **Authentication Required:** You must include your API key in the `x-api-key` header to authenticate this request. You can only view traces for sessions within your authorized scope.
</Info>

### Required Parameters & Pagination

* **`sessionId` (Path Parameter):** The unique UUID of the LiveKit session you want to inspect.

Because a single session might generate many internal traces (e.g., one for STT, one for LLM reasoning, one for TTS generation), this endpoint is paginated using query parameters:

* **`page`**: The specific page of results you want to fetch (defaults to 1).
* **`limit`**: How many trace objects to return per page.

### Understanding the Trace Payload

A successful request returns a list of trace objects and pagination metadata. Each trace in the `traces` array contains actionable insights:

* **`latencySeconds`**: Exactly how long this specific generation or action took. If your agent is responding slowly, look for spikes here to identify the bottleneck.
* **`totalCostUsd`**: The calculated cost of the tokens consumed during this trace, allowing you to monitor unit economics on a per-call basis.
* **`observationCount`**: The number of individual steps or spans recorded within this trace.
* **`htmlPath`**: A highly useful localized path or URL you can use to visualize the trace in a graphical UI (if supported by your dashboard implementation).


## OpenAPI

````yaml get /traces/session/{sessionId}
openapi: 3.0.3
info:
  title: Lyzr Voice LiveKit API
  version: 1.0.0
servers:
  - url: https://voice-livekit.studio.lyzr.ai/v1
security: []
paths:
  /traces/session/{sessionId}:
    get:
      summary: List Session Traces
      description: >-
        Retrieve a paginated list of Langfuse observability traces for a
        specific LiveKit session.
      parameters:
        - name: sessionId
          in: path
          required: true
          description: The unique UUID of the LiveKit session.
          schema:
            type: string
            format: uuid
            example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        - name: page
          in: query
          description: The page number to retrieve for pagination.
          schema:
            type: integer
            example: 1
        - name: limit
          in: query
          description: The maximum number of traces to return per page.
          schema:
            type: integer
            example: 10
      responses:
        '200':
          description: Trace list retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  traces:
                    type: array
                    items:
                      type: object
                      properties:
                        traceId:
                          type: string
                          example: trace-abc-123
                        name:
                          type: string
                          example: voice-agent-response
                        sessionId:
                          type: string
                          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                        timestamp:
                          type: string
                          format: date-time
                          example: '2026-03-25T18:19:24.347Z'
                        latencySeconds:
                          type: number
                          format: float
                          example: 1.25
                        totalCostUsd:
                          type: number
                          format: float
                          example: 0.0034
                        observationCount:
                          type: integer
                          example: 4
                        htmlPath:
                          type: string
                          example: /traces/view/trace-abc-123
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                        example: 1
                      limit:
                        type: integer
                        example: 10
                      totalItems:
                        type: integer
                        example: 45
                      totalPages:
                        type: integer
                        example: 5
        '404':
          description: Trace session not found for caller scope.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Session traces not found.
                  details:
                    type: string
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````