Skyvern/docs/sdk-reference/tasks/run-task.mdx

---
title: "run_task"
slug: sdk-reference/tasks/run-task
---

A task is a single browser automation. You describe what you want in natural language. Skyvern opens a browser, navigates to the URL, and executes the instructions with AI.

For when to use tasks vs workflows, see [Run a Task](/running-automations/run-a-task).

<Note>
Python uses `snake_case` (e.g., `run_task`, `wait_for_completion`); TypeScript uses `camelCase` (e.g., `runTask`, `waitForCompletion`) and wraps request params in a `body` object. Parameter tables show Python names. TypeScript names are the camelCase equivalents.
</Note>

---

Start a browser automation. Skyvern opens a cloud browser, navigates to the URL, and executes your prompt with AI.

<CodeGroup>
```python Python
result = await client.run_task(
    prompt="Get the title of the top post",
    url="https://news.ycombinator.com",
    wait_for_completion=True,
)
print(result.output)
```

```typescript TypeScript
const result = await skyvern.runTask({
  body: {
    prompt: "Get the title of the top post",
    url: "https://news.ycombinator.com",
  },
  waitForCompletion: true,
});
console.log(result.output);
```
</CodeGroup>

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | `str` | Yes | - | Natural language instructions for what the AI should do. |
| `url` | `str` | No | `None` | Starting page URL. If omitted, the AI navigates from a blank page. |
| `engine` | `RunEngine` | No | `skyvern_v2` | AI engine. Options: `skyvern_v2`, `skyvern_v1`, `openai_cua`, `anthropic_cua`, `ui_tars`. |
| `wait_for_completion` | `bool` | No | `False` | Block until the run finishes. |
| `timeout` | `float` | No | `1800` | Max wait time in seconds when `wait_for_completion=True`. |
| `max_steps` | `int` | No | `None` | Cap the number of AI steps to limit cost. Run terminates with `timed_out` if hit. |
| `data_extraction_schema` | `dict \| str` | No | `None` | JSON schema or Pydantic model name constraining the output shape. |
| `proxy_location` | `ProxyLocation` | No | `None` | Route the browser through a geographic proxy. |
| `browser_session_id` | `str` | No | `None` | Run inside an existing [browser session](/developers/optimization/browser-sessions). |
| `publish_workflow` | `bool` | No | `False` | Save the generated code as a reusable workflow. Only works with `skyvern_v2`. |
| `webhook_url` | `str` | No | `None` | URL to receive a POST when the run finishes. |
| `error_code_mapping` | `dict[str, str]` | No | `None` | Map custom error codes to failure reasons. |
| `totp_identifier` | `str` | No | `None` | Identifier for TOTP verification. |
| `totp_url` | `str` | No | `None` | URL to receive TOTP codes. |
| `title` | `str` | No | `None` | Display name for this run in the dashboard. |
| `model` | `dict` | No | `None` | Override the output model definition. |
| `user_agent` | `str` | No | `None` | Custom User-Agent header for the browser. |
| `extra_http_headers` | `dict[str, str]` | No | `None` | Additional HTTP headers injected into every browser request. |
| `include_action_history_in_verification` | `bool` | No | `None` | Include action history when verifying task completion. |
| `max_screenshot_scrolls` | `int` | No | `None` | Number of scrolls for post-action screenshots. Useful for lazy-loaded content. |
| `browser_address` | `str` | No | `None` | Connect to a browser at this CDP address instead of spinning up a new one. |
| `run_with` | `str` | No | `None` | Force execution mode: `"code"` (use cached Playwright code) or `"agent"` (use AI). |
| `request_options` | `RequestOptions` | No | - | Per-request configuration (see below). |

### Returns `TaskRunResponse`

| Field | Type | Description |
|-------|------|-------------|
| `run_id` | `str` | Unique identifier. Starts with `tsk_` for task runs. |
| `status` | `str` | `created`, `queued`, `running`, `completed`, `failed`, `terminated`, `timed_out`, or `canceled`. |
| `output` | `dict \| None` | Extracted data from the run. Shape depends on your prompt or `data_extraction_schema`. |
| `downloaded_files` | `list[FileInfo] \| None` | Files downloaded during the run. |
| `recording_url` | `str \| None` | URL to the session recording video. |
| `screenshot_urls` | `list[str] \| None` | Final screenshots (most recent first). |
| `failure_reason` | `str \| None` | Error description if the run failed. |
| `app_url` | `str \| None` | Link to view this run in the Cloud UI. |
| `step_count` | `int \| None` | Number of AI steps taken. |
| `script_run` | `ScriptRunResponse \| None` | Code execution result if the run used generated code. |
| `created_at` | `datetime` | When the run was created. |
| `finished_at` | `datetime \| None` | When the run finished. |

### Examples

**Extract structured data:**

<CodeGroup>
```python Python
result = await client.run_task(
    prompt="Extract the name, price, and rating of the top 3 products",
    url="https://example.com/products",
    data_extraction_schema={
        "type": "array",
        "items": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "price": {"type": "string"},
                "rating": {"type": "number"},
            },
        },
    },
    wait_for_completion=True,
)
print(result.output)
# [{"name": "Widget A", "price": "$29.99", "rating": 4.5}, ...]
```

```typescript TypeScript
const result = await skyvern.runTask({
  body: {
    prompt: "Extract the name, price, and rating of the top 3 products",
    url: "https://example.com/products",
    data_extraction_schema: {
      type: "array",
      items: {
        type: "object",
        properties: {
          name: { type: "string" },
          price: { type: "string" },
          rating: { type: "number" },
        },
      },
    },
  },
  waitForCompletion: true,
});
console.log(result.output);
// [{ name: "Widget A", price: "$29.99", rating: 4.5 }, ...]
```
</CodeGroup>

**Run inside an existing browser session:**

<CodeGroup>
```python Python
session = await client.create_browser_session()

result = await client.run_task(
    prompt="Log in and download the latest invoice",
    url="https://app.example.com/login",
    browser_session_id=session.browser_session_id,
    wait_for_completion=True,
)
```

```typescript TypeScript
const session = await skyvern.createBrowserSession({});

const result = await skyvern.runTask({
  body: {
    prompt: "Log in and download the latest invoice",
    url: "https://app.example.com/login",
    browser_session_id: session.browser_session_id,
  },
  waitForCompletion: true,
});
```
</CodeGroup>

**Limit cost with max_steps:**

<CodeGroup>
```python Python
result = await client.run_task(
    prompt="Fill out the contact form",
    url="https://example.com/contact",
    max_steps=10,
    wait_for_completion=True,
)
```

```typescript TypeScript
const result = await skyvern.runTask({
  body: {
    prompt: "Fill out the contact form",
    url: "https://example.com/contact",
    max_steps: 10,
  },
  waitForCompletion: true,
});
```
</CodeGroup>

**Use a lighter engine:**

<CodeGroup>
```python Python
from skyvern.schemas.runs import RunEngine

result = await client.run_task(
    prompt="Get the page title",
    url="https://example.com",
    engine=RunEngine.skyvern_v1,
    wait_for_completion=True,
)
```

```typescript TypeScript
const result = await skyvern.runTask({
  body: {
    prompt: "Get the page title",
    url: "https://example.com",
    engine: "skyvern_v1",
  },
  waitForCompletion: true,
});
```
</CodeGroup>

**Publish as a reusable workflow:**

<CodeGroup>
```python Python
result = await client.run_task(
    prompt="Fill out the contact form with the provided data",
    url="https://example.com/contact",
    publish_workflow=True,
    wait_for_completion=True,
)
# The generated workflow is saved and can be re-triggered via run_workflow
```

```typescript TypeScript
const result = await skyvern.runTask({
  body: {
    prompt: "Fill out the contact form with the provided data",
    url: "https://example.com/contact",
    publish_workflow: true,
  },
  waitForCompletion: true,
});
// The generated workflow is saved and can be re-triggered via runWorkflow
```
</CodeGroup>

---

## Polling pattern

If you don't use `wait_for_completion` / `waitForCompletion`, poll `get_run` / `getRun` manually:

<CodeGroup>
```python Python
import asyncio

task = await client.run_task(
    prompt="Extract product data",
    url="https://example.com/products",
)

while True:
    run = await client.get_run(task.run_id)
    if run.status in ("completed", "failed", "terminated", "timed_out", "canceled"):
        break
    await asyncio.sleep(5)

print(run.output)
```

```typescript TypeScript
const task = await skyvern.runTask({
  body: {
    prompt: "Extract product data",
    url: "https://example.com/products",
  },
});

const terminalStatuses = ["completed", "failed", "terminated", "timed_out", "canceled"];
let run;
while (true) {
  run = await skyvern.getRun(task.run_id);
  if (terminalStatuses.includes(run.status)) break;
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

console.log(run.output);
```
</CodeGroup>

<Tip>
For production, prefer `wait_for_completion=True` / `waitForCompletion: true` or [webhooks](/developers/going-to-production/webhooks) over manual polling.
</Tip>

---

## `wait_for_completion` / `waitForCompletion`

By default, `run_task` / `runTask` and `run_workflow` / `runWorkflow` return immediately after the run is queued. You get a `run_id` and need to poll `get_run` / `getRun` yourself. Pass `wait_for_completion=True` / `waitForCompletion: true` to have the SDK poll automatically until the run reaches a terminal state (`completed`, `failed`, `terminated`, `timed_out`, or `canceled`):

<CodeGroup>
```python Python
# Returns only after the task finishes (up to 30 min by default)
result = await client.run_task(
    prompt="Fill out the contact form",
    url="https://example.com/contact",
    wait_for_completion=True,
    timeout=600,  # give up after 10 minutes
)

# Without wait_for_completion -- returns immediately
task = await client.run_task(
    prompt="Fill out the contact form",
    url="https://example.com/contact",
)
print(task.run_id)  # poll with client.get_run(task.run_id)
```

```typescript TypeScript
// Returns only after the task finishes (up to 30 min by default)
const result = await skyvern.runTask({
  body: {
    prompt: "Fill out the contact form",
    url: "https://example.com/contact",
  },
  waitForCompletion: true,
  timeout: 600, // give up after 10 minutes
});

// Without waitForCompletion -- returns immediately
const task = await skyvern.runTask({
  body: {
    prompt: "Fill out the contact form",
    url: "https://example.com/contact",
  },
});
console.log(task.run_id); // poll with skyvern.getRun(task.run_id)
```
</CodeGroup>

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `wait_for_completion` / `waitForCompletion` | `bool` / `boolean` | `False` / `false` | Poll until the run finishes. |
| `timeout` | `float` / `number` | `1800` | Maximum wait time in seconds. Raises `TimeoutError` (Python) or `Error` (TS) if exceeded. |

Supported on `run_task`/`runTask`, `run_workflow`/`runWorkflow`, and `login`. In TypeScript, also supported on `downloadFiles`.

---

### Request options


Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).

<CodeGroup>
```python Python
from skyvern.client.core import RequestOptions

request_options=RequestOptions(
    timeout_in_seconds=120,
    max_retries=3,
    additional_headers={"x-custom-header": "value"},
)
```

```typescript TypeScript
// Pass as second argument to any method
{
  timeoutInSeconds: 120,
  maxRetries: 3,
  headers: { "x-custom-header": "value" },
}
```
</CodeGroup>

| Option (Python) | Option (TypeScript) | Type | Description |
|-----------------|---------------------|------|-------------|
| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
| `additional_query_parameters` | - | `dict` | Extra query parameters. |
| `additional_body_parameters` | - | `dict` | Extra body parameters. |
| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
| - | `apiKey` | `string` | Override API key. |


---