Capabilities

Session, context, extension, and download capabilities exposed by the Python SDK.

Core Features

Session Management

Create Session

# Basic creation
session = client.sessions.create()

# With specific browser mode
session = client.sessions.create(browser_mode="normal")

# With uploaded extensions
session = client.sessions.create(
    browser_mode="normal",
    extension_ids=["ext_11ff6ce20fb0"]
)

# With authenticated upstream proxy
session = client.sessions.create(
    proxy={
        "type": "external",
        "server": "http://10.3.6.54:28080",
        "username": "user",
        "password": "pass",
    }
)

# Available browser modes:
# - "normal": Chrome in Docker container
# - "light": Lightweight Chrome in Docker

Extension Management

# Upload extension archive
extension = client.extensions.upload("./test_extension.zip", name="demo-extension")

# List extensions
extensions = client.extensions.list(limit=10)
for item in extensions:
    print(item.id, item.name)

# Get extension details
extension = client.extensions.get(extension.id)

# Use extension when creating session
session = client.sessions.create(extension_ids=[extension.id])

List Sessions

# List all sessions with pagination
result = client.sessions.list()
print(f"Total: {result.pagination.total_count}")
print(f"Active: {result.pagination.active_count}")

for session in result.sessions:
    print(f"{session.id}: {session.status}")

# Filter by status (server-side filtering)
active_sessions = client.sessions.list(status="active")
print(f"Found {len(active_sessions)} active sessions")

Delete Session

# Delete by session ID
client.sessions.delete(session_id="session-id")

# Or use session object
session.close()

Session Timeout Behavior

Session timeout is enforced server-side from the session's configured duration.
If the timeout is reached but the platform has seen recent client CDP activity within the last 2 minutes, the session is kept alive temporarily instead of being deleted immediately.
In practice, active connect_over_cdp, Playwright, Puppeteer, and raw DevTools traffic all count as CDP activity.
Once CDP activity stops for more than 2 minutes, the timed-out session becomes eligible for cleanup on the next timeout sweep.

Session Downloads

session = client.sessions.create(downloads={"enabled": True})

# List downloads for a session
downloads = client.sessions.downloads.list(session.id)
print(downloads.summary["count"])

# Download a single file
file_bytes = client.sessions.downloads.get(session.id, "download-id")

# Download all files as zip
archive_bytes = client.sessions.downloads.archive(session.id)

# Clear session downloads
client.sessions.downloads.delete(session.id)

Persistent Replay

session = client.sessions.create(recording={"persistent": True})

Close the session after the task finishes, then inspect the replay artifact from the console session detail page.

Error Handling

from lexmount import (
    Lexmount,
    AuthenticationError,
    SessionNotFoundError,
    TimeoutError,
    NetworkError,
    APIError
)

try:
    client = Lexmount(api_key="key", project_id="proj")
    session = client.sessions.create()
except AuthenticationError:
    print("Invalid credentials")
except TimeoutError:
    print("Request timed out")
except NetworkError:
    print("Network connection failed")
except APIError as e:
    print(f"API error: {e.status_code}")

Logging

from lexmount import set_log_level

# Enable debug logging
set_log_level("DEBUG")

# Available levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
client = Lexmount(api_key="key", project_id="proj")
session = client.sessions.create()  # Will log detailed info

Context Operations

client.contexts.create(metadata=...) creates a server-side persistent browser profile.
client.contexts.list(status=..., limit=...) lists available or locked contexts.
client.contexts.get(context_id) reads one context.
client.contexts.delete(context_id) deletes one context.
client.contexts.force_release(context_id) clears a stuck lock as an emergency operation.

API Reference Entry Points

This page contains the complete API reference for the Lexmount Python SDK.

Client

lexmount.Lexmount

Sessions

lexmount._sessions.SessionsResource

Session Information

lexmount._sessions.SessionInfo
lexmount._sessions.SessionListResponse
lexmount._sessions.PaginationInfo

Exceptions

lexmount.exceptions

Logging

lexmount._logging

Core Features

Session Management

Create Session

# Basic creation
session = client.sessions.create()

# With specific browser mode
session = client.sessions.create(browser_mode="normal")

# With uploaded extensions
session = client.sessions.create(
    browser_mode="normal",
    extension_ids=["ext_11ff6ce20fb0"]
)

# With authenticated upstream proxy
session = client.sessions.create(
    proxy={
        "type": "external",
        "server": "http://10.3.6.54:28080",
        "username": "user",
        "password": "pass",
    }
)

# Available browser modes:
# - "normal": Chrome in Docker container
# - "light": Lightweight Chrome in Docker

Extension Management

# Upload extension archive
extension = client.extensions.upload("./test_extension.zip", name="demo-extension")

# List extensions
extensions = client.extensions.list(limit=10)
for item in extensions:
    print(item.id, item.name)

# Get extension details
extension = client.extensions.get(extension.id)

# Use extension when creating session
session = client.sessions.create(extension_ids=[extension.id])

List Sessions

# List all sessions with pagination
result = client.sessions.list()
print(f"Total: {result.pagination.total_count}")
print(f"Active: {result.pagination.active_count}")

for session in result.sessions:
    print(f"{session.id}: {session.status}")

# Filter by status (server-side filtering)
active_sessions = client.sessions.list(status="active")
print(f"Found {len(active_sessions)} active sessions")

Delete Session

# Delete by session ID
client.sessions.delete(session_id="session-id")

# Or use session object
session.close()

Session Timeout Behavior

Session timeout is enforced server-side from the session's configured duration.
If the timeout is reached but the platform has seen recent client CDP activity within the last 2 minutes, the session is kept alive temporarily instead of being deleted immediately.
In practice, active connect_over_cdp, Playwright, Puppeteer, and raw DevTools traffic all count as CDP activity.
Once CDP activity stops for more than 2 minutes, the timed-out session becomes eligible for cleanup on the next timeout sweep.

Session Downloads

session = client.sessions.create(downloads={"enabled": True})

# List downloads for a session
downloads = client.sessions.downloads.list(session.id)
print(downloads.summary["count"])

# Download a single file
file_bytes = client.sessions.downloads.get(session.id, "download-id")

# Download all files as zip
archive_bytes = client.sessions.downloads.archive(session.id)

# Clear session downloads
client.sessions.downloads.delete(session.id)

Persistent Replay

session = client.sessions.create(recording={"persistent": True})

Close the session after the task finishes, then inspect the replay artifact from the console session detail page.

Error Handling

from lexmount import (
    Lexmount,
    AuthenticationError,
    SessionNotFoundError,
    TimeoutError,
    NetworkError,
    APIError
)

try:
    client = Lexmount(api_key="key", project_id="proj")
    session = client.sessions.create()
except AuthenticationError:
    print("Invalid credentials")
except TimeoutError:
    print("Request timed out")
except NetworkError:
    print("Network connection failed")
except APIError as e:
    print(f"API error: {e.status_code}")

Logging

from lexmount import set_log_level

# Enable debug logging
set_log_level("DEBUG")

# Available levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
client = Lexmount(api_key="key", project_id="proj")
session = client.sessions.create()  # Will log detailed info

Context Operations

client.contexts.create(metadata=...) creates a server-side persistent browser profile.
client.contexts.list(status=..., limit=...) lists available or locked contexts.
client.contexts.get(context_id) reads one context.
client.contexts.delete(context_id) deletes one context.
client.contexts.force_release(context_id) clears a stuck lock as an emergency operation.