Task Parameters

This page covers all parameters you can pass to run_task. Only prompt is a required parameter.

Quick reference

Parameter	Type	Use this to
`prompt` (Required)	string	Give natural language instructions for the AI
`url`	string	Give a starting URL for the task
`engine`	string	Choose a different Agent model
`data_extraction_schema`	object	Get consistent, structured JSON output
`max_steps`	integer	Limit how long the Agent runs and cap costs
`proxy_location`	string \| object	Access geo-restricted content or reduce bot detection
`browser_session_id`	string	Maintain state (cookies, login) across multiple tasks
`totp_identifier`	string	Handle 2FA when pushing codes to Skyvern
`totp_url`	string	Have Skyvern fetch 2FA codes from your endpoint
`error_code_mapping`	object	Get custom error codes for programmatic handling
`webhook_url`	string	Get notified when the task completes
`title`	string	Label the task in the Skyvern UI
`extra_http_headers`	object	Add custom headers (e.g., Authorization) to browser requests
`publish_workflow`	boolean	Convert this task into a reusable workflow
`max_screenshot_scrolls`	integer	Capture lazy-loaded content in screenshots
`browser_address`	string	Connect to your own browser for local development
`include_action_history_in_verification`	boolean	Improve verification accuracy for multi-step forms
`run_with`	string	Choose whether to run with the AI agent or generated code
`model`	object	Configure model settings (e.g., temperature)

`prompt`

Required. Natural language instructions describing what the AI should do.

result = await client.run_task(
    prompt="Find the cheapest flight from NYC to LAX on March 15"
)

Be specific about your goal and what data you want extracted. The more detailed your prompt, the better the results.

`url`

The starting page for the automation. Skyvern navigates from here based on your prompt.

result = await client.run_task(
    prompt="Get the top headline",
    url="https://news.ycombinator.com"
)

If not provided, Skyvern attempts to determine an appropriate starting URL from your prompt.

`engine`

The AI engine that powers the task. These are not iterations—they’re suited for different purposes.

Engine	Description
`skyvern-2.0`	Default. Multi-objective, flexible, handles complex multi-step tasks. 85.85% on WebVoyager benchmark. Slower and more expensive.
`skyvern-1.0`	Single objective, precise, faster, cheaper. Best for simple tasks like form filling or single-page extraction.
`openai-cua`	OpenAI’s Computer Use Agent
`anthropic-cua`	Anthropic Claude Sonnet with computer use
`ui-tars`	UI-TARS model (Seed1.5-VL) via Doubao API

Use skyvern-1.0 when you have a clear, single goal and want faster, cheaper execution. Use skyvern-2.0 when the task requires flexibility or multiple steps.

result = await client.run_task(
    prompt="Fill out the contact form",
    engine="skyvern-1.0"
)

`data_extraction_schema`

A JSON Schema defining the structure of output data. Use this when you need consistent, typed responses.

result = await client.run_task(
    prompt="Find the top post on Hacker News",
    data_extraction_schema={
        "type": "object",
        "properties": {
            "title": {
                "type": "string",
                "description": "The title of the top post"
            },
            "points": {
                "type": "integer",
                "description": "Number of points"
            }
        }
    }
)

Without a schema, output format varies based on what the AI extracts. With a schema, output matches your defined structure.

`max_steps`

Maximum number of steps the task can take. The task fails if it exceeds this limit.

result = await client.run_task(
    prompt="Get the current stock price of AAPL",
    max_steps=10
)

On the cloud-hosted version, you’re billed per step. Set this to a reasonable value during development to cap costs.

Set max_steps during development to avoid runaway costs. A task that loops or gets stuck will keep consuming steps until it hits this limit.

`proxy_location`

Route browser traffic through a residential proxy in a specific location. Use this for geo-restricted content or to reduce bot detection. Country-level pools:

Value	Location
`RESIDENTIAL`	Random US residential (default)
`RESIDENTIAL_GB`	United Kingdom
`RESIDENTIAL_DE`	Germany
`RESIDENTIAL_FR`	France
`RESIDENTIAL_ES`	Spain
`RESIDENTIAL_IE`	Ireland
`RESIDENTIAL_IN`	India
`RESIDENTIAL_JP`	Japan
`RESIDENTIAL_AU`	Australia
`RESIDENTIAL_CA`	Canada
`RESIDENTIAL_BR`	Brazil
`RESIDENTIAL_MX`	Mexico
`RESIDENTIAL_AR`	Argentina
`RESIDENTIAL_NZ`	New Zealand
`RESIDENTIAL_ZA`	South Africa
`RESIDENTIAL_IT`	Italy
`RESIDENTIAL_NL`	Netherlands
`RESIDENTIAL_PH`	Philippines
`RESIDENTIAL_KR`	South Korea
`RESIDENTIAL_TR`	Turkey
`RESIDENTIAL_ISP`	ISP proxy
`US-CA`	California, US
`US-NY`	New York, US
`US-TX`	Texas, US
`US-FL`	Florida, US
`US-WA`	Washington, US
`NONE`	No proxy

result = await client.run_task(
    prompt="Get UK-specific pricing",
    proxy_location="RESIDENTIAL_GB"
)

Granular targeting (state/city level):

result = await client.run_task(
    prompt="Get California pricing",
    proxy_location={
        "country": "US",
        "subdivision": "CA",
        "city": "San Francisco"
    }
)

The full list of available proxy locations is shown above. Use NONE to disable proxies.

For geo-restricted sites, proxy_location is required—without it, you’ll get blocked or see wrong regional content (e.g., US prices instead of UK prices).

`browser_session_id`

Run the task in an existing persistent browser session. Use this to maintain state (cookies, localStorage) across multiple tasks.

result = await client.run_task(
    prompt="Extract account data",
    browser_session_id="pbs_123"
)

Browser sessions persist cookies, localStorage, and authentication state across multiple tasks.

`totp_identifier`

Identifier for TOTP codes when you push codes to Skyvern’s API. Use this for two-factor authentication during task execution.

result = await client.run_task(
    prompt="Log in and extract account balance",
    totp_identifier="my-2fa-credential"
)

TOTP codes are used for two-factor authentication during automated logins.

`totp_url`

URL that Skyvern calls to fetch TOTP codes when needed. Use this when Skyvern should retrieve codes from your endpoint.

result = await client.run_task(
    prompt="Log in and extract account balance",
    totp_url="https://your-server.com/totp"
)

TOTP codes are used for two-factor authentication during automated logins.

`error_code_mapping`

Map specific error conditions to custom error codes. Use this to make programmatic error handling easier.

result = await client.run_task(
    prompt="Log in and extract data",
    error_code_mapping={
        "login_failed": "The login credentials are incorrect or the account is locked",
        "maintenance_mode": "The website is down for maintenance"
    }
)

If Skyvern encounters a login failure matching your description, output contains {"error": "login_failed"} instead of a generic error message.

`webhook_url`

URL to receive a POST request when the task completes. Use this instead of polling for production systems.

result = await client.run_task(
    prompt="Extract pricing data",
    webhook_url="https://your-server.com/webhook"
)

Skyvern sends a POST request with the full run data when the task completes or fails.

`title`

Display name for the task in the Skyvern UI.

result = await client.run_task(
    prompt="Get the top post",
    title="HN Top Post Scraper"
)

`extra_http_headers`

Additional HTTP headers to include in browser requests.

result = await client.run_task(
    prompt="Access protected resource",
    extra_http_headers={
        "Authorization": "Bearer your-token"
    }
)

`publish_workflow`

Convert this task into a reusable workflow. Only available for skyvern-2.0.

result = await client.run_task(
    prompt="Fill out the contact form with provided data",
    publish_workflow=True
)

`max_screenshot_scrolls`

Number of scrolls for post-action screenshots. Use this for pages with lazy-loaded content.

result = await client.run_task(
    prompt="Extract all product listings",
    max_screenshot_scrolls=3
)

`browser_address`

Connect to a browser at a specific CDP address. Use this for local development only.

result = await client.run_task(
    prompt="Automate my local browser",
    browser_address="http://127.0.0.1:9222"
)

`run_with`

Choose whether the task runs with the AI agent or generated code.

Value	Description
`agent`	Run with the AI agent (default). The agent analyzes screenshots and decides actions in real time.
`code`	Run with generated code. Faster and more deterministic, but requires a previously published workflow.

result = await client.run_task(
    prompt="Fill out the contact form",
    run_with="agent"
)

`model`

Optional model configuration for the task.

result = await client.run_task(
    prompt="Extract data from the page",
    model={"temperature": 0.5}
)

`include_action_history_in_verification`

Include action history when verifying task completion. Default: false.

result = await client.run_task(
    prompt="Complete the multi-step form",
    include_action_history_in_verification=True
)

Getting Started

Running Automations

Multi-Step Automations

Optimization

Going to Production

Debugging

Self-Hosted Deployment

Task Parameters

Quick reference

`prompt`

`url`

`engine`

`data_extraction_schema`

`max_steps`

`proxy_location`

`browser_session_id`

`totp_identifier`

`totp_url`

`error_code_mapping`

`webhook_url`

`title`

`extra_http_headers`

`publish_workflow`

`max_screenshot_scrolls`

`browser_address`

`run_with`

`model`

`include_action_history_in_verification`

Next steps

Extract Structured Data

Run a Task

Getting Started

Running Automations

Multi-Step Automations

Optimization

Going to Production

Debugging

Self-Hosted Deployment

​Quick reference

​prompt

​url

​engine

​data_extraction_schema

​max_steps

​proxy_location

​browser_session_id

​totp_identifier

​totp_url

​error_code_mapping

​webhook_url

​title

​extra_http_headers

​publish_workflow

​max_screenshot_scrolls

​browser_address

​run_with

​model

​include_action_history_in_verification

​Next steps

Extract Structured Data

Run a Task

Quick reference

`prompt`

`url`

`engine`

`data_extraction_schema`

`max_steps`

`proxy_location`

`browser_session_id`

`totp_identifier`

`totp_url`

`error_code_mapping`

`webhook_url`

`title`

`extra_http_headers`

`publish_workflow`

`max_screenshot_scrolls`

`browser_address`

`run_with`

`model`

`include_action_history_in_verification`

Next steps