Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
---
title: "Forms"
description: "Fill whole forms with AI, or extract fields and fill them from a mapping."
slug: sdk-reference/browser-automation/forms
keywords:
- "fill_form"
- "form filling"
- "autocomplete"
---
{/* Generated from the Skyvern SDK source (signatures and docstrings). Do not edit by hand; change the SDK docstrings. */}
Use `fill_form` to fill a form in one call. For more control, `extract_form_fields` lists the fields, `dynamic_field_map` maps your data onto them, and `fill_from_mapping` fills them.
---
## page.fill_form
Scan page for form fields, map data to fields via LLM, and fill them.
This is the primary SDK interface for form filling. It composes:
1. extract_form_fields() — scan all fields from the DOM (free)
2. dynamic_field_map() — one LLM call to map data to fields
3. validate_mapping() — one LLM call to check user conditions
4. fill_from_mapping() — fill via CSS selectors with AI fallback
<Note>Python only: the TypeScript SDK has no equivalent.</Note>
<CodeGroup>
```python Python
await page.fill_form(data: dict[str, Any], *, prompt: str = 'Fill out the form') -> None
```
</CodeGroup>
**Parameters**
<ParamField path={"data"} type={"dict[str, Any]"} required>
Dict of data keys/values to fill into the form.
</ParamField>
<ParamField path={"prompt"} type={"str"}>
User instructions for how to fill the form.
Default: `'Fill out the form'`
</ParamField>
**Returns** `None`
**Example**
<CodeGroup>
```python Python
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.fill_form(data={"email": "[email protected]", "full_name": "Jane Doe"})
await browser.close()
asyncio.run(main())
```
</CodeGroup>
---
## page.fill_multipage_form
Fill a multi-page form by looping: fill current page → click next → repeat.
Returns the number of pages filled. Stops when:
- No fillable form fields are found on the current page (e.g., Review page)
- The next button is not found (last page)
- max_pages is reached
- Wall-clock timeout is exceeded
<Note>Python only: the TypeScript SDK has no equivalent.</Note>
<CodeGroup>
```python Python
await page.fill_multipage_form(
data: dict[str, Any],
*,
prompt: str = 'Fill out the form',
next_button: str = 'button:has-text("Save and Continue"), button:has-text("Next"), button:has-text("Continue")',
max_pages: int = 10,
timeout_seconds: float = 300,
debug_dir: str | None = None,
) -> int
```
</CodeGroup>
**Parameters**
<ParamField path={"data"} type={"dict[str, Any]"} required>
Dict of data keys/values to fill into the form.
</ParamField>
<ParamField path={"prompt"} type={"str"}>
User instructions for how to fill the form.
Default: `'Fill out the form'`
</ParamField>
<ParamField path={"next_button"} type={"str"}>
CSS selector(s) for the next/continue button.
Default: `'button:has-text("Save and Continue"), button:has-text("Next"), button:has-text("Continue")'`
</ParamField>
<ParamField path={"max_pages"} type={"int"}>
Safety limit on number of pages to fill.
Default: `10`
</ParamField>
<ParamField path={"timeout_seconds"} type={"float"}>
Wall-clock timeout for the entire multi-page fill (default 5 min).
Default: `300`
</ParamField>
<ParamField path={"debug_dir"} type={"str | None"}>
Default: `None`
</ParamField>
**Returns** `int`
**Example**
<CodeGroup>
```python Python
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_multipage_form(
data={"email": "[email protected]", "full_name": "Jane Doe"},
)
print(result)
await browser.close()
asyncio.run(main())
```
</CodeGroup>
---
## page.extract_form_fields
Scan the page for visible form fields using DOM inspection (no LLM).
The base scanner handles standard HTML form elements (input, select,
textarea) and ARIA role-based groups. Platform-specific passes
(e.g., custom listbox buttons, multiselect widgets) are injected
at runtime via `AgentFunction.get_form_field_extraction_js()`.
Returns a list of field descriptors.
<Note>Python only: the TypeScript SDK has no equivalent.</Note>
<CodeGroup>
```python Python
await page.extract_form_fields() -> list[dict[str, Any]]
```
</CodeGroup>
**Returns** `list[dict[str, Any]]`
**Example**
<CodeGroup>
```python Python
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_form_fields()
print(result)
await browser.close()
asyncio.run(main())
```
</CodeGroup>
---
## page.dynamic_field_map
Map data to form fields via a single cheap text-only LLM call.
One LLM call sees ALL fields + ALL data and produces a complete mapping —
no deterministic matching, no caching, no accumulated state.
<Note>Python only: the TypeScript SDK has no equivalent.</Note>
<CodeGroup>
```python Python
await page.dynamic_field_map(
form_fields: list[dict[str, Any]],
data: dict[str, Any],
*,
prompt: str | None = None,
) -> dict[int, str | list | bool | None]
```
</CodeGroup>
**Parameters**
<ParamField path={"form_fields"} type={"list[dict[str, Any]]"} required>
Output of `extract_form_fields`.
</ParamField>
<ParamField path={"data"} type={"dict[str, Any]"} required>
Flat dict of data keys/values to map to form fields.
</ParamField>
<ParamField path={"prompt"} type={"str | None"}>
Default: `None`
</ParamField>
**Returns** `dict[int, str | list | bool | None]` — Mapping of 0-based field index -> value to fill (or None to skip).
**Example**
<CodeGroup>
```python Python
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")
fields = await page.extract_form_fields()
result = await page.dynamic_field_map(
form_fields=fields,
data={"email": "[email protected]", "full_name": "Jane Doe"},
)
print(result)
await browser.close()
asyncio.run(main())
```
</CodeGroup>
---
## page.fill_from_mapping
Fill form fields using a pre-computed mapping from `dynamic_field_map`.
Iterates over the mapping and fills each field using the appropriate
browser method based on field type. No LLM calls — pure execution.
<Note>Python only: the TypeScript SDK has no equivalent.</Note>
<CodeGroup>
```python Python
await page.fill_from_mapping(
form_fields: list[dict[str, Any]],
mapping: dict[int, str | list | bool | None],
data: dict[str, Any] | None = None,
) -> None
```
</CodeGroup>
**Parameters**
<ParamField path={"form_fields"} type={"list[dict[str, Any]]"} required>
Output of `extract_form_fields`.
</ParamField>
<ParamField path={"mapping"} type={"dict[int, str | list | bool | None]"} required>
Output of `dynamic_field_map` (index -> value).
</ParamField>
<ParamField path={"data"} type={"dict[str, Any] | None"}>
Original data dict for post-fill file upload matching.
Default: `None`
</ParamField>
**Returns** `None`
**Example**
<CodeGroup>
```python Python
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")
fields = await page.extract_form_fields()
mapping = await page.dynamic_field_map(fields, {"email": "[email protected]"})
await page.fill_from_mapping(form_fields=fields, mapping=mapping)
await browser.close()
asyncio.run(main())
```
</CodeGroup>
---
## page.validate_mapping
Validate the field mapping against the user's prompt/instructions.
Makes one LLM call that sees the prompt (user instructions),
the form fields, and what was mapped to each field. Returns True if
the run should complete, False if it should terminate.
This catches user directives like "terminate if you can't answer the
security clearance question" or "never fabricate answers — fail if
data is missing for required fields."
<Note>Python only: the TypeScript SDK has no equivalent.</Note>
<CodeGroup>
```python Python
await page.validate_mapping(
form_fields: list[dict[str, Any]],
mapping: dict[int, str | list | bool | None],
prompt: str | None,
) -> bool
```
</CodeGroup>
**Parameters**
<ParamField path={"form_fields"} type={"list[dict[str, Any]]"} required>
Output of `extract_form_fields`.
</ParamField>
<ParamField path={"mapping"} type={"dict[int, str | list | bool | None]"} required>
Output of `dynamic_field_map`.
</ParamField>
<ParamField path={"prompt"} type={"str | None"} required>
The user's instructions/prompt for this automation.
</ParamField>
**Returns** `bool` — True to complete, False to terminate.
**Example**
<CodeGroup>
```python Python
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")
fields = await page.extract_form_fields()
mapping = await page.dynamic_field_map(fields, {"email": "[email protected]"})
result = await page.validate_mapping(
form_fields=fields,
mapping=mapping,
prompt="Fill in the contact form",
)
print(result)
await browser.close()
asyncio.run(main())
```
</CodeGroup>
---
## page.fill_autocomplete
Fill an autocomplete input by typing a value and clicking the matching dropdown option.
Handles widgets like Google Places, autocomplete location fields, and other
autocomplete inputs where typing triggers a dropdown and the user must
select an option for the value to persist.
The flow:
1. Clear the field and type the value character-by-character (triggers autocomplete)
2. Wait for dropdown options to appear
3. Find the best-matching option by text similarity
4. Click it so the value is committed
If no dropdown options appear, falls back to the same behavior as `page.fill()`.
<Note>Python only: the TypeScript SDK has no equivalent.</Note>
<CodeGroup>
```python Python
await page.fill_autocomplete(
selector: str | None = None,
value: str | None = None,
*,
prompt: str | None = None,
ai: str | None = 'fallback',
option_selector: str | None = None,
wait_seconds: float = 1.5,
) -> str
```
</CodeGroup>
**Parameters**
<ParamField path={"selector"} type={"str | None"}>
CSS selector for the input field.
Default: `None`
</ParamField>
<ParamField path={"value"} type={"str | None"}>
The text to type (e.g. "San Francisco, CA").
Default: `None`
</ParamField>
<ParamField path={"prompt"} type={"str | None"}>
Natural language description for AI fallback.
Default: `None`
</ParamField>
<ParamField path={"ai"} type={"str | None"}>
AI behavior mode (same as fill). Defaults to "fallback".
Default: `'fallback'`
</ParamField>
<ParamField path={"option_selector"} type={"str | None"}>
CSS selector for the dropdown options. If not provided, tries common patterns: `[role="option"]`, `.pac-item`, `li[role="option"]`, `[data-option-id]`.
Default: `None`
</ParamField>
<ParamField path={"wait_seconds"} type={"float"}>
How long to wait for dropdown options to appear after typing. Defaults to 1.5 seconds.
Default: `1.5`
</ParamField>
**Returns** `str` — The value that was selected from the dropdown, or the typed value if no dropdown appeared.
**Example**
<CodeGroup>
```python Python
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_autocomplete(selector="#city", value="San Francisco")
print(result)
await browser.close()
asyncio.run(main())
```
</CodeGroup>