Run Tasks

• Quickstart to run a task.
• Run Task API

Every feature in this page is enabled through API & SDK. Some features are enabled through Skyvern’s Discover page as well.

Parameters

Engine

Parameter: engine

This parameter defines the engine that powers the agent task.

• skyvern-2.0: this is the default engine. It’s the latest Skyvern agent that performs really well with complex and multi-step tasks. It scores state of the art 85.85% on the WebVoyager benchmark.
• skyvern-1.0: performs really well for tasks with a simple goal, like filling a form, or searching for information on Google.
• openai-cua: uses OpenAI’s CUA model.
• anthropic-cua: uses Anthropic’s Claude Sonnet 3.7 model with the computer use tool.
• ui-tars: uses the UI-TARS model (Seed1.5-VL) via Doubao API for computer vision and GUI automation with multi-turn conversation support (https://seed.bytedance.com/zh/tech/seed1_5_vl).

Data Extraction Schema

Parameter: data_extraction_schema

The schema for data to be extracted from the webpage. If you’re looking for consistent data schema being returned by the agent, it’s highly recommended to use https://json-schema.org/.

Send Webhook

Parameter: webhook_url

You can set the webhook_url to receive the update when the task is done. Check Webhooks FAQ for more details.

Max Steps

Parameter: max_steps

Maximum number of steps the task can take. Task will fail if it exceeds this number. Caution: you are charged per step, so set this number to a reasonable value. Contact sales@skyvern.com for custom pricing.

Error Code Mapping

Parameter: error_code_mapping

Custom mapping of error codes to error messages if Skyvern encounters an error.

For example:

1
[
2
    {"login_failed": "The login credentials are incorrect or the account is locked"},
3
    {"maintenance_mode": "The website is down for maintenance"},
4
]

With this mapping, if Skyvern encounters a login failure, the task output will show {"error": "login_failed"}, which makes it easy to codify error handling.

Proxy Location

Parameter: proxy_location

Some websites block requests from certain countries. You can set a proxy location to route the browser traffic through.

2FA Support (TOTP)

• totp_identifier: Skyvern can receive the TOTP code and use this identifier to identify the code for authentication.
• totp_url: Skyvern makes a request to this URL to fetch the TOTP code when needed.

More details can be found in the TOTP section.

Run Task In A Persistent Browser Session

Parameter: browser_session_id

You can set a browser session for a task. Having a browser session persist the real-time state of the browser, so that the next run can continue from where the previous run left off.

See the Browser Sessions section to see how to create a browser session.

Use Cases

Control Your Own Browser (Chrome)

Just With Python Code

1
from skyvern import Skyvern
2
3
# The path to your Chrome browser. This example path is for Mac.
4
browser_path = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
5
skyvern = Skyvern(
6
	base_url="http://localhost:8000",
7
	api_key="YOUR_API_KEY",
8
	browser_path=browser_path,
9
)
10
task = await skyvern.run_task(
11
	prompt="Find the top post on hackernews today",
12
)

With Skyvern Service

$
# The path to your Chrome browser. This example path is for Mac.
>
CHROME_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
>
BROWSER_TYPE=cdp-connect

Restart your Skyvern service skyvern run server and run the task through UI or code:

1
from skyvern import Skyvern
2
3
skyvern = Skyvern(
4
	base_url="http://localhost:8000",
5
	api_key="YOUR_API_KEY",
6
)
7
task = await skyvern.run_task(
8
	prompt="Find the top post on hackernews today",
9
)

Get Consistent Output Schema

You can do it by adding the data_extraction_schema parameter to your task.

For example, if you want to get the title, URL, and points of the top post on Hacker News today, you can add the following to your task:

1
from skyvern import Skyvern
2
3
skyvern = Skyvern()
4
task = await skyvern.run_task(
5
    prompt="Find the top post on hackernews today",
6
    data_extraction_schema={
7
        "type": "object",
8
        "properties": {
9
            "title": {
10
                "type": "string",
11
                "description": "The title of the top post"
12
            },
13
            "url": {
14
                "type": "string",
15
                "description": "The URL of the top post"
16
            },
17
            "points": {
18
                "type": "integer",
19
                "description": "Number of points the post has received"
20
            }
21
        }
22
    }
23
)

Wait Until Task Is Done

When you are sending a run task request the Skyvern service, you can set the wait_for_completion to True and wait until the task is done.

1
from skyvern import Skyvern
2
3
skyvern = Skyvern()
4
task = await skyvern.run_task(
5
    prompt="Find the top post on hackernews today",
6
    # the request will be hanging until the task is done
7
    wait_for_completion=True,
8
)
9
print(task.output)

Send Run Result To Your Webhook

Instead of waiting, you can also set the webhook_url in the run task request and get the result in your webhook whenever it’s done.

1
from skyvern import Skyvern
2
3
skyvern = Skyvern()
4
task = await skyvern.run_task(
5
    prompt="Find the top post on hackernews today",
6
    webhook_url="https://your-webhook-url.com",
7
)

You can also use the GET RUN API to get the current status of the task.