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}, ...]
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,
)
result = await client.run_task(
prompt="Fill out the contact form",
url="https://example.com/contact",
max_steps=10,
wait_for_completion=True,
)
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,
)
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. |
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. |
