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.

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.

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

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)

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.
`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:

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}, ...]

Run inside an existing browser session:

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,
)

Limit cost with max_steps:

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

Use a lighter engine:

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,
)

Publish as a reusable workflow:

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

Polling pattern

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

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)

For production, prefer wait_for_completion=True / waitForCompletion: true or webhooks over manual polling.

`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):

# 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)

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).

from skyvern.client.core import RequestOptions

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

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.

SDK

Browser Automation

Tasks

Workflows

Browser Sessions

Browser Profiles

Credentials

Helpers

Parameters

Returns `TaskRunResponse`

Examples

Polling pattern

`wait_for_completion` / `waitForCompletion`

Request options

SDK

Browser Automation

Tasks

Workflows

Browser Sessions

Browser Profiles

Credentials

Helpers

Documentation Index

​Parameters

​Returns TaskRunResponse

​Examples

​Polling pattern

​wait_for_completion / waitForCompletion

​Request options

Parameters

Returns `TaskRunResponse`

Examples

Polling pattern

`wait_for_completion` / `waitForCompletion`

Request options