Page actions

A Skyvern page is a Playwright Page with AI methods added. Every Playwright method still works; the methods below are the ones Skyvern adds or extends. Most accept a CSS selector, a natural-language prompt, or both (the selector is tried first and AI is the fallback).

AI methods

page.act

Perform an action on the page using AI based on a natural language prompt.

await page.act(
    prompt: str,
    skip_refresh: bool = False,
    use_economy_tree: bool = False,
) -> None

page.act(prompt: string): Promise<void>

Parameters

str

required

Natural language description of the action to perform.

bool

Default: False · Python only

bool

Default: False · Python only

Returns None · TypeScript Promise<void> Example

import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    browser = await skyvern.launch_cloud_browser()
    page = await browser.get_working_page()
    await page.goto("https://example.com")
    await page.act(prompt="Click the 'Sign in' button")
    await browser.close()


asyncio.run(main())

import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const browser = await skyvern.launchCloudBrowser();
const page = await browser.getWorkingPage();
await page.goto("https://example.com");
await page.act("Click the 'Sign in' button");
await browser.close();

page.extract

Extract structured data from the page using AI.

await page.extract(
    prompt: str,
    schema: dict[str, Any] | list | str | None = None,
    error_code_mapping: dict[str, str] | None = None,
    intention: str | None = None,
) -> dict[str, Any] | list | str | None

page.extract(options: { prompt: string; schema?: Record<string, unknown> | unknown[] | string; errorCodeMapping?: Record<string, string>; intention?: string; data?: string | Record<string, unknown>; }): Promise<Record<string, unknown> | unknown[] | string | null>

Parameters

str

required

Natural language description of what data to extract.

dict[str, Any] | list | str | None

JSON Schema defining the structure of data to extract.Default: None

dict[str, str] | None

Mapping of error codes to custom error messages.Default: None · TypeScript: errorCodeMapping

str | None

Additional context about the extraction intent.Default: None

string | Record<string, unknown>

TypeScript only

import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    browser = await skyvern.launch_cloud_browser()
    page = await browser.get_working_page()
    await page.goto("https://example.com")
    result = await page.extract(prompt="Extract the title and price of every product on the page")
    print(result)
    await browser.close()


asyncio.run(main())

import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const browser = await skyvern.launchCloudBrowser();
const page = await browser.getWorkingPage();
await page.goto("https://example.com");
const result = await page.extract({
    prompt: "Extract the title and price of every product on the page",
});
console.log(result);
await browser.close();

page.validate

Validate the current page state using AI.

await page.validate(prompt: str, model: dict[str, Any] | str | None = None) -> bool

page.validate(prompt: string, model?: Record<string, unknown> | string): Promise<boolean>

Parameters

str

required

Validation criteria or condition to check

dict[str, Any] | str | None

Optional model configuration. Can be either: - A dict with model configuration (e.g., {“model_name”: “gemini-3.0-flash”, “max_tokens”: 2048}) - A string with just the model name (e.g., “gpt-4”)Default: None

Returns bool · TypeScript Promise<boolean> — True if validation passes, False otherwise Example

import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    browser = await skyvern.launch_cloud_browser()
    page = await browser.get_working_page()
    await page.goto("https://example.com")
    result = await page.validate(prompt="The user is signed in")
    print(result)
    await browser.close()


asyncio.run(main())

import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const browser = await skyvern.launchCloudBrowser();
const page = await browser.getWorkingPage();
await page.goto("https://example.com");
const result = await page.validate("The user is signed in");
console.log(result);
await browser.close();

page.prompt

Send a prompt to the LLM and get a response based on the provided schema. This method allows you to interact with the LLM directly without requiring page context. It’s useful for making decisions, generating text, or processing information using AI.

await page.prompt(
    prompt: str,
    schema: dict[str, Any] | None = None,
    model: dict[str, Any] | str | None = None,
) -> dict[str, Any] | list | str | None

page.prompt(prompt: string, schema?: Record<string, unknown>, model?: Record<string, unknown> | string): Promise<Record<string, unknown> | unknown[] | string | null>

Parameters

str

required

The prompt to send to the LLM

dict[str, Any] | None

Optional JSON schema to structure the response. If provided, the LLM response will be validated against this schema.Default: None

dict[str, Any] | str | None

import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    browser = await skyvern.launch_cloud_browser()
    page = await browser.get_working_page()
    await page.goto("https://example.com")
    result = await page.prompt(prompt="What is the main heading on this page?")
    print(result)
    await browser.close()


asyncio.run(main())

import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const browser = await skyvern.launchCloudBrowser();
const page = await browser.getWorkingPage();
await page.goto("https://example.com");
const result = await page.prompt("What is the main heading on this page?");
console.log(result);
await browser.close();

page.locator

Get a Playwright locator using a CSS selector, AI-powered prompt, or both. This method extends Playwright’s locator() with AI capabilities. It supports three modes:

Selector-based: Get locator using CSS selector (standard Playwright behavior)
AI-powered: Use natural language to describe the element (returns lazy AILocator)
Fallback mode (default): Try the selector first, fall back to AI if it fails

The AI-powered locator is lazy - it only calls ai_locate_element when you actually use the locator (e.g., when you call .click(), .fill(), etc.). Note that using this AI locator lookup with prompt only works for elements you can interact with on the page.

Python only: the TypeScript SDK has no equivalent.

page.locator(
    selector: str | None = None,
    *,
    prompt: str | None = None,
    ai: str | None = 'fallback',
    **kwargs: Any,
) -> Locator

Parameters

str | None

CSS selector for the target element.Default: None

str | None

Natural language description of which element to locate.Default: None

str | None

AI behavior mode. Defaults to “fallback” which tries selector first, then AI.Default: 'fallback'

Any

All Playwright locator parameters (has_text, has, etc.)Sent only when you pass it

Returns Locator — A Playwright Locator object (or AILocator proxy that acts like one). Example

import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    browser = await skyvern.launch_cloud_browser()
    page = await browser.get_working_page()
    await page.goto("https://example.com")
    result = page.locator(prompt="the search box")
    print(result)
    await browser.close()


asyncio.run(main())

Element actions

page.click

Click an element using a CSS selector, AI-powered prompt matching, or both. This method supports three modes:

Selector-based: Click the element matching the CSS selector
AI-powered: Use natural language to describe which element to click
Fallback mode (default): Try the selector first, fall back to AI if it fails

await page.click(
    selector: str | None = None,
    *,
    prompt: str | None = None,
    ai: str | None = 'fallback',
    mode: str | None = None,
    desired_state: bool | None = None,
    **kwargs: Any,
) -> str | None

page.click(selector: string, options?: Parameters<Page["click"]>[1]): Promise<void>
page.click(options: { prompt: string; } & Partial<Parameters<Page["click"]>[1]>): Promise<void>
page.click(selector: string, options: { prompt: string; } & Partial<Parameters<Page["click"]>[1]>): Promise<void>

Parameters

str | None

CSS selector for the target element.Default: None

str | None

Natural language description of which element to click.Default: None

str | None

AI behavior mode. Defaults to “fallback” which tries selector first, then AI.Default: 'fallback' · Python only

str | None

When "direct", perform a raw Playwright click with no AI fallback or element preparation. The action is still recorded in the DB so it appears in the timeline.Default: None · Python only

bool | None

Level-triggered toggle intent recorded with the action. When set, a selector-first click is suppressed if the control already holds that state, so a replay never toggles an already-satisfied control back off. Ignored by mode="direct".Default: None · Python only

Any

All Playwright click parameters (timeout, force, modifiers, etc.)Sent only when you pass it · Python only

Parameters<Page["click"]>[1]

Playwright options for this call.TypeScript only

Returns str | None · TypeScript Promise<void> — The selector string that was successfully used to click the element, or None. Example

import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    browser = await skyvern.launch_cloud_browser()
    page = await browser.get_working_page()
    await page.goto("https://example.com")
    result = await page.click(prompt="Click the 'Sign in' button")
    print(result)
    await browser.close()


asyncio.run(main())

import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const browser = await skyvern.launchCloudBrowser();
const page = await browser.getWorkingPage();
await page.goto("https://example.com");
await page.click({ prompt: "Click the 'Sign in' button" });
await browser.close();

page.fill

Fill an input field using a CSS selector, AI-powered prompt matching, or both. This method supports three modes:

Selector-based: Fill the input field with a value using CSS selector
AI-powered: Use natural language prompt (AI extracts value from prompt)
Fallback mode (default): Try the selector first, fall back to AI if it fails

await page.fill(
    selector: str | None = None,
    value: str | None = None,
    *,
    prompt: str | None = None,
    ai: str | None = 'fallback',
    mode: str | None = None,
    totp_identifier: str | None = None,
    totp_url: str | None = None,
) -> str

page.fill(selector: string, value: string, options?: Parameters<Page["fill"]>[2]): Promise<void>
page.fill(options: { prompt: string; value?: string; } & Partial<Parameters<Page["fill"]>[2]>): Promise<void>
page.fill(selector: string, value: string, options: { prompt: string; } & Partial<Parameters<Page["fill"]>[2]>): Promise<void>

Parameters

str | None

CSS selector for the target input element.Default: None

str | None

The text value to input into the field.Default: None

str | None

Natural language description of which field to fill and what value.Default: None

str | None

AI behavior mode. Defaults to “fallback” which tries selector first, then AI.Default: 'fallback' · Python only

str | None

When "direct", perform a raw Playwright fill with no AI fallback or element preparation. The action is still recorded in the DB so it appears in the timeline.Default: None · Python only

str | None

TOTP identifier for time-based one-time password fields.Default: None · Python only

str | None

URL to fetch TOTP codes from for authentication.Default: None · Python only

Parameters<Page["fill"]>[2]

Playwright options for this call.TypeScript only

Returns str · TypeScript Promise<void> — The value that was successfully filled into the field. Example

import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    browser = await skyvern.launch_cloud_browser()
    page = await browser.get_working_page()
    await page.goto("https://example.com")
    result = await page.fill(prompt="the email field", value="jane@example.com")
    print(result)
    await browser.close()


asyncio.run(main())

import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const browser = await skyvern.launchCloudBrowser();
const page = await browser.getWorkingPage();
await page.goto("https://example.com");
await page.fill({ prompt: "the email field", value: "jane@example.com" });
await browser.close();

page.select_option

Select an option from a dropdown using a CSS selector, AI-powered prompt matching, or both. This method supports three modes:

Selector-based: Select the option with a value using CSS selector
AI-powered: Use natural language prompt (AI extracts value from prompt)
Fallback mode (default): Try the selector first, fall back to AI if it fails

await page.select_option(
    selector: str | None = None,
    value: str | None = None,
    *,
    prompt: str | None = None,
    ai: str | None = 'fallback',
) -> str | None

page.selectOption(selector: string, values: string | string[], options?: Parameters<Page["selectOption"]>[2]): Promise<void>
page.selectOption(options: { prompt: string; value?: string; } & Partial<Parameters<Page["selectOption"]>[2]>): Promise<void>
page.selectOption(selector: string, values: string | string[], options: { prompt: string; } & Partial<Parameters<Page["selectOption"]>[2]>): Promise<void>

Parameters

str | None

CSS selector for the target select/dropdown element.Default: None

str | None

The option value to select.Default: None

str | None

Natural language description of which option to select.Default: None

str | None

AI behavior mode. Defaults to “fallback” which tries selector first, then AI.Default: 'fallback' · Python only

string | string[]

TypeScript only

Parameters<Page["selectOption"]>[2]

Playwright options for this call.TypeScript only

Returns str | None · TypeScript Promise<void> — The value that was successfully selected. Example

import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    browser = await skyvern.launch_cloud_browser()
    page = await browser.get_working_page()
    await page.goto("https://example.com")
    result = await page.select_option(prompt="the country dropdown", value="Canada")
    print(result)
    await browser.close()


asyncio.run(main())

import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const browser = await skyvern.launchCloudBrowser();
const page = await browser.getWorkingPage();
await page.goto("https://example.com");
await page.selectOption({ prompt: "the country dropdown", value: "Canada" });
await browser.close();

page.type

Enter text into an input using a selector, AI, or both. Behaves the same as fill. With a selector, the value is set in one step (Playwright’s fill), not typed key by key. For inputs that need real key events, use fill_autocomplete, keypress, or press_sequentially on a Playwright locator.

Python only: the TypeScript SDK has no equivalent.

await page.type(
    selector: str | None = None,
    value: str | None = None,
    ai: str | None = 'fallback',
    prompt: str | None = None,
    totp_identifier: str | None = None,
    totp_url: str | None = None,
    **kwargs: Any,
) -> str

Parameters

str | None

CSS selector for the input.Default: None

str | None

The text to enter.Default: None

str | None

AI behavior mode. Defaults to “fallback”, which tries the selector first, then AI.Default: 'fallback'

str | None

Natural language description of which input to type into.Default: None

str | None

Identifier of the 2FA code to type, when value is a TOTP placeholder.Default: None

str | None

URL Skyvern calls to fetch the 2FA code, when value is a TOTP placeholder.Default: None

Any

Playwright options such as timeout.Sent only when you pass it

Returns str — The value that was entered. Example

import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    browser = await skyvern.launch_cloud_browser()
    page = await browser.get_working_page()
    await page.goto("https://example.com")
    result = await page.type(selector="#search", value="skyvern")
    print(result)
    await browser.close()


asyncio.run(main())

page.hover

Move the mouse over the element identified by selector.

Python only: the TypeScript SDK has no equivalent.

await page.hover(
    selector: str,
    *,
    timeout: float = 5000,
    hold_seconds: float = 0.0,
    intention: str | None = None,
) -> str

Parameters

str

required

CSS selector for the element.

float

Maximum time to wait for the element, in milliseconds.Default: 5000

float

How long to keep the mouse over the element, in seconds.Default: 0.0

str | None

Description of why you are hovering, recorded with the action.Default: None

Returns str — The selector that was hovered. Example

import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    browser = await skyvern.launch_cloud_browser()
    page = await browser.get_working_page()
    await page.goto("https://example.com")
    result = await page.hover(selector="#account-menu")
    print(result)
    await browser.close()


asyncio.run(main())

page.upload_file

Upload a file to a file input, using a selector, AI, or both.

Python only: the TypeScript SDK has no equivalent.

await page.upload_file(
    selector: str | None = None,
    files: str | None = None,
    *,
    prompt: str | None = None,
    ai: str | None = 'fallback',
) -> str

Parameters

str | None

CSS selector for the file input.Default: None

str | None

URL of the file to upload. One file per call.Default: None

str | None

Natural language description of which file input to use.Default: None

str | None

AI behavior mode. With the default “fallback”, a selector-only call uploads through the selector. When a prompt is passed, the selector is tried first and AI then always runs the upload, using the selector only if it worked.Default: 'fallback'

Returns str — The file URL that was uploaded. Example

import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    browser = await skyvern.launch_cloud_browser()
    page = await browser.get_working_page()
    await page.goto("https://example.com")
    result = await page.upload_file(
        files="https://example.com/resume.pdf",
        prompt="the resume upload field",
    )
    print(result)
    await browser.close()


asyncio.run(main())

page.keypress

Press one or more keys, such as ["Enter"] or ["Control", "a"].

Python only: the TypeScript SDK has no equivalent.

await page.keypress(keys: list[str], hold: bool = False, duration: float = 0) -> None

Parameters

list[str]

required

Keys to press, using Playwright key names.

bool

Hold the keys down for duration seconds instead of tapping them.Default: False

float

How long to hold the keys, in seconds, when hold is true.Default: 0

Returns None Example

import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    browser = await skyvern.launch_cloud_browser()
    page = await browser.get_working_page()
    await page.goto("https://example.com")
    await page.keypress(keys=["Enter"])
    await browser.close()


asyncio.run(main())

page.scroll

Scroll the page by a number of pixels.

Python only: the TypeScript SDK has no equivalent.

await page.scroll(scroll_x: int, scroll_y: int) -> None

Parameters

int

required

Pixels to scroll horizontally (negative scrolls left).

int

required

Pixels to scroll vertically (negative scrolls up).

Returns None Example

import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    browser = await skyvern.launch_cloud_browser()
    page = await browser.get_working_page()
    await page.goto("https://example.com")
    await page.scroll(scroll_x=0, scroll_y=600)
    await browser.close()


asyncio.run(main())

page.drag

Drag with the mouse from a start point along a path of points.

Python only: the TypeScript SDK has no equivalent.

await page.drag(start_x: int, start_y: int, path: list[tuple[int, int]]) -> None

Parameters

int

required

Horizontal start position in pixels.

int

required

Vertical start position in pixels.

list[tuple[int, int]]

required

Points (x, y) to drag through, ending where the mouse is released.

Returns None Example

import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    browser = await skyvern.launch_cloud_browser()
    page = await browser.get_working_page()
    await page.goto("https://example.com")
    await page.drag(start_x=100, start_y=200, path=[[300, 200]])
    await browser.close()


asyncio.run(main())

page.move

Move the mouse cursor to a point on the page.

Python only: the TypeScript SDK has no equivalent.

await page.move(x: int, y: int) -> None

Parameters

int

required

Horizontal position in pixels from the left of the viewport.

int

required

Vertical position in pixels from the top of the viewport.

Returns None Example

import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    browser = await skyvern.launch_cloud_browser()
    page = await browser.get_working_page()
    await page.goto("https://example.com")
    await page.move(x=100, y=200)
    await browser.close()


asyncio.run(main())

page.wait

Pause the script for a fixed time, recorded as a wait action.

Python only: the TypeScript SDK has no equivalent.

await page.wait(seconds: float | None = None) -> None

Parameters

float | None

How long to wait, in seconds.Default: None

Returns None Example

import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    browser = await skyvern.launch_cloud_browser()
    page = await browser.get_working_page()
    await page.goto("https://example.com")
    await page.wait()
    await browser.close()


asyncio.run(main())

page.download_file

Download a file from a URL and save it locally during cached script replay.

Python only: the TypeScript SDK has no equivalent.

await page.download_file(
    file_name: str | None = None,
    download_url: str | None = None,
) -> str

Parameters

str | None

The original file name (for logging/reference). Defaults to UUID if empty.Default: None

str | None

The URL to download the file from.Default: None

Returns str — The local file path where the file was saved. Example

import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    browser = await skyvern.launch_cloud_browser()
    page = await browser.get_working_page()
    await page.goto("https://example.com")
    result = await page.download_file(download_url="https://example.com/invoice.pdf")
    print(result)
    await browser.close()


asyncio.run(main())

page.reload_page

Reload the current page, recorded as an action.

Python only: the TypeScript SDK has no equivalent.

await page.reload_page() -> None

Returns None Example

import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    browser = await skyvern.launch_cloud_browser()
    page = await browser.get_working_page()
    await page.goto("https://example.com")
    await page.reload_page()
    await browser.close()


asyncio.run(main())

SDK

Browser automation

API client

AI methods

page.act

page.extract

page.validate

page.prompt

page.locator

Element actions

page.click

page.fill

page.select_option

page.type

page.hover

page.upload_file

page.keypress

page.scroll

page.drag

page.move

page.wait

page.download_file

page.reload_page

​AI methods

​page.act

​page.extract

​page.validate

​page.prompt

​page.locator

​Element actions

​page.click

​page.fill

​page.select_option

​page.type

​page.hover

​page.upload_file

​page.keypress

​page.scroll

​page.drag

​page.move

​page.wait

​page.download_file

​page.reload_page

AI methods

page.act

page.extract

page.validate

page.prompt

page.locator

Element actions

page.click

page.fill

page.select_option

page.type

page.hover

page.upload_file

page.keypress

page.scroll

page.drag

page.move

page.wait

page.download_file

page.reload_page