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

# Get Sessions Metadata

> Get detailed metadata for all active lens sessions

## Overview

This endpoint returns detailed information about each active lens session in your organization.

## Request

<ParamField query="session_id" type="string">
  Optional. Filter to a specific session by ID.
</ParamField>

<ParamField query="shard_index" type="integer" default="-1">
  Optional. Shard index for pagination. Use `-1` to retrieve all sessions.
</ParamField>

<ParamField query="max_items_per_shard" type="integer" default="-1">
  Optional. Maximum items per shard. Use `-1` for no limit.
</ParamField>

## Response

Returns an array of session objects, each containing:

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

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

<ResponseField name="last_update_timestamp" type="float">
  Unix timestamp of the last activity on this session
</ResponseField>

<ResponseField name="session_status" type="string">
  Current status of the session
</ResponseField>

<ResponseField name="session_endpoint" type="string">
  WebSocket endpoint for this session
</ResponseField>

<ResponseField name="session_duration_sec" type="float">
  How long the session has been active in seconds
</ResponseField>

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

<ResponseField name="session_index" type="integer">
  Zero-based index of this session within the runner.
</ResponseField>

<RequestExample>
  ```bash cURL - All Sessions theme={"system"}
  curl https://api.u1.archetypeai.app/v0.5/lens/sessions/metadata \
    -H "Authorization: Bearer $ATAI_API_KEY"
  ```

  ```bash cURL - Specific Session theme={"system"}
  curl "https://api.u1.archetypeai.app/v0.5/lens/sessions/metadata?session_id=lsn-250313c2177253cbaa7a73542edd90" \
    -H "Authorization: Bearer $ATAI_API_KEY"
  ```

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

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

  response = requests.get(
      "https://api.u1.archetypeai.app/v0.5/lens/sessions/metadata",
      headers={"Authorization": f"Bearer {api_key}"}
  )

  sessions = response.json()
  if not sessions:
      print("No active sessions")
  else:
      for session in sessions:
          print(f"Session: {session['session_id']}")
          print(f"  Status: {session['session_status']}")
  ```

  ```javascript JavaScript theme={"system"}
  const response = await fetch('https://api.u1.archetypeai.app/v0.5/lens/sessions/metadata', {
    headers: {
      'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
    }
  });

  const sessions = await response.json();
  if (sessions.length === 0) {
    console.log('No active sessions');
  } else {
    sessions.forEach(session => {
      console.log(`Session: ${session.session_id}`);
    });
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success (with sessions) theme={"system"}
  [
    {
      "session_id": "lsn-250313c2177253cbaa7a73542edd90",
      "lens_id": "lns-fd669361822b07e2-237ab3ffd79199b1",
      "last_update_timestamp": 1741843135.1848276,
      "session_status": "SESSION_STATUS_RUNNING",
      "session_runner": "lens_service:runner:lens-node-worker-node-abc123",
      "session_endpoint": "wss://api.u1.archetypeai.app/v0.5/lens/sessions/lsn-250313c2177253cbaa7a73542edd90",
      "session_index": 0,
      "session_duration_sec": 2811.020206451416
    }
  ]
  ```

  ```json 200 - No active sessions theme={"system"}
  []
  ```

  ```json 200 - Non-existent session_id filter theme={"system"}
  []
  ```

  ```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"
      }
    ]
  }
  ```

  ```json 422 - Invalid shard_index type theme={"system"}
  {
    "detail": [
      {
        "type": "int_parsing",
        "loc": [
          "query",
          "shard_index"
        ],
        "msg": "Input should be a valid integer, unable to parse string as an integer",
        "input": "abc"
      }
    ]
  }
  ```
</ResponseExample>