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

# Create Session Event

> Record a session lifecycle event.

## Event Types

| Event | Description | When to Use |
|-------|-------------|-------------|
| `SESSION_START` | Session has started | After WebRTC connection is established |
| `SESSION_DURING` | Session heartbeat | Periodically during active session |
| `SESSION_END` | Session ended normally | When user ends the session |
| `SESSION_ERROR` | Session ended with error | When an error occurs |
| `SESSION_LOG` | Custom log entry | For debugging/analytics |

## Example

Select **"CreateSessionEventRequest"** from the **Examples** dropdown to see the request format.




## OpenAPI

````yaml /specs/openapi-interactive.json post /api/v1/session/{session_id}/event/create/
openapi: 3.0.3
info:
  title: Perso Interactive API
  version: 0.0.0
servers:
  - url: https://platform.perso.ai
security: []
tags:
  - name: Embed
paths:
  /api/v1/session/{session_id}/event/create/:
    post:
      tags:
        - Session Lifecycle
      summary: Create Session Event
      description: >
        Record a session lifecycle event.


        ## Event Types


        | Event | Description | When to Use |

        |-------|-------------|-------------|

        | `SESSION_START` | Session has started | After WebRTC connection is
        established |

        | `SESSION_DURING` | Session heartbeat | Periodically during active
        session |

        | `SESSION_END` | Session ended normally | When user ends the session |

        | `SESSION_ERROR` | Session ended with error | When an error occurs |

        | `SESSION_LOG` | Custom log entry | For debugging/analytics |


        ## Example


        Select **"CreateSessionEventRequest"** from the **Examples** dropdown to
        see the request format.
      operationId: v1_session_event_create_create
      parameters:
        - in: path
          name: session_id
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionEventCreateRequest'
            examples:
              CreateSessionEventRequest:
                value:
                  event: SESSION_START
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SessionEventCreateRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/SessionEventCreateRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionEventCreate'
          description: ''
        '400':
          description: Bad Request - Invalid input data or parameters.
        '401':
          description: Unauthorized - Invalid or missing authentication credentials.
        '403':
          description: Forbidden - You do not have permission to perform this action.
        '404':
          description: Not Found - The requested resource could not be found.
        '405':
          description: Method Not Allowed - Invalid HTTP method
        '406':
          description: Not Acceptable - Invalid request accept headers
        '415':
          description: Unsupported Media Type - Invalid content type
        '500':
          description: Internal Server Error - An unexpected error occurred.
      security:
        - {}
components:
  schemas:
    SessionEventCreateRequest:
      type: object
      properties:
        detail:
          type: string
          description: Optional human-readable detail describing the event.
        file:
          type: string
          format: binary
          nullable: true
          description: Optional binary file attached to the event (max 10 MB).
        event:
          allOf:
            - $ref: '#/components/schemas/EventEnum'
          description: >-
            Event type — see SessionEventType enum (e.g. SESSION_END,
            SESSION_ERROR).


            * `SESSION_START` - Session Start

            * `SESSION_DURING` - Session During

            * `SESSION_LOG` - Session Log

            * `SESSION_END` - Session End

            * `SESSION_ERROR` - Session Error

            * `SESSION_TTS` - Session TTS

            * `SESSION_STT` - Session STT

            * `SESSION_LLM` - Session LLM

            * `SESSION_DASHBOARD` - Session Dashboard

            * `SESSION_WS_LOG` - Session WS Log

            * `SESSION_WS_ERROR` - Session WS Error
      required:
        - event
    SessionEventCreate:
      type: object
      properties:
        sessionevent_id:
          type: string
          format: uuid
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        detail:
          type: string
          description: Optional human-readable detail describing the event.
        file:
          type: string
          format: uri
          nullable: true
          description: Optional binary file attached to the event (max 10 MB).
        terminate:
          type: boolean
          readOnly: true
        terminate_reason:
          readOnly: true
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/TerminateReasonEnum'
            - $ref: '#/components/schemas/NullEnum'
        event:
          allOf:
            - $ref: '#/components/schemas/EventEnum'
          description: >-
            Event type — see SessionEventType enum (e.g. SESSION_END,
            SESSION_ERROR).


            * `SESSION_START` - Session Start

            * `SESSION_DURING` - Session During

            * `SESSION_LOG` - Session Log

            * `SESSION_END` - Session End

            * `SESSION_ERROR` - Session Error

            * `SESSION_TTS` - Session TTS

            * `SESSION_STT` - Session STT

            * `SESSION_LLM` - Session LLM

            * `SESSION_DASHBOARD` - Session Dashboard

            * `SESSION_WS_LOG` - Session WS Log

            * `SESSION_WS_ERROR` - Session WS Error
      required:
        - created_at
        - event
        - sessionevent_id
        - terminate
        - terminate_reason
    EventEnum:
      enum:
        - SESSION_START
        - SESSION_DURING
        - SESSION_LOG
        - SESSION_END
        - SESSION_ERROR
        - SESSION_TTS
        - SESSION_STT
        - SESSION_LLM
        - SESSION_DASHBOARD
        - SESSION_WS_LOG
        - SESSION_WS_ERROR
      type: string
      description: |-
        * `SESSION_START` - Session Start
        * `SESSION_DURING` - Session During
        * `SESSION_LOG` - Session Log
        * `SESSION_END` - Session End
        * `SESSION_ERROR` - Session Error
        * `SESSION_TTS` - Session TTS
        * `SESSION_STT` - Session STT
        * `SESSION_LLM` - Session LLM
        * `SESSION_DASHBOARD` - Session Dashboard
        * `SESSION_WS_LOG` - Session WS Log
        * `SESSION_WS_ERROR` - Session WS Error
    TerminateReasonEnum:
      enum:
        - SESSION_EVENT_GRACEFUL_TERMINATION
        - SESSION_EVENT_SESSION_EXPIRED_BEFORE_CONNECTION
        - SESSION_EVENT_SESSION_LOST_AFTER_CONNECTION
        - SESSION_EVENT_MISC_ERROR
        - SESSION_EVENT_MAX_ACTIVE_SESSION_QUOTA_EXCEEDED
        - SESSION_EVENT_MAX_MIN_PER_SESSION_QUOTA_EXCEEDED
        - SESSION_EVENT_TOTAL_MIN_PER_MONTH_QUOTA_EXCEEDED
        - SESSION_EVENT_INSUFFICIENT_CREDITS
      type: string
      description: >-
        * `SESSION_EVENT_GRACEFUL_TERMINATION` - Graceful Termination

        * `SESSION_EVENT_SESSION_EXPIRED_BEFORE_CONNECTION` - Session Expired
        Before Connection

        * `SESSION_EVENT_SESSION_LOST_AFTER_CONNECTION` - Session Lost After
        Connection

        * `SESSION_EVENT_MISC_ERROR` - Session Misc Error

        * `SESSION_EVENT_MAX_ACTIVE_SESSION_QUOTA_EXCEEDED` - Max Active Session
        Quota Exceeded

        * `SESSION_EVENT_MAX_MIN_PER_SESSION_QUOTA_EXCEEDED` - Max Min Per
        Session Quota Exceeded

        * `SESSION_EVENT_TOTAL_MIN_PER_MONTH_QUOTA_EXCEEDED` - Total Min Per
        Month Quota Exceeded

        * `SESSION_EVENT_INSUFFICIENT_CREDITS` - Insufficient Credits
    NullEnum:
      enum:
        - null

````