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

# Destroy Lens Session

> Destroy an active lens session and free up resources

## Overview

This endpoint destroys an active lens session, closing any open connections and freeing up resources.

Always destroy sessions when you're done using them to avoid hitting concurrent session limits.

## Request

<ParamField body="session_id" type="string" required>
  The unique session ID to destroy. This is returned when creating a session.
</ParamField>

## Response

On success, returns the destroyed session record. Errors are returned with an HTTP 4xx status and an `errors` array (no `is_valid` field).

<ResponseField name="session_id" type="string">
  The ID of the destroyed session.
</ResponseField>

<ResponseField name="lens_id" type="string">
  The lens ID the session was attached to.
</ResponseField>

<ResponseField name="session_status" type="string">
  Final status of the session (typically `SESSION_STATUS_DESTROYED`).
</ResponseField>

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

<ResponseField name="session_endpoint" type="string">
  WebSocket URL the session was reachable at.
</ResponseField>

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

<ResponseField name="session_duration_sec" type="float">
  Total duration the session was active in seconds.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X POST https://api.u1.archetypeai.app/v0.5/lens/sessions/destroy \
    -H "Authorization: Bearer $ATAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "session_id": "lsn-250313c2177253cbaa7a73542edd90"
    }'
  ```

  ```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/destroy",
      headers={
          "Authorization": f"Bearer {api_key}",
          "Content-Type": "application/json"
      },
      json={
          "session_id": "lsn-250313c2177253cbaa7a73542edd90"
      }
  )

  result = response.json()

  if result.get("is_valid") == False:
      print(f"Error: {result['errors']}")
  else:
      print(f"Session destroyed: {result['session_id']}")
      print(f"Duration: {result['session_duration_sec']} seconds")
  ```

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

  const result = await response.json();

  if (result.is_valid === false) {
    console.error('Error:', result.errors);
  } else {
    console.log(`Session destroyed: ${result.session_id}`);
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={"system"}
  {
    "session_id": "lsn-2512078e5c9ce4d312a6681e771542",
    "lens_id": "lns-test-lens-3de60a5c",
    "last_update_timestamp": 1765095462.576972,
    "session_status": "SESSION_STATUS_DESTROYED",
    "session_runner": "lens_service:runner:lens-node-worker-node-abc123",
    "session_endpoint": "wss://api.u1.archetypeai.app/v0.5/lens/sessions/lsn-2512078e5c9ce4d312a6681e771542",
    "session_duration_sec": 53.79125928878784
  }
  ```

  ```json 400 - Missing session_id theme={"system"}
  {
    "errors": [
      "Missing session_id!"
    ]
  }
  ```

  ```json 400 - Non-existent or already destroyed session theme={"system"}
  {
    "errors": [
      "Invalid session_id: lsn-nonexistent-12345678"
    ]
  }
  ```

  ```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>

## Best Practices

<Tip>
  **Always clean up sessions**: Implement proper cleanup in your code to ensure sessions are destroyed even if errors occur:

  ```python theme={"system"}
  try:
      # Create and use session
      session = create_session(lens_id)
      process_data(session)
  finally:
      # Always destroy the session
      destroy_session(session['session_id'])
  ```
</Tip>

<Warning>
  Sessions that are not explicitly destroyed will:

  * Continue consuming your concurrent session quota
  * Timeout after 30 minutes of inactivity
  * May result in hitting rate limits for new session creation
</Warning>