Dorod-Sky/fern/running-tasks/run-tasks.mdx

---
title: Run Tasks
slug: running-tasks/run-tasks
---

- [Quickstart](/getting-started/quickstart) to run a task.
- [Run Task API](/api-reference/api-reference/agent/run-task)

Every feature in this page is enabled through API & SDK. Some features are enabled through [Skyvern's Discover page](https://app.skyvern.com/discover) as well.
 
<Frame caption="Run Task UI">
<img src="../images/run_tasks/ui_run_task.png" alt="Configure advanced settings in the UI" width="400" />
</Frame>

## Parameters

### [Engine](/api-reference/api-reference/agent/run-task#request.body.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](https://blog.skyvern.com/skyvern-2-0-state-of-the-art-web-navigation-with-85-8-on-webvoyager-eval/).
- `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](/api-reference/api-reference/agent/run-task#request.body.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](/api-reference/api-reference/agent/run-task#request.body.webhook_url)

Parameter: `webhook_url`

You can set the `webhook_url` to receive the update when the task is done. Check [Webhooks FAQ](/running-tasks/webhooks-faq) for more details.

### [Max Steps](/api-reference/api-reference/agent/run-task#request.body.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](/api-reference/api-reference/agent/run-task#request.body.error_code_mapping)

Parameter: `error_code_mapping`

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

For example:
```json
[
    {"login_failed": "The login credentials are incorrect or the account is locked"},
    {"maintenance_mode": "The website is down for maintenance"},
]
```
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](/api-reference/api-reference/agent/run-task#request.body.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](/api-reference/api-reference/agent/run-task#request.body.totp_identifier): Skyvern can receive the TOTP code and use this identifier to identify the code for authentication.
- [totp_url](/api-reference/api-reference/agent/run-task#request.body.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](/credentials/totp).

### [Run Task In A Persistent Browser Session](/api-reference/api-reference/agent/run-task#request.body.browser_session_id)
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](/browser-sessions/introduction) section to see how to create a browser session.

## Use Cases
### Control Your Own Browser (Chrome) 
<Warning>Since [Chrome 136](https://developer.chrome.com/blog/remote-debugging-port), Chrome refuses any CDP connect to the browser using the default user_data_dir. In order to use your browser data, Skyvern copies your default user_data_dir to `./tmp/user_data_dir` the first time connecting to your local browser.</Warning>

**Just With Python Code**
```python
from skyvern import Skyvern

# The path to your Chrome browser. This example path is for Mac.
browser_path = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
skyvern = Skyvern(
	base_url="http://localhost:8000",
	api_key="YOUR_API_KEY",
	browser_path=browser_path,
)
task = await skyvern.run_task(
	prompt="Find the top post on hackernews today",
)
```

**With Skyvern Service**
```bash
# 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:
```python
from skyvern import Skyvern

skyvern = Skyvern(
	base_url="http://localhost:8000",
	api_key="YOUR_API_KEY",
)
task = await skyvern.run_task(
	prompt="Find the top post on hackernews today",
)
```

### 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:
```python
from skyvern import Skyvern

skyvern = Skyvern()
task = await skyvern.run_task(
    prompt="Find the top post on hackernews today",
    data_extraction_schema={
        "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"
            }
        }
    }
)
```

### 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.
```python
from skyvern import Skyvern

skyvern = Skyvern()
task = await skyvern.run_task(
    prompt="Find the top post on hackernews today",
    # the request will be hanging until the task is done
    wait_for_completion=True,
)
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.
```python
from skyvern import Skyvern

skyvern = Skyvern()
task = await skyvern.run_task(
    prompt="Find the top post on hackernews today",
    webhook_url="https://your-webhook-url.com",
)
```
You can also use the [GET RUN API](/api-reference/api-reference/agent/get-run) to get the current status of the task.