Responses

ActionResult

Each action returns an ActionResult object with information about whether it succeeded or failed.

Structure

ActionResult(
    status='SUCCESS',
    error_message=None,
    result={'screenshot_url': '...'},
    timestamp='2025-10-12T18:14:47Z'
)

Fields

status

string

Execution status: "SUCCESS" or "ERROR"

error_message

string | None

Error description if status is "ERROR", otherwise None

result

dict

Action-specific result data:

screenshot() returns {'screenshot_url': 'https://...'}
Most other actions return {}

timestamp

string

ISO 8601 timestamp of action completion

request_id

string | None

Unique identifier for the request (used for debugging and tracking)

page_context

object | None

Detailed page state information (when include_context=True is passed to action). See Page Context below.

executed_tab_id

string | None

ID of the tab where the action was executed (browser sessions only)

Usage Example

from tzafon import Computer

client = Computer()
with client.create(kind="browser") as computer:
    # Each action returns ActionResult
    nav_result = computer.navigate("https://example.com")
    
    if nav_result.status == "SUCCESS":
        print(f"✓ Navigation successful at {nav_result.timestamp}")
    else:
        print(f"✗ Failed: {nav_result.error_message}")
        exit()
    
    # Screenshot returns URL in result dict
    screenshot = computer.screenshot()
    if screenshot.status == "SUCCESS":
        url = screenshot.result['screenshot_url']
        print(f"Screenshot saved: {url}")

Page Context

Get detailed page state information with every action by passing include_context=True. This is useful for:

Understanding the current viewport and page dimensions
Tracking scroll position
Verifying which tab executed the action
Debugging coordinate-based interactions
Monitoring page navigation

Requesting Page Context

from tzafon import Computer

client = Computer()
with client.create(kind="browser") as computer:
    computer.navigate("https://example.com")

    # Request page context with any action
    result = computer.execute_action({
        "type": "screenshot",
        "include_context": True
    })

    context = result.page_context
    print(f"URL: {context.url}")
    print(f"Title: {context.title}")
    print(f"Viewport: {context.viewport_width}x{context.viewport_height}")
    print(f"Page size: {context.page_width}x{context.page_height}")
    print(f"Scroll: ({context.scroll_x}, {context.scroll_y})")
    print(f"Scale: {context.device_scale_factor}x")
    print(f"Tab ID: {context.tab_id}")
    print(f"Is main tab: {context.is_main_tab}")

PageContext Fields

url

string

Current page URL

title

string

Page title (from <title> tag)

viewport_width

int

Visible viewport width in pixels

viewport_height

int

Visible viewport height in pixels

page_width

int

Total page width in pixels (including scrollable area)

page_height

int

Total page height in pixels (including scrollable area)

scroll_x

float

Horizontal scroll position in pixels

scroll_y

float

Vertical scroll position in pixels

device_scale_factor

float

Device pixel ratio / zoom level (e.g., 2.0 for Retina displays)

tab_id

string

ID of the tab this context belongs to

is_main_tab

bool

Whether this is the main/first tab in the browser session

Use Cases

Coordinate Debugging

Verify viewport dimensions match your expected coordinates. If your click at (1500, 800) fails, check if viewport_width < 1500.

Scroll Position Tracking

Know exactly where on the page you are. Useful for calculating whether to scroll up or down to reach elements.

Multi-Tab Workflows

Track which tab each action executed on, especially useful when managing multiple tabs programmatically.

Responsive Testing

Verify that viewport changes (via set_viewport()) took effect and check device_scale_factor for high-DPI testing.

Page Navigation Verification

Example: Smart Scrolling

from tzafon import Computer

client = Computer()
with client.create(kind="browser") as computer:
    computer.navigate("https://example.com/long-page")

    # Get current context
    result = computer.execute_action({
        "type": "screenshot",
        "include_context": True
    })

    context = result.page_context

    # Calculate if we need to scroll to reach the bottom
    current_bottom = context.scroll_y + context.viewport_height
    page_height = context.page_height

    if current_bottom < page_height:
        # Scroll to bottom
        scroll_amount = page_height - current_bottom
        computer.scroll(dx=0, dy=scroll_amount)
        print(f"Scrolled {scroll_amount}px to reach bottom")
    else:
        print("Already at bottom of page")

Important: The include_context parameter is only available via execute_action()/execute() or the direct API. The high-level wrapper methods (computer.screenshot(), etc.) do NOT support this parameter.

Use include_context=True when you need to make decisions based on the current page state. For simple automation scripts, you can omit it to reduce response payload size.

Response Examples

ActionResult(
    status='SUCCESS',
    error_message=None,
    result={},
    timestamp='2025-10-12T18:14:47Z'
)

Failed Action

ActionResult(
    status='ERROR',
    error_message='Navigation timeout after 30 seconds',
    result={},
    timestamp='2025-10-12T18:15:17Z'
)

Screenshot Success

ActionResult(
    status='SUCCESS',
    error_message=None,
    result={
        'screenshot_url': 'https://storage.tzafon.ai/screenshots/abc123.png'
    },
    timestamp='2025-10-12T18:14:50Z'
)

Error Handling

from tzafon import Computer

client = Computer()
with client.create(kind="browser") as computer:
    result = computer.navigate("https://example.com")
    
    if result.status == "ERROR":
        print(f"Navigation failed: {result.error_message}")
        # Handle error: retry, log, exit, etc.
        exit()
    
    # Continue only if successful
    computer.click(100, 200)

Common Error Types

Error	Description	Solution
Navigation timeout	Page took too long to load	Increase wait time or check URL
Invalid coordinates	Click coordinates out of bounds	Verify x/y values are within viewport
Screenshot failed	Unable to capture screen	Check instance is active, retry
Connection error	Network/API connection issue	Check internet connection, retry
Invalid instance	Computer instance not found	Ensure create() succeeded, check termination

Best Practices

Always Check Critical Actions

Verify navigation and screenshot results before continuing

Log Errors for Debugging

Store error messages and timestamps for troubleshooting

Implement Retry Logic

Retry failed actions with exponential backoff

Use Context Managers

Ensure cleanup happens even when errors occur

Next Steps

Actions Reference

Explore all available actions

Computer Instances

Learn about browser and desktop instances

Getting Started

Core Concepts

Examples

ActionResult

Structure

Fields

Usage Example

Page Context

Requesting Page Context

PageContext Fields

Use Cases

Example: Smart Scrolling

Response Examples

Successful Navigation

Failed Action

Screenshot Success

Error Handling

Common Error Types

Best Practices

Next Steps

Actions Reference

Computer Instances

Getting Started

Core Concepts

Examples

​ActionResult

​Structure

​Fields

​Usage Example

​Page Context

​Requesting Page Context

​PageContext Fields

​Use Cases

​Example: Smart Scrolling

​Response Examples

​Successful Navigation

​Failed Action

​Screenshot Success

​Error Handling

​Common Error Types

​Best Practices

​Next Steps

Actions Reference

Computer Instances

ActionResult

Structure

Fields

Usage Example

Page Context

Requesting Page Context

PageContext Fields

Use Cases

Example: Smart Scrolling

Response Examples

Successful Navigation

Failed Action

Screenshot Success

Error Handling

Common Error Types

Best Practices

Next Steps