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

# Session Events

> Session events allow developers to query, validate, and control the lifecycle of active lens sessions through an event-driven interface.

## Session Lifecycle

Sessions progress through these states:

```mermaid theme={"system"}
stateDiagram-v2
    [*] --> SESSION_STATUS_REGISTERED: create_session()
    SESSION_STATUS_REGISTERED --> SESSION_STATUS_STARTING: session.start
    SESSION_STATUS_STARTING --> SESSION_STATUS_RUNNING: Initialization complete
    SESSION_STATUS_RUNNING --> SESSION_STATUS_KILLED: session.destroy
    SESSION_STATUS_STARTING --> SESSION_STATUS_KILLED: session.destroy
    SESSION_STATUS_KILLED --> [*]
```

***

## Session Event Types

| Event Type         | Pattern          | Description                                  |
| ------------------ | ---------------- | -------------------------------------------- |
| `session.status`   | Query            | Retrieve current session status and metadata |
| `session.validate` | Request-Response | Validate session health and configuration    |
| `session.get`      | Request-Response | Retrieve specific session information        |
| `session.modify`   | Request-Response | Modify session configuration                 |
| `session.update`   | Request-Response | Update session state                         |
| `session.read`     | Direct           | Read pending events from session queue       |
| `session.destroy`  | Request-Response | Terminate session and free resources         |

***

## session.status

Query the current status and metadata of an active session.

<CodeGroup>
  ```yaml Request theme={"system"}
  type: session.status
  ```

  ```json Response theme={"system"}
  {
    "session_id": "lsn-...",
    "lens_id": "lens_...",
    "org_id": "org_...",
    "session_status": "SESSION_STATUS_RUNNING",
    "session_endpoint": "https://...",
    "reverse_proxy_endpoint": "https://...",
    "session_runner": "node_...",
    "node_tag": "default",
    "registration_timestamp": 1234567890.0,
    "last_event_timestamp": 1234567890.0,
    "last_update_timestamp": 1234567890.0,
    "num_active_connections": 2,
    "num_updates": 15,
    "num_inputs": 42,
    "num_outputs": 38,
    "num_events": 120,
    "session_ttl_sec": 600
  }
  ```
</CodeGroup>

***

## session.validate

Validate that a session is properly configured and healthy.

<CodeGroup>
  ```yaml Request theme={"system"}
  type: session.validate
  event_data: {}
  ```

  ```json Response theme={"system"}
  {
    "type": "session.validate.response",
    // Response content is lens-specific
  }
  ```
</CodeGroup>

***

## session.get

Retrieve specific session configuration or state information.

<CodeGroup>
  ```yaml Request theme={"system"}
  type: session.get
  event_data:
    # Parameters are lens-specific
  ```

  ```json Response theme={"system"}
  {
    "type": "session.get.response",
    // Response content is lens-specific
  }
  ```
</CodeGroup>

***

## session.modify

Modify session configuration or parameters while the session is running.

<CodeGroup>
  ```yaml Request theme={"system"}
  type: session.modify
  event_data:
    # Parameters are lens-specific
  ```

  ```json Response theme={"system"}
  {
    "type": "session.modify.response",
    // Response content is lens-specific
  }
  ```
</CodeGroup>

***

## session.update

Update session state or trigger session processing.

<CodeGroup>
  ```yaml Request theme={"system"}
  type: session.update
  event_data:
    # Parameters are lens-specific
  ```

  ```json Response theme={"system"}
  {
    "type": "session.update.response",
    // Response content is lens-specific
  }
  ```
</CodeGroup>

***

## session.read

Read pending events from the session's event queue.

<Warning>
  Unlike other session events, session.read returns immediately without waiting for a response.
</Warning>

<CodeGroup>
  ```yaml Request theme={"system"}
  type: session.read
  event_data:
    # Parameters are lens-specific
  ```

  ```json Response theme={"system"}
  {
    // Returns immediately with available events
  }
  ```
</CodeGroup>

***

## session.destroy

Terminate an active session and free its allocated resources.

<Warning>
  Only affects sessions in `SESSION_STATUS_STARTING` or `SESSION_STATUS_RUNNING` status.
</Warning>

<CodeGroup>
  ```yaml Request theme={"system"}
  type: session.destroy
  event_data: {}
  ```

  ```json Response theme={"system"}
  {
    "type": "session.destroy.response",
    // Response confirms destruction
  }
  ```
</CodeGroup>

***

## Error Responses

| Error Type | Message                              | Cause                       |
| ---------- | ------------------------------------ | --------------------------- |
| `error`    | `"Unknown session id: {session_id}"` | Session not found           |
| `error`    | `"Failed to fetch session_runner!"`  | No node assigned to session |

<CodeGroup>
  ```json Session Not Found theme={"system"}
  {
    "type": "error",
    "message": "Unknown session id: lsn-abc123"
  }
  ```

  ```json No Session Runner theme={"system"}
  {
    "type": "error",
    "message": "Failed to fetch session_runner!"
  }
  ```
</CodeGroup>