# Computers

## List

`computers.list(ComputerListParams**kwargs)  -> ComputerListResponse`

**get** `/computers`

List all active computers for the user's organization. Use type=persistent to list persistent sessions instead.

### Parameters

- `type: Optional[Literal["live", "persistent"]]`

  Session type filter

  - `"live"`

  - `"persistent"`

### Returns

- `List[ComputerResponse]`

  - `id: Optional[str]`

  - `auto_kill: Optional[bool]`

  - `created_at: Optional[str]`

  - `endpoints: Optional[Dict[str, str]]`

  - `expires_at: Optional[str]`

  - `idle_expires_at: Optional[str]`

  - `inactivity_timeout_seconds: Optional[int]`

  - `kind: Optional[str]`

  - `last_activity_at: Optional[str]`

  - `max_lifetime_seconds: Optional[int]`

  - `status: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
computer_responses = client.computers.list()
print(computer_responses)
```

## Create

`computers.create(ComputerCreateParams**kwargs)  -> ComputerResponse`

**post** `/computers`

Create a new automation session. Set kind to "browser" for web automation or "desktop" for OS-level automation. Defaults to "browser" if not specified. timeout_seconds controls max lifetime, inactivity_timeout_seconds controls idle timeout, and auto_kill disables only the idle timeout (max lifetime still applies).

### Parameters

- `auto_kill: Optional[bool]`

  If true (default), kill session after inactivity

- `context_id: Optional[str]`

- `display: Optional[Display]`

  - `height: Optional[int]`

  - `scale: Optional[float]`

  - `width: Optional[int]`

- `environment_id: Optional[str]`

- `inactivity_timeout_seconds: Optional[int]`

  Idle timeout before auto-kill

- `kind: Optional[str]`

  "browser" (default) or "desktop"

- `persistent: Optional[bool]`

  Persist cookies/storage state to DB on session teardown only if true

- `stealth: Optional[object]`

- `timeout_seconds: Optional[int]`

- `use_advanced_proxy: Optional[bool]`

  If true (browser sessions), use ADVANCED_PROXY_URL on session start

### Returns

- `class ComputerResponse: …`

  - `id: Optional[str]`

  - `auto_kill: Optional[bool]`

  - `created_at: Optional[str]`

  - `endpoints: Optional[Dict[str, str]]`

  - `expires_at: Optional[str]`

  - `idle_expires_at: Optional[str]`

  - `inactivity_timeout_seconds: Optional[int]`

  - `kind: Optional[str]`

  - `last_activity_at: Optional[str]`

  - `max_lifetime_seconds: Optional[int]`

  - `status: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
computer_response = client.computers.create()
print(computer_response.id)
```

## Retrieve

`computers.retrieve(strid)  -> ComputerResponse`

**get** `/computers/{id}`

Get the current status and metadata of a computer instance

### Parameters

- `id: str`

### Returns

- `class ComputerResponse: …`

  - `id: Optional[str]`

  - `auto_kill: Optional[bool]`

  - `created_at: Optional[str]`

  - `endpoints: Optional[Dict[str, str]]`

  - `expires_at: Optional[str]`

  - `idle_expires_at: Optional[str]`

  - `inactivity_timeout_seconds: Optional[int]`

  - `kind: Optional[str]`

  - `last_activity_at: Optional[str]`

  - `max_lifetime_seconds: Optional[int]`

  - `status: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
computer_response = client.computers.retrieve(
    "id",
)
print(computer_response.id)
```

## Delete

`computers.delete(strid)`

**delete** `/computers/{id}`

Terminate and clean up a computer instance, stopping the session and recording metrics

### Parameters

- `id: str`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
client.computers.delete(
    "id",
)
```

## Batch

`computers.batch(strid, ComputerBatchParams**kwargs)  -> ComputerBatchResponse`

**post** `/computers/{id}/batch`

Execute a batch of actions in sequence, stopping on first error

### Parameters

- `id: str`

- `actions: Optional[Iterable[ComputerActionParam]]`

  - `auto_detect_encoding: Optional[bool]`

    For get_html_content

  - `base64: Optional[bool]`

    For screenshot

  - `button: Optional[str]`

  - `debug: Optional[Debug]`

    - `command: Optional[str]`

    - `cwd: Optional[str]`

    - `env: Optional[Dict[str, str]]`

    - `max_output_length: Optional[int]`

    - `request_id: Optional[str]`

    - `stream: Optional[bool]`

    - `timeout_seconds: Optional[int]`

  - `dx: Optional[float]`

    For scrolling

  - `dy: Optional[float]`

  - `height: Optional[int]`

  - `include_context: Optional[bool]`

    Include page context in response

  - `key: Optional[str]`

    For key_down/key_up

  - `keys: Optional[List[str]]`

  - `ms: Optional[int]`

  - `proxy_url: Optional[str]`

  - `request_id: Optional[str]`

    RequestId is used for correlating streaming output to the originating request.
    Set on ActionRequest, not individual action types.

  - `scale_factor: Optional[float]`

  - `tab_id: Optional[str]`

    For tab management (browser sessions only)

  - `text: Optional[str]`

  - `type: Optional[str]`

    click|double_click|right_click|drag|type|keypress|scroll|wait|screenshot|go_to_url|debug|get_html_content|set_viewport|list_tabs|new_tab|switch_tab|close_tab|key_down|key_up|mouse_down|mouse_up

  - `url: Optional[str]`

  - `width: Optional[int]`

    For set_viewport

  - `x: Optional[float]`

  - `x1: Optional[float]`

    For dragging/scrolling

  - `x2: Optional[float]`

    For dragging

  - `y: Optional[float]`

  - `y1: Optional[float]`

  - `y2: Optional[float]`

### Returns

- `Dict[str, object]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
response = client.computers.batch(
    id="id",
)
print(response)
```

## Change Proxy

`computers.change_proxy(strid, ComputerChangeProxyParams**kwargs)  -> ActionResult`

**post** `/computers/{id}/change-proxy`

Change the proxy settings for the browser session

### Parameters

- `id: str`

- `proxy_url: Optional[str]`

### Returns

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
action_result = client.computers.change_proxy(
    id="id",
)
print(action_result.executed_tab_id)
```

## Click

`computers.click(strid, ComputerClickParams**kwargs)  -> ActionResult`

**post** `/computers/{id}/click`

Perform a left mouse click at the specified x,y coordinates. Coordinates are screenshot pixel positions - send exactly what you see in the screenshot/screencast image. If target is at pixel (500, 300) in the image, send x=500, y=300. Optionally specify tab_id (browser sessions only)

### Parameters

- `id: str`

- `tab_id: Optional[str]`

- `x: Optional[float]`

- `y: Optional[float]`

### Returns

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
action_result = client.computers.click(
    id="id",
)
print(action_result.executed_tab_id)
```

## Debug

`computers.debug(strid, ComputerDebugParams**kwargs)  -> ActionResult`

**post** `/computers/{id}/debug`

Execute a shell command with optional timeout and output length limits. Optionally specify tab_id (browser sessions only). Deprecated: use /exec or /exec/sync instead.

### Parameters

- `id: str`

- `command: Optional[str]`

- `max_output_length: Optional[int]`

- `tab_id: Optional[str]`

- `timeout_seconds: Optional[int]`

### Returns

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
action_result = client.computers.debug(
    id="id",
)
print(action_result.executed_tab_id)
```

## Double Click

`computers.double_click(strid, ComputerDoubleClickParams**kwargs)  -> ActionResult`

**post** `/computers/{id}/double-click`

Perform a double mouse click at the specified x,y coordinates. Coordinates are screenshot pixel positions. Optionally specify tab_id (browser sessions only)

### Parameters

- `id: str`

- `tab_id: Optional[str]`

- `x: Optional[float]`

- `y: Optional[float]`

### Returns

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
action_result = client.computers.double_click(
    id="id",
)
print(action_result.executed_tab_id)
```

## Drag

`computers.drag(strid, ComputerDragParams**kwargs)  -> ActionResult`

**post** `/computers/{id}/drag`

Perform a click-and-drag action from (x1,y1) to (x2,y2). Coordinates are screenshot pixel positions. Optionally specify tab_id (browser sessions only)

### Parameters

- `id: str`

- `tab_id: Optional[str]`

- `x1: Optional[float]`

- `x2: Optional[float]`

- `y1: Optional[float]`

- `y2: Optional[float]`

### Returns

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
action_result = client.computers.drag(
    id="id",
)
print(action_result.executed_tab_id)
```

## Retrieve Events

`computers.retrieve_events(strid)`

**get** `/computers/{id}/events`

Stream real-time events using Server-Sent Events (SSE)

### Parameters

- `id: str`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
client.computers.retrieve_events(
    "id",
)
```

## Execute

`computers.execute(strid, ComputerExecuteParams**kwargs)  -> ActionResult`

**post** `/computers/{id}/execute`

Execute a single action such as screenshot, click, type, navigate, scroll, debug, set_viewport, get_html_content or other computer use actions

### Parameters

- `id: str`

- `action: Optional[ComputerActionParam]`

  - `auto_detect_encoding: Optional[bool]`

    For get_html_content

  - `base64: Optional[bool]`

    For screenshot

  - `button: Optional[str]`

  - `debug: Optional[Debug]`

    - `command: Optional[str]`

    - `cwd: Optional[str]`

    - `env: Optional[Dict[str, str]]`

    - `max_output_length: Optional[int]`

    - `request_id: Optional[str]`

    - `stream: Optional[bool]`

    - `timeout_seconds: Optional[int]`

  - `dx: Optional[float]`

    For scrolling

  - `dy: Optional[float]`

  - `height: Optional[int]`

  - `include_context: Optional[bool]`

    Include page context in response

  - `key: Optional[str]`

    For key_down/key_up

  - `keys: Optional[List[str]]`

  - `ms: Optional[int]`

  - `proxy_url: Optional[str]`

  - `request_id: Optional[str]`

    RequestId is used for correlating streaming output to the originating request.
    Set on ActionRequest, not individual action types.

  - `scale_factor: Optional[float]`

  - `tab_id: Optional[str]`

    For tab management (browser sessions only)

  - `text: Optional[str]`

  - `type: Optional[str]`

    click|double_click|right_click|drag|type|keypress|scroll|wait|screenshot|go_to_url|debug|get_html_content|set_viewport|list_tabs|new_tab|switch_tab|close_tab|key_down|key_up|mouse_down|mouse_up

  - `url: Optional[str]`

  - `width: Optional[int]`

    For set_viewport

  - `x: Optional[float]`

  - `x1: Optional[float]`

    For dragging/scrolling

  - `x2: Optional[float]`

    For dragging

  - `y: Optional[float]`

  - `y1: Optional[float]`

  - `y2: Optional[float]`

### Returns

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
action_result = client.computers.execute(
    id="id",
)
print(action_result.executed_tab_id)
```

## Hotkey

`computers.hotkey(strid, ComputerHotkeyParams**kwargs)  -> ActionResult`

**post** `/computers/{id}/hotkey`

Press a combination of keys (e.g., ["Control", "c"] for copy). Optionally specify tab_id (browser sessions only)

### Parameters

- `id: str`

- `keys: Optional[SequenceNotStr[str]]`

- `tab_id: Optional[str]`

### Returns

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
action_result = client.computers.hotkey(
    id="id",
)
print(action_result.executed_tab_id)
```

## HTML

`computers.html(strid, ComputerHTMLParams**kwargs)  -> ActionResult`

**post** `/computers/{id}/html`

Get the HTML content of the current browser page. Optionally specify tab_id (browser sessions only)

### Parameters

- `id: str`

- `auto_detect_encoding: Optional[bool]`

- `tab_id: Optional[str]`

### Returns

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
action_result = client.computers.html(
    id="id",
)
print(action_result.executed_tab_id)
```

## Keepalive

`computers.keepalive(strid)  -> ComputerKeepaliveResponse`

**post** `/computers/{id}/keepalive`

Extend the timeout for a computer session and verify it is still running

### Parameters

- `id: str`

### Returns

- `Dict[str, object]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
response = client.computers.keepalive(
    "id",
)
print(response)
```

## Key Down

`computers.key_down(strid, ComputerKeyDownParams**kwargs)  -> ActionResult`

**post** `/computers/{id}/key-down`

Press and hold a keyboard key. Use with key_up to release. Supports modifier keys (shift, ctrl, alt, meta) for complex interactions like Shift+Click.

**Supported keys:** Modifier keys (shift, ctrl, alt, meta), special keys (enter, escape, tab, backspace, delete, space), arrow keys (arrowup, arrowdown, arrowleft, arrowright), navigation (home, end, pageup, pagedown), function keys (f1-f24), and any single character (a-z, 0-9).

**Key names are case-insensitive:** "shift", "Shift", and "SHIFT" all work.

**Example Shift+Click:** 1) key_down "shift", 2) click at coordinates, 3) key_up "shift"

### Parameters

- `id: str`

- `key: Optional[str]`

  Key name to press. Case-insensitive. Examples: "shift", "ctrl", "a", "Enter"

- `tab_id: Optional[str]`

  Optional tab ID for browser sessions (ignored for desktop sessions)

### Returns

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
action_result = client.computers.key_down(
    id="id",
)
print(action_result.executed_tab_id)
```

## Key Up

`computers.key_up(strid, ComputerKeyUpParams**kwargs)  -> ActionResult`

**post** `/computers/{id}/key-up`

Release a keyboard key that was previously pressed with key_down. The key name should match the corresponding key_down call.

**Key names are case-insensitive:** "shift", "Shift", and "SHIFT" all work.

**Important:** Always release modifier keys after use to prevent them from affecting subsequent actions.

### Parameters

- `id: str`

- `key: Optional[str]`

  Key name to release. Case-insensitive. Examples: "shift", "ctrl", "a", "Enter"

- `tab_id: Optional[str]`

  Optional tab ID for browser sessions (ignored for desktop sessions)

### Returns

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
action_result = client.computers.key_up(
    id="id",
)
print(action_result.executed_tab_id)
```

## Mouse Down

`computers.mouse_down(strid, ComputerMouseDownParams**kwargs)  -> ActionResult`

**post** `/computers/{id}/mouse-down`

Press and hold the left mouse button at the specified x,y coordinates. Coordinates are screenshot pixel positions. Optionally specify tab_id (browser sessions only)

### Parameters

- `id: str`

- `tab_id: Optional[str]`

- `x: Optional[float]`

- `y: Optional[float]`

### Returns

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
action_result = client.computers.mouse_down(
    id="id",
)
print(action_result.executed_tab_id)
```

## Mouse Up

`computers.mouse_up(strid, ComputerMouseUpParams**kwargs)  -> ActionResult`

**post** `/computers/{id}/mouse-up`

Release the left mouse button at the specified x,y coordinates. Coordinates are screenshot pixel positions. Optionally specify tab_id (browser sessions only)

### Parameters

- `id: str`

- `tab_id: Optional[str]`

- `x: Optional[float]`

- `y: Optional[float]`

### Returns

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
action_result = client.computers.mouse_up(
    id="id",
)
print(action_result.executed_tab_id)
```

## Navigate

`computers.navigate(strid, ComputerNavigateParams**kwargs)  -> ActionResult`

**post** `/computers/{id}/navigate`

Navigate the browser to a specified URL. Optionally specify tab_id to navigate a specific tab (browser sessions only)

### Parameters

- `id: str`

- `tab_id: Optional[str]`

- `url: Optional[str]`

### Returns

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
action_result = client.computers.navigate(
    id="id",
)
print(action_result.executed_tab_id)
```

## Right Click

`computers.right_click(strid, ComputerRightClickParams**kwargs)  -> ActionResult`

**post** `/computers/{id}/right-click`

Perform a right mouse click at the specified x,y coordinates. Coordinates are screenshot pixel positions. Optionally specify tab_id (browser sessions only)

### Parameters

- `id: str`

- `tab_id: Optional[str]`

- `x: Optional[float]`

- `y: Optional[float]`

### Returns

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
action_result = client.computers.right_click(
    id="id",
)
print(action_result.executed_tab_id)
```

## Retrieve Screencast

`computers.retrieve_screencast(strid)`

**get** `/computers/{id}/screencast`

Stream only screencast frames (base64 JPEG images) using Server-Sent Events (SSE) for live browser viewing

### Parameters

- `id: str`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
client.computers.retrieve_screencast(
    "id",
)
```

## Screenshot

`computers.screenshot(strid, ComputerScreenshotParams**kwargs)  -> ActionResult`

**post** `/computers/{id}/screenshot`

Take a screenshot of the current browser viewport, optionally as base64. Optionally specify tab_id (browser sessions only)

### Parameters

- `id: str`

- `base64: Optional[bool]`

- `tab_id: Optional[str]`

### Returns

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
action_result = client.computers.screenshot(
    id="id",
)
print(action_result.executed_tab_id)
```

## Scroll

`computers.scroll(strid, ComputerScrollParams**kwargs)  -> ActionResult`

**post** `/computers/{id}/scroll`

Scroll at the specified x,y position by delta dx,dy. Coordinates are screenshot pixel positions. Optionally specify tab_id (browser sessions only)

### Parameters

- `id: str`

- `dx: Optional[float]`

- `dy: Optional[float]`

- `tab_id: Optional[str]`

- `x: Optional[float]`

- `y: Optional[float]`

### Returns

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
action_result = client.computers.scroll(
    id="id",
)
print(action_result.executed_tab_id)
```

## Retrieve Status

`computers.retrieve_status(strid)  -> ComputerRetrieveStatusResponse`

**get** `/computers/{id}/status`

Get current TTLs and last activity metadata for a computer session

### Parameters

- `id: str`

### Returns

- `class ComputerRetrieveStatusResponse: …`

  - `id: Optional[str]`

  - `auto_kill: Optional[bool]`

  - `created_at: Optional[str]`

  - `expires_at: Optional[str]`

  - `idle_expires_at: Optional[str]`

  - `inactivity_timeout_seconds: Optional[int]`

  - `last_activity_at: Optional[str]`

  - `max_lifetime_seconds: Optional[int]`

  - `status: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
response = client.computers.retrieve_status(
    "id",
)
print(response.id)
```

## Type

`computers.type(strid, ComputerTypeParams**kwargs)  -> ActionResult`

**post** `/computers/{id}/type`

Type text into the currently focused element in the browser. Optionally specify tab_id (browser sessions only)

### Parameters

- `id: str`

- `tab_id: Optional[str]`

- `text: Optional[str]`

### Returns

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
action_result = client.computers.type(
    id="id",
)
print(action_result.executed_tab_id)
```

## Viewport

`computers.viewport(strid, ComputerViewportParams**kwargs)  -> ActionResult`

**post** `/computers/{id}/viewport`

Change the browser viewport dimensions and scale factor. Optionally specify tab_id (browser sessions only)

### Parameters

- `id: str`

- `height: Optional[int]`

- `scale_factor: Optional[float]`

- `tab_id: Optional[str]`

- `width: Optional[int]`

### Returns

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
action_result = client.computers.viewport(
    id="id",
)
print(action_result.executed_tab_id)
```

## Retrieve Ws

`computers.retrieve_ws(strid)`

**get** `/computers/{id}/ws`

Establish WebSocket for real-time bidirectional communication

### Parameters

- `id: str`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
client.computers.retrieve_ws(
    "id",
)
```

## Domain Types

### Action Result

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Computer Action

- `class ComputerAction: …`

  - `auto_detect_encoding: Optional[bool]`

    For get_html_content

  - `base64: Optional[bool]`

    For screenshot

  - `button: Optional[str]`

  - `debug: Optional[Debug]`

    - `command: Optional[str]`

    - `cwd: Optional[str]`

    - `env: Optional[Dict[str, str]]`

    - `max_output_length: Optional[int]`

    - `request_id: Optional[str]`

    - `stream: Optional[bool]`

    - `timeout_seconds: Optional[int]`

  - `dx: Optional[float]`

    For scrolling

  - `dy: Optional[float]`

  - `height: Optional[int]`

  - `include_context: Optional[bool]`

    Include page context in response

  - `key: Optional[str]`

    For key_down/key_up

  - `keys: Optional[List[str]]`

  - `ms: Optional[int]`

  - `proxy_url: Optional[str]`

  - `request_id: Optional[str]`

    RequestId is used for correlating streaming output to the originating request.
    Set on ActionRequest, not individual action types.

  - `scale_factor: Optional[float]`

  - `tab_id: Optional[str]`

    For tab management (browser sessions only)

  - `text: Optional[str]`

  - `type: Optional[str]`

    click|double_click|right_click|drag|type|keypress|scroll|wait|screenshot|go_to_url|debug|get_html_content|set_viewport|list_tabs|new_tab|switch_tab|close_tab|key_down|key_up|mouse_down|mouse_up

  - `url: Optional[str]`

  - `width: Optional[int]`

    For set_viewport

  - `x: Optional[float]`

  - `x1: Optional[float]`

    For dragging/scrolling

  - `x2: Optional[float]`

    For dragging

  - `y: Optional[float]`

  - `y1: Optional[float]`

  - `y2: Optional[float]`

### Computer Response

- `class ComputerResponse: …`

  - `id: Optional[str]`

  - `auto_kill: Optional[bool]`

  - `created_at: Optional[str]`

  - `endpoints: Optional[Dict[str, str]]`

  - `expires_at: Optional[str]`

  - `idle_expires_at: Optional[str]`

  - `inactivity_timeout_seconds: Optional[int]`

  - `kind: Optional[str]`

  - `last_activity_at: Optional[str]`

  - `max_lifetime_seconds: Optional[int]`

  - `status: Optional[str]`

### V2 Go Backend Internal Types Page Context

- `class V2GoBackendInternalTypesPageContext: …`

  - `device_scale_factor: Optional[float]`

  - `is_main_tab: Optional[bool]`

  - `page_height: Optional[int]`

  - `page_width: Optional[int]`

  - `scroll_x: Optional[float]`

  - `scroll_y: Optional[float]`

  - `tab_id: Optional[str]`

  - `title: Optional[str]`

  - `url: Optional[str]`

  - `viewport_height: Optional[int]`

  - `viewport_width: Optional[int]`

# Exec

## Create

`computers.exec.create(strid, ExecCreateParams**kwargs)  -> ExecCreateResponse`

**post** `/computers/{id}/exec`

Execute a shell command with real-time streaming output as NDJSON. Each line is a JSON object with type (stdout/stderr/exit/error).

### Parameters

- `id: str`

- `command: Optional[str]`

- `cwd: Optional[str]`

- `env: Optional[Dict[str, str]]`

- `timeout_seconds: Optional[int]`

### Returns

- `class ExecCreateResponse: …`

  - `code: Optional[int]`

    for exit

  - `data: Optional[str]`

    for stdout/stderr

  - `message: Optional[str]`

    for error

  - `type: Optional[str]`

    "stdout", "stderr", "exit", "error"

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
for exec in client.computers.exec.create(
    id="id",
):
  print(exec)
```

## Sync

`computers.exec.sync(strid, ExecSyncParams**kwargs)  -> ExecSyncResponse`

**post** `/computers/{id}/exec/sync`

Execute a shell command and wait for completion, returning buffered stdout/stderr.

### Parameters

- `id: str`

- `command: Optional[str]`

- `cwd: Optional[str]`

- `env: Optional[Dict[str, str]]`

- `timeout_seconds: Optional[int]`

### Returns

- `class ExecSyncResponse: …`

  - `exit_code: Optional[int]`

  - `stderr: Optional[str]`

  - `stdout: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
response = client.computers.exec.sync(
    id="id",
)
print(response.exit_code)
```

# Tabs

## List

`computers.tabs.list(strid)  -> ActionResult`

**get** `/computers/{id}/tabs`

Get a list of open tabs with IDs, URLs, titles, and main tab status (browser sessions only). Includes external CDP pages (e.g., Playwright). Excludes devtools:// and chrome:// tabs. Results may be eventually consistent for newly created tabs.

### Parameters

- `id: str`

### Returns

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
action_result = client.computers.tabs.list(
    "id",
)
print(action_result.executed_tab_id)
```

## Create

`computers.tabs.create(strid, TabCreateParams**kwargs)  -> ActionResult`

**post** `/computers/{id}/tabs`

Create a new tab, optionally navigating to a URL. The new tab becomes the main tab (browser sessions only).

### Parameters

- `id: str`

- `url: Optional[str]`

### Returns

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
action_result = client.computers.tabs.create(
    id="id",
)
print(action_result.executed_tab_id)
```

## Delete

`computers.tabs.delete(strtab_id, TabDeleteParams**kwargs)  -> ActionResult`

**delete** `/computers/{id}/tabs/{tab_id}`

Close a specific tab by ID. Cannot close the last remaining tab (browser sessions only). Tab IDs come from ListTabs.

### Parameters

- `id: str`

- `tab_id: str`

### Returns

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
action_result = client.computers.tabs.delete(
    tab_id="tab_id",
    id="id",
)
print(action_result.executed_tab_id)
```

## Switch

`computers.tabs.switch(strtab_id, TabSwitchParams**kwargs)  -> ActionResult`

**post** `/computers/{id}/tabs/{tab_id}/switch`

Switch the main/active tab to a different tab by ID (browser sessions only). Tab IDs come from ListTabs.

### Parameters

- `id: str`

- `tab_id: str`

### Returns

- `class ActionResult: …`

  - `error_message: Optional[str]`

  - `executed_tab_id: Optional[str]`

  - `page_context: Optional[V2GoBackendInternalTypesPageContext]`

    - `device_scale_factor: Optional[float]`

    - `is_main_tab: Optional[bool]`

    - `page_height: Optional[int]`

    - `page_width: Optional[int]`

    - `scroll_x: Optional[float]`

    - `scroll_y: Optional[float]`

    - `tab_id: Optional[str]`

    - `title: Optional[str]`

    - `url: Optional[str]`

    - `viewport_height: Optional[int]`

    - `viewport_width: Optional[int]`

  - `request_id: Optional[str]`

  - `result: Optional[Dict[str, object]]`

  - `status: Optional[str]`

  - `timestamp: Optional[str]`

### Example

```python
import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
action_result = client.computers.tabs.switch(
    tab_id="tab_id",
    id="id",
)
print(action_result.executed_tab_id)
```