Task Parameters

Full reference for all task parameters including prompt, URL, engine, data extraction schema, proxy location, browser sessions, TOTP, webhooks, and cost control options.

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.

Python

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.

Python

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.

Python

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.

Python

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.

Python

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_SA	Saudi Arabia
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

Python

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

Granular targeting (state/city level):

Python

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.

Python

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.

Python

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.

Python

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.

Python

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.

Python

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.

Python

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.

Python

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.

Python

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.

Python

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.

Python

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.

Python

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

---

model

Optional model configuration for the task.

Python

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.

Python

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

---

Next steps

Extract Structured Data

Define a schema to get typed JSON output

Run a Task

Execute tasks and retrieve results