> ## Documentation Index
> Fetch the complete documentation index at: https://skyvern.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Page actions

> AI and selector-based actions on a page: act, extract, validate, click, fill and more.

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.

<CodeGroup>
  ```python Python theme={null}
  await page.act(
      prompt: str,
      skip_refresh: bool = False,
      use_economy_tree: bool = False,
  ) -> None
  ```

  ```typescript TypeScript theme={null}
  page.act(prompt: string): Promise<void>
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `prompt` | `prompt` | `str` | Yes | — | Natural language description of the action to perform. |
| `skip_refresh` | — | `bool` | No | `False` | |
| `use_economy_tree` | — | `bool` | No | `False` | |

**Returns** `None` · TypeScript `Promise<void>`

**Example**

<CodeGroup>
  ```python Python theme={null}
  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())
  ```

  ```typescript TypeScript theme={null}
  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();
  ```
</CodeGroup>

***

### page.extract

Extract structured data from the page using AI.

<CodeGroup>
  ```python Python theme={null}
  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
  ```

  ```typescript TypeScript theme={null}
  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>
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `prompt` | `prompt` | `str` | Yes | — | Natural language description of what data to extract. |
| `schema` | `schema` | `dict[str, Any] \| list \| str \| None` | No | `None` | JSON Schema defining the structure of data to extract. |
| `error_code_mapping` | `errorCodeMapping` | `dict[str, str] \| None` | No | `None` | Mapping of error codes to custom error messages. |
| `intention` | `intention` | `str \| None` | No | `None` | Additional context about the extraction intent. |
| — | `data` | `string \| Record<string, unknown>` | No | — | TypeScript only. |

**Returns** `dict[str, Any] \| list \| str \| None` · TypeScript `Promise<Record<string, unknown> \| unknown[] \| string \| null>` — Extracted data matching the provided schema, or None if extraction fails.

**Example**

<CodeGroup>
  ```python Python theme={null}
  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())
  ```

  ```typescript TypeScript theme={null}
  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();
  ```
</CodeGroup>

***

### page.validate

Validate the current page state using AI.

<CodeGroup>
  ```python Python theme={null}
  await page.validate(prompt: str, model: dict[str, Any] | str | None = None) -> bool
  ```

  ```typescript TypeScript theme={null}
  page.validate(prompt: string, model?: Record<string, unknown> | string): Promise<boolean>
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `prompt` | `prompt` | `str` | Yes | — | Validation criteria or condition to check |
| `model` | `model` | `dict[str, Any] \| str \| None` | No | `None` | Optional model configuration. Can be either: - A dict with model configuration (e.g., \{"model\_name": "gemini-2.5-flash-lite", "max\_tokens": 2048}) - A string with just the model name (e.g., "gpt-4") |

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

**Example**

<CodeGroup>
  ```python Python theme={null}
  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())
  ```

  ```typescript TypeScript theme={null}
  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();
  ```
</CodeGroup>

***

### 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.

<CodeGroup>
  ```python Python theme={null}
  await page.prompt(
      prompt: str,
      schema: dict[str, Any] | None = None,
      model: dict[str, Any] | str | None = None,
  ) -> dict[str, Any] | list | str | None
  ```

  ```typescript TypeScript theme={null}
  page.prompt(prompt: string, schema?: Record<string, unknown>, model?: Record<string, unknown> | string): Promise<Record<string, unknown> | unknown[] | string | null>
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `prompt` | `prompt` | `str` | Yes | — | The prompt to send to the LLM |
| `schema` | `schema` | `dict[str, Any] \| None` | No | `None` | Optional JSON schema to structure the response. If provided, the LLM response will be validated against this schema. |
| `model` | `model` | `dict[str, Any] \| str \| None` | No | `None` | Optional model configuration. Can be either: - A dict with model configuration (e.g., \{"model\_name": "gemini-2.5-flash-lite", "max\_tokens": 2048}) - A string with just the model name (e.g., "gemini-2.5-flash-lite") |

**Returns** `dict[str, Any] \| list \| str \| None` · TypeScript `Promise<Record<string, unknown> \| unknown[] \| string \| null>` — LLM response structured according to the schema if provided, or unstructured response otherwise.

**Example**

<CodeGroup>
  ```python Python theme={null}
  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())
  ```

  ```typescript TypeScript theme={null}
  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();
  ```
</CodeGroup>

***

### page.classify

Classify the current page state against named options using a tiered cascade.

This method uses a three-tier approach to minimize cost:

1. URL pattern matching against current URL (FREE)
2. Text substring check in page content (FREE)
3. LLM-based classification as last resort (\~\$0.001)

<Note>Python only: the TypeScript SDK has no equivalent.</Note>

<CodeGroup>
  ```python Python theme={null}
  await page.classify(
      options: dict[str, str],
      url_patterns: dict[str, str] | None = None,
      text_patterns: dict[str, str | list[str]] | None = None,
  ) -> str
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `options` | — | `dict[str, str]` | Yes | — | Dict mapping option keys to descriptions. e.g. \{"eligible": "The page shows eligibility confirmation", "not\_eligible": "The page shows a rejection message"} |
| `url_patterns` | — | `dict[str, str] \| None` | No | `None` | Optional dict mapping option keys to regex patterns to match against the current URL. |
| `text_patterns` | — | `dict[str, str \| list[str]] \| None` | No | `None` | Optional dict mapping option keys to text substrings to search for in the page's extracted text. |

**Returns** `str` — The matching option key, or "UNKNOWN" if no option matches.

**Example**

<CodeGroup>
  ```python Python theme={null}
  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.classify(
          options={
              "logged_in": "The page shows the account dashboard",
              "logged_out": "The page shows a sign-in form",
          },
      )
      print(result)
      await browser.close()


  asyncio.run(main())
  ```
</CodeGroup>

***

### 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.

<Note>Python only: the TypeScript SDK has no equivalent.</Note>

<CodeGroup>
  ```python Python theme={null}
  page.locator(
      selector: str | None = None,
      *,
      prompt: str | None = None,
      ai: str | None = 'fallback',
      **kwargs: Any,
  ) -> Locator
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `selector` | — | `str \| None` | No | `None` | CSS selector for the target element. |
| `prompt` | — | `str \| None` | No | `None` | Natural language description of which element to locate. |
| `ai` | — | `str \| None` | No | `'fallback'` | AI behavior mode. Defaults to "fallback" which tries selector first, then AI. |
| `**kwargs` | — | `Any` | No | — | All Playwright locator parameters (has\_text, has, etc.) |

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

**Example**

<CodeGroup>
  ```python Python theme={null}
  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())
  ```
</CodeGroup>

***

### page.element\_fallback

Activate the AI agent from the CURRENT page position to achieve a goal.

Instead of re-running the entire block when cached code encounters an unknown
state, this method activates the AI agent from the current page position.
Much cheaper than a full block re-execution.

<Note>Python only: the TypeScript SDK has no equivalent.</Note>

<CodeGroup>
  ```python Python theme={null}
  await page.element_fallback(
      navigation_goal: str,
      max_steps: int = 5,
      validate_first: bool = False,
  ) -> None
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `navigation_goal` | — | `str` | Yes | — | The goal for the AI agent to achieve from the current page. |
| `max_steps` | — | `int` | No | `5` | Maximum number of agent steps before giving up. Defaults to 5. |
| `validate_first` | — | `bool` | No | `False` | When True, run an AI validation before the first action to short-circuit if the page already satisfies the goal. Defaults to False because the documented call site (else branch of `classify`) cannot be on the success state — pass True for defensive calls that may invoke this on a possibly-complete page. |

**Returns** `None`

**Example**

<CodeGroup>
  ```python Python theme={null}
  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.element_fallback(navigation_goal="Open the most recent invoice")
      await browser.close()


  asyncio.run(main())
  ```
</CodeGroup>

## 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

<CodeGroup>
  ```python Python theme={null}
  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
  ```

  ```typescript TypeScript theme={null}
  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>
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `selector` | `selector` | `str \| None` | No | `None` | CSS selector for the target element. |
| `prompt` | `prompt` | `str \| None` | No | `None` | Natural language description of which element to click. |
| `ai` | — | `str \| None` | No | `'fallback'` | AI behavior mode. Defaults to "fallback" which tries selector first, then AI. |
| `mode` | — | `str \| None` | No | `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. |
| `desired_state` | — | `bool \| None` | No | `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"`. |
| `**kwargs` | — | `Any` | No | — | All Playwright click parameters (timeout, force, modifiers, etc.) |
| — | `options` | `Parameters<Page["click"]>[1]` | No | — | Playwright options for this call. |

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

**Example**

<CodeGroup>
  ```python Python theme={null}
  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())
  ```

  ```typescript TypeScript theme={null}
  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();
  ```
</CodeGroup>

***

### 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

<CodeGroup>
  ```python Python theme={null}
  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
  ```

  ```typescript TypeScript theme={null}
  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>
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `selector` | `selector` | `str \| None` | No | `None` | CSS selector for the target input element. |
| `value` | `value` | `str \| None` | No | `None` | The text value to input into the field. |
| `prompt` | `prompt` | `str \| None` | No | `None` | Natural language description of which field to fill and what value. |
| `ai` | — | `str \| None` | No | `'fallback'` | AI behavior mode. Defaults to "fallback" which tries selector first, then AI. |
| `mode` | — | `str \| None` | No | `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. |
| `totp_identifier` | — | `str \| None` | No | `None` | TOTP identifier for time-based one-time password fields. |
| `totp_url` | — | `str \| None` | No | `None` | URL to fetch TOTP codes from for authentication. |
| — | `options` | `Parameters<Page["fill"]>[2]` | No | — | Playwright options for this call. |

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

**Example**

<CodeGroup>
  ```python Python theme={null}
  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())
  ```

  ```typescript TypeScript theme={null}
  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();
  ```
</CodeGroup>

***

### 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

<CodeGroup>
  ```python Python theme={null}
  await page.select_option(
      selector: str | None = None,
      value: str | None = None,
      *,
      prompt: str | None = None,
      ai: str | None = 'fallback',
  ) -> str | None
  ```

  ```typescript TypeScript theme={null}
  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>
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `selector` | `selector` | `str \| None` | No | `None` | CSS selector for the target select/dropdown element. |
| `value` | `value` | `str \| None` | No | `None` | The option value to select. |
| `prompt` | `prompt` | `str \| None` | No | `None` | Natural language description of which option to select. |
| `ai` | — | `str \| None` | No | `'fallback'` | AI behavior mode. Defaults to "fallback" which tries selector first, then AI. |
| — | `values` | `string \| string[]` | No | — | TypeScript only. |
| — | `options` | `Parameters<Page["selectOption"]>[2]` | No | — | Playwright options for this call. |

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

**Example**

<CodeGroup>
  ```python Python theme={null}
  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())
  ```

  ```typescript TypeScript theme={null}
  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();
  ```
</CodeGroup>

***

### 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.

<Note>Python only: the TypeScript SDK has no equivalent.</Note>

<CodeGroup>
  ```python Python theme={null}
  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
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `selector` | — | `str \| None` | No | `None` | CSS selector for the input. |
| `value` | — | `str \| None` | No | `None` | The text to enter. |
| `ai` | — | `str \| None` | No | `'fallback'` | AI behavior mode. Defaults to "fallback", which tries the selector first, then AI. |
| `prompt` | — | `str \| None` | No | `None` | Natural language description of which input to type into. |
| `totp_identifier` | — | `str \| None` | No | `None` | Identifier of the 2FA code to type, when `value` is a TOTP placeholder. |
| `totp_url` | — | `str \| None` | No | `None` | URL Skyvern calls to fetch the 2FA code, when `value` is a TOTP placeholder. |
| `**kwargs` | — | `Any` | No | — | Playwright options such as `timeout`. |

**Returns** `str` — The value that was entered.

**Example**

<CodeGroup>
  ```python Python theme={null}
  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())
  ```
</CodeGroup>

***

### page.hover

Move the mouse over the element identified by `selector`.

<Note>Python only: the TypeScript SDK has no equivalent.</Note>

<CodeGroup>
  ```python Python theme={null}
  await page.hover(
      selector: str,
      *,
      timeout: float = 5000,
      hold_seconds: float = 0.0,
      intention: str | None = None,
  ) -> str
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `selector` | — | `str` | Yes | — | CSS selector for the element. |
| `timeout` | — | `float` | No | `5000` | Maximum time to wait for the element, in milliseconds. |
| `hold_seconds` | — | `float` | No | `0.0` | How long to keep the mouse over the element, in seconds. |
| `intention` | — | `str \| None` | No | `None` | Description of why you are hovering, recorded with the action. |

**Returns** `str` — The selector that was hovered.

**Example**

<CodeGroup>
  ```python Python theme={null}
  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())
  ```
</CodeGroup>

***

### page.upload\_file

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

<Note>Python only: the TypeScript SDK has no equivalent.</Note>

<CodeGroup>
  ```python Python theme={null}
  await page.upload_file(
      selector: str | None = None,
      files: str | None = None,
      *,
      prompt: str | None = None,
      ai: str | None = 'fallback',
  ) -> str
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `selector` | — | `str \| None` | No | `None` | CSS selector for the file input. |
| `files` | — | `str \| None` | No | `None` | URL of the file to upload. One file per call. |
| `prompt` | — | `str \| None` | No | `None` | Natural language description of which file input to use. |
| `ai` | — | `str \| None` | No | `'fallback'` | 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. |

**Returns** `str` — The file URL that was uploaded.

**Example**

<CodeGroup>
  ```python Python theme={null}
  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())
  ```
</CodeGroup>

***

### page.keypress

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

<Note>Python only: the TypeScript SDK has no equivalent.</Note>

<CodeGroup>
  ```python Python theme={null}
  await page.keypress(keys: list[str], hold: bool = False, duration: float = 0) -> None
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `keys` | — | `list[str]` | Yes | — | Keys to press, using Playwright key names. |
| `hold` | — | `bool` | No | `False` | Hold the keys down for `duration` seconds instead of tapping them. |
| `duration` | — | `float` | No | `0` | How long to hold the keys, in seconds, when `hold` is true. |

**Returns** `None`

**Example**

<CodeGroup>
  ```python Python theme={null}
  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())
  ```
</CodeGroup>

***

### page.scroll

Scroll the page by a number of pixels.

<Note>Python only: the TypeScript SDK has no equivalent.</Note>

<CodeGroup>
  ```python Python theme={null}
  await page.scroll(scroll_x: int, scroll_y: int) -> None
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `scroll_x` | — | `int` | Yes | — | Pixels to scroll horizontally (negative scrolls left). |
| `scroll_y` | — | `int` | Yes | — | Pixels to scroll vertically (negative scrolls up). |

**Returns** `None`

**Example**

<CodeGroup>
  ```python Python theme={null}
  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())
  ```
</CodeGroup>

***

### page.drag

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

<Note>Python only: the TypeScript SDK has no equivalent.</Note>

<CodeGroup>
  ```python Python theme={null}
  await page.drag(start_x: int, start_y: int, path: list[tuple[int, int]]) -> None
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `start_x` | — | `int` | Yes | — | Horizontal start position in pixels. |
| `start_y` | — | `int` | Yes | — | Vertical start position in pixels. |
| `path` | — | `list[tuple[int, int]]` | Yes | — | Points `(x, y)` to drag through, ending where the mouse is released. |

**Returns** `None`

**Example**

<CodeGroup>
  ```python Python theme={null}
  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())
  ```
</CodeGroup>

***

### page.move

Move the mouse cursor to a point on the page.

<Note>Python only: the TypeScript SDK has no equivalent.</Note>

<CodeGroup>
  ```python Python theme={null}
  await page.move(x: int, y: int) -> None
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `x` | — | `int` | Yes | — | Horizontal position in pixels from the left of the viewport. |
| `y` | — | `int` | Yes | — | Vertical position in pixels from the top of the viewport. |

**Returns** `None`

**Example**

<CodeGroup>
  ```python Python theme={null}
  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())
  ```
</CodeGroup>

***

### page.wait

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

<Note>Python only: the TypeScript SDK has no equivalent.</Note>

<CodeGroup>
  ```python Python theme={null}
  await page.wait(seconds: float | None = None) -> None
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `seconds` | — | `float \| None` | No | `None` | How long to wait, in seconds. |

**Returns** `None`

**Example**

<CodeGroup>
  ```python Python theme={null}
  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())
  ```
</CodeGroup>

***

### page.download\_file

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

<Note>Python only: the TypeScript SDK has no equivalent.</Note>

<CodeGroup>
  ```python Python theme={null}
  await page.download_file(
      file_name: str | None = None,
      download_url: str | None = None,
  ) -> str
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `file_name` | — | `str \| None` | No | `None` | The original file name (for logging/reference). Defaults to UUID if empty. |
| `download_url` | — | `str \| None` | No | `None` | The URL to download the file from. |

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

**Example**

<CodeGroup>
  ```python Python theme={null}
  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())
  ```
</CodeGroup>

***

### page.reload\_page

Reload the current page, recorded as an action.

<Note>Python only: the TypeScript SDK has no equivalent.</Note>

<CodeGroup>
  ```python Python theme={null}
  await page.reload_page() -> None
  ```
</CodeGroup>

**Returns** `None`

**Example**

<CodeGroup>
  ```python Python theme={null}
  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())
  ```
</CodeGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.