Skip to main content

​
Overview

This page documents all available parameters when creating tasks via the SDK or API. Parameters allow you to customize task behavior, specify execution settings, and configure data extraction.

​
Required Parameters

​
prompt
string
required
The goal or task description for Skyvern to accomplish. This tells Skyvern what you want it to do.Examples:
  • "Find the top post on hackernews today"
  • "Fill out the contact form with my information"
  • "Get a quote for car insurance"
  • "Navigate to the invoices page and download all PDFs"

​
Core Parameters

​
url
string
The starting URL for the task. If not provided, Skyvern will attempt to determine an appropriate URL based on the prompt.Examples:
  • "https://www.geico.com"
  • "https://news.ycombinator.com"
  • "https://example.com/contact"
​
engine
RunEngine
default:"skyvern-2.0"
The engine that powers the agent task. Available options:
  • skyvern-2.0 (default): Latest Skyvern agent, performs well with complex and multi-step tasks
  • skyvern-1.0: Good for simple tasks like filling a form or searching for information
  • openai-cua: Uses OpenAI’s Computer Use Agent model
  • anthropic-cua: Uses Anthropic’s Claude Sonnet 3.7 model with computer use tool
  • ui-tars: Specialized UI interaction engine
​
title
string
A human-readable title for the task. Useful for organizing and identifying tasks in the UI.Example: "Get car insurance quote"
​
max_steps
integer
Maximum number of steps the task can take. Task will fail if it exceeds this number.Important: You are charged per step, so set this to a reasonable value.Default: Varies based on your account settingsExample: 50

​
Data Extraction

​
data_extraction_schema
object | string
The schema for data to be extracted from the webpage. For consistent data output, it’s highly recommended to use JSON Schema format.Example:
{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "The title of the top post"
    },
    "url": {
      "type": "string",
      "description": "The URL of the top post"
    },
    "points": {
      "type": "integer",
      "description": "Number of points the post has received"
    }
  }
}
See Data Extraction for more details.

​
Browser & Session

​
browser_session_id
string
Run the task in a specific Skyvern browser session. Browser sessions persist the real-time state of the browser, allowing the next run to continue from where the previous run left off.Example: "bs_a1b2c3d4e5f6"
​
browser_address
string
The Chrome DevTools Protocol (CDP) address for the task. Use this to connect to a specific browser instance.Examples:
  • "http://127.0.0.1:9222"
  • "ws://127.0.0.1:9222/devtools/browser/1234567890"
​
proxy_location
ProxyLocation
Geographic proxy location to route the browser traffic through. Only available in Skyvern Cloud.Available options:
  • RESIDENTIAL: Default, random US residential proxy
  • RESIDENTIAL_ES: Spain
  • RESIDENTIAL_IE: Ireland
  • RESIDENTIAL_GB: United Kingdom
  • RESIDENTIAL_IN: India
  • RESIDENTIAL_JP: Japan
  • RESIDENTIAL_FR: France
  • RESIDENTIAL_DE: Germany
  • RESIDENTIAL_NZ: New Zealand
  • RESIDENTIAL_PH: Philippines
  • RESIDENTIAL_ZA: South Africa
  • RESIDENTIAL_AR: Argentina
  • RESIDENTIAL_AU: Australia
  • RESIDENTIAL_ISP: ISP proxy
  • NONE: No proxy
Or use a GeoTarget object for granular targeting:
{"country": "US", "subdivision": "CA", "city": "San Francisco"}

​
Authentication & 2FA

​
totp_identifier
string
Identifier for the TOTP/2FA/MFA code when the code is pushed to Skyvern.See TOTP Documentation for details.
​
totp_url
string
URL that serves TOTP/2FA/MFA codes for Skyvern to use during task execution.See TOTP Documentation for details.

​
Webhooks & Callbacks

​
webhook_url
string
After a task finishes, send an update to this URL.Example: "https://your-domain.com/webhook"See Webhooks FAQ for details.

​
Error Handling

​
error_code_mapping
object
Custom mapping of error codes to error messages if Skyvern encounters specific situations.Example:
{
  "out_of_stock": "Return this error when the product is out of stock",
  "not_found": "Return this error when the product is not found",
  "invalid_zip": "Return this error when the zip code is invalid"
}

​
Advanced Configuration

​
model
object
Optional model configuration for custom LLM settings.Example:
{
  "model_name": "gpt-4o",
  "temperature": 0.7
}
​
extra_http_headers
object
Extra HTTP headers for the requests in the browser.Example:
{
  "X-Custom-Header": "value",
  "Authorization": "Bearer token"
}
​
user_agent
string
Custom user agent string for the browser.Example: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
​
include_action_history_in_verification
boolean
default:"false"
Whether to include action history when verifying that the task is complete.
​
max_screenshot_scrolls
integer
The maximum number of scrolls for the post-action screenshot. When set to None or 0, it takes the current viewport screenshot.Example: 10
​
publish_workflow
boolean
default:"false"
Whether to publish this task as a reusable workflow. Only available for skyvern-2.0 engine.
​
run_with
string
Whether to run the task with agent or code execution.Options: "agent", "code"
​
download_timeout
float
The maximum time to wait for downloads to complete, in seconds. If not set, defaults to BROWSER_DOWNLOAD_TIMEOUT from settings.Example: 15.0

​
SDK-Specific Parameters

​
Python SDK Only

​
wait_for_completion
boolean
default:"false"
When True, the SDK will poll the task status until it reaches a final state (completed, failed, terminated, timed_out, or canceled).
task = await skyvern.run_task(
    prompt="Fill out the form",
    wait_for_completion=True,
    timeout=300.0  # Wait up to 5 minutes
)
​
timeout
float
default:"600.0"
Timeout in seconds when wait_for_completion=True. Only used with Python SDK.Example: 300.0 (5 minutes)
​
request_options
RequestOptions
Additional options for the HTTP request, such as custom timeout or headers. Python SDK only.

​
Example: Complete Task Configuration

from skyvern import Skyvern
from skyvern.schemas.runs import ProxyLocation, RunEngine

skyvern = Skyvern(api_key="your-api-key")

task = await skyvern.run_task(
    # Required
    prompt="Get a car insurance quote",
    
    # Core settings
    url="https://www.geico.com",
    engine=RunEngine.skyvern_v2,
    title="GEICO Quote Request",
    max_steps=50,
    
    # Data extraction
    data_extraction_schema={
        "type": "object",
        "properties": {
            "quote_amount": {"type": "number"},
            "coverage_type": {"type": "string"}
        }
    },
    
    # Browser settings
    proxy_location=ProxyLocation.RESIDENTIAL,
    
    # Webhooks
    webhook_url="https://your-domain.com/webhook",
    
    # Error handling
    error_code_mapping={
        "invalid_zip": "Zip code not in service area"
    },
    
    # Wait for completion
    wait_for_completion=True,
    timeout=600.0
)

​
Next Steps

Data Extraction

Learn how to extract structured data with JSON schemas

Monitoring Runs

Monitor task execution and check status

Build docs developers (and LLMs) love

Get started for freeTalk to us