> ## Documentation Index
> Fetch the complete documentation index at: https://docs-new.skyvern.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 theme={null}
  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 theme={null}
  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](/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 theme={null}
  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 theme={null}
  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 theme={null}
  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 theme={null}
  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 theme={null}
  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 theme={null}
  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 theme={null}
  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 theme={null}
  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 theme={null}
  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 theme={null}
  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 theme={null}
  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 theme={null}
  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](/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 theme={null}
  # 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 theme={null}
  // 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 theme={null}
  from skyvern.client.core import RequestOptions

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

  ```typescript TypeScript theme={null}
  // 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.             |

***