Complete Reference (For LLMs)

# Requires Python 3.11+
pip install skyvern

import asyncio
from skyvern import Skyvern

async def main():
    client = Skyvern(api_key="YOUR_API_KEY")
    result = await client.run_task(
        prompt="Get the title of the top post on Hacker News",
        url="https://news.ycombinator.com",
        wait_for_completion=True,
    )
    print(result.output)

asyncio.run(main())

Skyvern(
    api_key: str,                          # Required
    base_url: str | None = None,           # Override for self-hosted deployments
    environment: SkyvernEnvironment = CLOUD,# CLOUD, STAGING, or LOCAL
    timeout: float | None = None,          # HTTP request timeout (seconds)
)

# Local mode (Python only - requires pip install "skyvern[local]")
# For local browser control, also run: python -m playwright install chromium
client = Skyvern.local()

# Launch / connect
browser = await client.launch_cloud_browser(timeout=60, proxy_location=None)
browser = await client.use_cloud_browser(timeout=60, proxy_location=None)
browser = await client.connect_to_cloud_browser_session("pbs_abc123")
browser = await client.connect_to_browser_over_cdp("http://localhost:9222")
browser = await client.launch_local_browser(headless=False, port=9222)  # Python only

# Get pages
page = await browser.get_working_page()   # Most recent page, or creates one
page = await browser.new_page()            # Always creates a new tab
page = await browser.get_page_for(pw_page) # Wrap existing Playwright Page (Python only)
await browser.close()                      # Close browser and cloud session

# act - freeform AI action
await page.act("Click the login button")

# extract - structured data extraction
data = await page.extract("Extract all products", schema={...})

# validate - page state assertion, returns bool
ok = await page.validate("User is logged in")

# prompt - ask LLM about the page
result = await page.prompt("What is the heading?", schema={...})

# locator - AI element locator returning chainable AILocator (Python only)
locator = page.locator(prompt="the submit button")
await locator.click()

# click - selector, AI, or both with fallback
await page.click("#submit-btn")
await page.click(prompt="Click the submit button")
await page.click("#submit-btn", prompt="Click submit")

# fill - selector, AI, or both with fallback
await page.fill("#email", value="user@example.com")
await page.fill(prompt="Fill email with user@example.com")

# select_option - selector, AI, or both with fallback
await page.select_option("#country", value="us")
await page.select_option(prompt="Select United States")

# type - character-by-character input (Python only)
await page.type("#search", value="query")

# hover (Python only)
await page.hover("#menu-item", intention="Hover over the menu")

# scroll (Python only)
await page.scroll(0, 500)

# upload_file (Python only)
await page.upload_file("#file-input", files="/path/to/file.pdf")

# fill_form - AI full form fill (Python only)
await page.fill_form(data={"name": "John", "email": "john@example.com"})

# fill_multipage_form - across page transitions (Python only)
await page.fill_multipage_form(data={...}, max_pages=5)

# fill_from_mapping - explicit field→value mapping (Python only)
await page.fill_from_mapping(form_fields=fields, mapping={0: "John"}, data={...})

# extract_form_fields - get all fields with metadata (Python only)
fields = await page.extract_form_fields()

# validate_mapping - verify mapping works (Python only)
is_valid = await page.validate_mapping(form_fields=fields, mapping={...}, prompt="Validate fields")

# fill_autocomplete - typeahead handling (Python only)
await page.fill_autocomplete(selector="#city", value="San Francisco")

# frame_switch - switch iframe context (Python only)
await page.frame_switch(selector="#payment-iframe")
page.frame_main()                    # back to main frame
frames = await page.frame_list()     # list all frames

# run_task
result = await page.agent.run_task("Fill out the form", data_extraction_schema={...}, max_steps=10, timeout=1800)

# login - supports skyvern, bitwarden, onepassword, azure_vault
await page.agent.login(credential_type=CredentialType.skyvern, credential_id="cred_123")

# download_files
result = await page.agent.download_files("Download the invoice PDF", download_suffix=".pdf")

# run_workflow
result = await page.agent.run_workflow("wpid_abc123", parameters={"key": "value"})

result = await client.run_task(
    prompt: str,                                # Required
    url: str | None = None,
    engine: RunEngine = RunEngine.skyvern_v1,
    wait_for_completion: bool = False,
    timeout: float = 1800,
    max_steps: int | None = None,
    data_extraction_schema: dict | str | None = None,
    browser_session_id: str | None = None,
    publish_workflow: bool = False,
    proxy_location: ProxyLocation | None = None,
    webhook_url: str | None = None,
    error_code_mapping: dict[str, str] | None = None,
    totp_identifier: str | None = None,
    totp_url: str | None = None,
    title: str | None = None,
    model: dict | None = None,
    user_agent: str | None = None,
    extra_http_headers: dict[str, str] | None = None,
    include_action_history_in_verification: bool | None = None,
    max_screenshot_scrolls: int | None = None,
    browser_address: str | None = None,
    run_with: str | None = None,
) -> TaskRunResponse

result = await client.run_workflow(
    workflow_id: str,                       # Required. Permanent ID (wpid_...).
    parameters: dict | None = None,
    wait_for_completion: bool = False,
    timeout: float = 1800,
    run_with: str | None = None,            # "code" or "agent"
    ai_fallback: bool | None = None,
    browser_session_id: str | None = None,
    browser_profile_id: str | None = None,
    proxy_location: ProxyLocation | None = None,
    max_steps_override: int | None = None,
    webhook_url: str | None = None,
    title: str | None = None,
    template: bool | None = None,
    totp_identifier: str | None = None,
    totp_url: str | None = None,
    user_agent: str | None = None,
    extra_http_headers: dict[str, str] | None = None,
    max_screenshot_scrolls: int | None = None,
    browser_address: str | None = None,
) -> WorkflowRunResponse

from skyvern.client.core import ApiError
from skyvern.client.errors import NotFoundError

try:
    run = await client.get_run("tsk_nonexistent")
except NotFoundError as e:
    print(e.status_code, e.body)    # 404
except ApiError as e:
    print(e.status_code, e.body)    # Any other HTTP error

from skyvern.client.core import RequestOptions

request_options=RequestOptions(
    timeout_in_seconds=120,
    max_retries=3,
    additional_headers={"x-custom-header": "value"},
)