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

# Create Lens Session

> Create a new lens session for processing sensor data

## Overview

This endpoint creates and allocates a new lens session that can process sensor data streams.

Each session is associated with a specific lens and returns a unique **session ID** and endpoint for real-time data streaming.

## Request

<ParamField body="lens_id" type="string" required>
  The ID of the lens to use for this session. Get available lens IDs from `/lens/metadata`
</ParamField>

## Response

<Warning>
  The response contains an `api_key` field that echoes back the caller's real API key. Treat this field as a secret — do not log, persist, or expose it in client-side code.
</Warning>

<ResponseField name="session_id" type="string">
  Unique identifier for the created session.
</ResponseField>

<ResponseField name="lens_id" type="string">
  The lens ID associated with this session.
</ResponseField>

<ResponseField name="lens_name" type="string">
  Name of the lens associated with this session.
</ResponseField>

<ResponseField name="org_id" type="string">
  Organization identifier the session belongs to.
</ResponseField>

<ResponseField name="api_key" type="string">
  The caller's API key, echoed back for downstream WebSocket auth. **Sensitive — see warning above.**
</ResponseField>

<ResponseField name="session_endpoint" type="string">
  WebSocket URL for streaming data to/from the session.
</ResponseField>

<ResponseField name="session_status" type="string">
  Initial status of the session (typically `LensSessionStatus.SESSION_STATUS_REGISTERED`).
</ResponseField>

<ResponseField name="session_ttl_sec" type="integer">
  Maximum session lifetime in seconds (default `86400`, i.e. 24 hours of inactivity).
</ResponseField>

<ResponseField name="session_runner" type="string">
  Identifier of the backend runner hosting the session.
</ResponseField>

<ResponseField name="lens_config" type="object">
  Resolved lens configuration in use for this session.
</ResponseField>

<ResponseField name="registration_timestamp" type="float">
  Unix timestamp when the session record was created.
</ResponseField>

<ResponseField name="last_event_timestamp" type="float">
  Unix timestamp of the last event processed by the session.
</ResponseField>

<ResponseField name="last_update_timestamp" type="float">
  Unix timestamp of the last update to the session record.
</ResponseField>

<ResponseField name="session_start_timestamp" type="float">
  Unix timestamp when the session began running. `null` until the runner starts.
</ResponseField>

<ResponseField name="session_destroyed_timestamp" type="float">
  Unix timestamp when the session was destroyed. `null` while active.
</ResponseField>

<ResponseField name="input_data_stream_id" type="string">
  Identifier of the configured input stream, or `null` if none is set.
</ResponseField>

<ResponseField name="output_data_stream_id" type="string">
  Identifier of the configured output stream, or `null` if none is set.
</ResponseField>

<ResponseField name="num_active_connections" type="integer">
  Number of active client connections to the session.
</ResponseField>

<ResponseField name="num_events" type="integer">
  Total number of events processed by the session.
</ResponseField>

<ResponseField name="num_updates" type="integer">
  Number of state updates the session has emitted.
</ResponseField>

<ResponseField name="num_inputs" type="integer">
  Number of input frames/records the session has received.
</ResponseField>

<ResponseField name="num_outputs" type="integer">
  Number of outputs the session has produced.
</ResponseField>

<ResponseField name="node_tag" type="string">
  Tag of the runner node the session is bound to.
</ResponseField>

<ResponseField name="errors" type="array">
  Array of error messages if the request failed (check for this field to detect errors).
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X POST https://api.u1.archetypeai.app/v0.5/lens/sessions/create \
    -H "Authorization: Bearer $ATAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "lens_id": "lns-fd669361822b07e2-237ab3ffd79199b0"
    }'
  ```

  ```python Python theme={"system"}
  import requests
  import os

  api_key = os.environ.get("ATAI_API_KEY")

  response = requests.post(
      "https://api.u1.archetypeai.app/v0.5/lens/sessions/create",
      headers={
          "Authorization": f"Bearer {api_key}",
          "Content-Type": "application/json"
      },
      json={
          "lens_id": "lns-fd669361822b07e2-237ab3ffd79199b0"
      }
  )

  data = response.json()

  if "errors" in data:
      print(f"Error: {data['errors']}")
  else:
      print(f"Session created: {data['session_id']}")
      print(f"WebSocket endpoint: {data['session_endpoint']}")
  ```

  ```javascript JavaScript theme={"system"}
  const response = await fetch('https://api.u1.archetypeai.app/v0.5/lens/sessions/create', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      lens_id: 'lns-fd669361822b07e2-237ab3ffd79199b0'
    })
  });

  const data = await response.json();

  if (data.errors) {
    console.error('Error:', data.errors);
  } else {
    console.log(`Session created: ${data.session_id}`);
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={"system"}
  {
    "org_id": "your-org",
    "api_key": "<echoed-api-key>",
    "session_id": "lsn-251207a89f948ed4e30d8f80aaba77",
    "lens_id": "lns-test-lens-b2ba0058",
    "lens_name": "Test Lens",
    "input_data_stream_id": null,
    "output_data_stream_id": null,
    "registration_timestamp": 1779428775.5983343,
    "last_event_timestamp": 1779428775.5983343,
    "last_update_timestamp": 1779428775.5983343,
    "session_start_timestamp": null,
    "session_destroyed_timestamp": null,
    "num_active_connections": 0,
    "num_updates": 0,
    "num_inputs": 0,
    "num_outputs": 0,
    "num_events": 0,
    "lens_config": {
      "model_pipeline": [
        {"processor_name": "lens_noop_processor", "processor_config": {}}
      ]
    },
    "session_status": "LensSessionStatus.SESSION_STATUS_REGISTERED",
    "session_runner": "lens_service:runner:lens-node-worker-node-abc123",
    "session_endpoint": "wss://api.u1.archetypeai.app/v0.5/lens/sessions/lsn-251207a89f948ed4e30d8f80aaba77",
    "node_tag": "default",
    "session_ttl_sec": 86400
  }
  ```

  ```json 400 - Missing lens_id theme={"system"}
  {
    "errors": [
      "Invalid lens_id: None"
    ]
  }
  ```

  ```json 400 - Non-existent or invalid lens_id theme={"system"}
  {
    "errors": [
      "Invalid lens config"
    ]
  }
  ```

  ```json 401 - Unauthorized theme={"system"}
  {
    "errors": [
      {
        "code": "unauthorized_request",
        "message": "Unauthorized or invalid access.",
        "suggestion": "Provide valid authentication credentials and ensure they have the required permissions.",
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```
</ResponseExample>

## Important Notes

<Note>
  * Sessions remain active until explicitly destroyed or timeout after no sensor activity
  * Always destroy sessions when done to free up resources
  * Check which sessions are running via /lens/sessions/metadata
</Note>