Python SDK

goto(url) #

Navigate the session to a new URL. Waits for the page to load before returning.

session.goto("https://news.ycombinator.com")
print(session.page.url)    # "https://news.ycombinator.com"
print(session.page.title)  # "Hacker News"

observe() #

Get the current page content and interactive elements. Use this to discover element refs before clicking or filling.

result = session.observe(scope="nav", format="markdown")

# Page content
print(result.page.markdown.content)

# Interactive elements with refs
for el in result.page.interactive_elements:
    print(f"{el.ref}: [{el.tag}] {el.label}")

Response example:

{
  "page": {
    "url": "https://example.com",
    "title": "Example",
    "markdown": {"content": "# Welcome\nThis is an example page."},
    "interactive_elements": [
      {"ref": "e1", "tag": "a", "role": "link", "label": "Home"},
      {"ref": "e2", "tag": "button", "role": "button", "label": "Sign In"}
    ]
  }
}

click() #

Click an element. Target it by ref (from observe), visible text, or accessible label.

# By ref (most precise)
session.click(ref="e2")

# By visible text
session.click(text="Sign In")

# By accessible label
session.click(label="Submit form")

fill(value) #

Clear an input field and set its value. Target by ref, text, or label.

# Fill by ref
session.fill("user@example.com", ref="e5")

# Fill by label
session.fill("hunter2", label="Password")

# Fill by visible text
session.fill("hello@example.com", text="Email")

fill_form(fields) #

Fill multiple form fields in a single call. Fields are matched by label. Optionally submit the form.

session.fill_form(
    {
        "Email": "user@example.com",
        "Password": "s3cur3p@ss",
        "Company": "Acme Inc.",
    },
    submit=True,
)

extract(**schema) #

Extract structured data from the page. Define your schema as keyword arguments. Supports nested objects and arrays.

# Simple extraction
result = session.extract(
    title="h1 >> text",
    description="meta[name=description] >> content",
)
print(result.extraction)
# {"title": "Example Domain", "description": "An example page."}

# Array extraction with nested schema
result = session.extract(
    products=[{
        "_parent": ".product-card",
        "name": "h2 >> text",
        "price": ".price >> text",
        "url": "a >> href",
    }]
)
for product in result.extraction["products"]:
    print(f"{product['name']}: {product['price']}")

Response example:

{
  "extraction": {
    "products": [
      {"name": "Widget Pro", "price": "$29.99", "url": "/products/widget-pro"},
      {"name": "Gadget Plus", "price": "$49.99", "url": "/products/gadget-plus"}
    ]
  }
}

screenshot() #

Capture a screenshot of the current viewport or the full page.

import base64

result = session.screenshot(full_page=True, format="png")

# Save to file
image_data = base64.b64decode(result.media[0].data)
with open("screenshot.png", "wb") as f:
    f.write(image_data)

scroll_collect() #

Scroll through the entire page and collect all content. Useful for infinite-scroll or long pages.

result = session.scroll_collect(max_scrolls=20, wait_ms=1000)
print(result.page.markdown.content)  # Full page content
print(result.page.scroll.percent)    # 100

close() #

Close the session and release browser resources. Always close sessions when you're done.

session.close()

type(value) #

Type text character by character. Useful for inputs with autocomplete or client-side filtering. Target by ref, text, or label.

session.type("search query", ref="e5", delay=50)
session.type("hello", label="Search")

select(value) #

Select a dropdown option by value. Target the select element by ref, text, or label.

session.select("us", label="Country")

check() #

Toggle a checkbox or radio button. Target by ref, text, or label.

session.check(label="I agree to the terms")
session.check(ref="cb3", checked=False)

scroll() #

Scroll the page or scroll an element into view. Target by ref, text, or label.

session.scroll(to="bottom")
session.scroll(direction="down", amount=500)
session.scroll(text="Footer section")

wait() #

Wait for a duration, CSS selector, visible text, or a JavaScript expression to become truthy.

session.wait(ms=2000)
session.wait(selector=".loaded", timeout=10000)
session.wait(until_js="document.querySelectorAll('.item').length > 5")

upload(files) #

Upload files to a file input. Target by ref, text, or label.

session.upload(["https://example.com/file.pdf"], ref="file1")
session.upload(["https://example.com/photo.jpg"], label="Upload photo")

pdf() #

Generate a PDF of the page. Supports format, landscape, background, scale, and margin options.

import base64

result = session.pdf(format="A4", landscape=True, scale=0.8,
    margin={"top": "1cm", "bottom": "1cm"})
pdf_data = base64.b64decode(result.media[0].data)
with open("page.pdf", "wb") as f:
    f.write(pdf_data)

execute_js(code) #

Run JavaScript code in the browser. The result is stored in the extraction under the specified key.

result = session.execute_js("return document.title")
print(result.extraction["js_result"])

# With custom result key and timeout
result = session.execute_js(
    "return document.querySelectorAll('a').length",
    result_key="link_count", timeout=5000
)