298 lines
9.3 KiB
Plaintext
298 lines
9.3 KiB
Plaintext
---
|
|
title: Tasks
|
|
subtitle: Run single browser automations with natural language
|
|
slug: sdk-reference/tasks
|
|
---
|
|
|
|
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).
|
|
|
|
---
|
|
|
|
## `run_task`
|
|
|
|
Start a browser automation. Skyvern opens a cloud browser, navigates to the URL, and executes your prompt with AI.
|
|
|
|
```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)
|
|
```
|
|
|
|
### 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. |
|
|
|
|
### 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:**
|
|
|
|
```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}, ...]
|
|
```
|
|
|
|
**Run inside an existing browser session:**
|
|
|
|
```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,
|
|
)
|
|
```
|
|
|
|
**Limit cost with max_steps:**
|
|
|
|
```python
|
|
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:**
|
|
|
|
```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,
|
|
)
|
|
```
|
|
|
|
**Publish as a reusable workflow:**
|
|
|
|
```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
|
|
```
|
|
|
|
---
|
|
|
|
## `get_run`
|
|
|
|
Get the current status and results of any run (task or workflow).
|
|
|
|
```python
|
|
run = await client.get_run("tsk_v2_486305187432193504")
|
|
print(run.status, run.output)
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `run_id` | `str` | Yes | The run ID returned by `run_task` or `run_workflow`. |
|
|
|
|
### Returns `GetRunResponse`
|
|
|
|
A discriminated union based on `run_type`. All variants share the same core fields as `TaskRunResponse` above, plus a `run_type` field (`task_v1`, `task_v2`, `openai_cua`, `anthropic_cua`, `ui_tars`, `workflow_run`).
|
|
|
|
Workflow run responses additionally include `run_with` and `ai_fallback` fields.
|
|
|
|
---
|
|
|
|
## `cancel_run`
|
|
|
|
Cancel a running or queued run.
|
|
|
|
```python
|
|
await client.cancel_run("tsk_v2_486305187432193504")
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `run_id` | `str` | Yes | The run ID to cancel. |
|
|
|
|
The run transitions to `canceled` status. If the run has already finished, this is a no-op.
|
|
|
|
---
|
|
|
|
## `get_run_timeline`
|
|
|
|
Get the step-by-step timeline of a run. Each entry represents one AI action with screenshots and reasoning.
|
|
|
|
```python
|
|
timeline = await client.get_run_timeline("tsk_v2_486305187432193504")
|
|
for step in timeline:
|
|
print(f"Step {step.order}: {step.type} — {step.status}")
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `run_id` | `str` | Yes | The run ID. |
|
|
|
|
### Returns `list[WorkflowRunTimeline]`
|
|
|
|
Each timeline entry contains step details including type, status, order, and associated artifacts.
|
|
|
|
---
|
|
|
|
## `get_run_artifacts`
|
|
|
|
Get all artifacts (screenshots, recordings, generated code, etc.) for a run.
|
|
|
|
```python
|
|
artifacts = await client.get_run_artifacts("tsk_v2_486305187432193504")
|
|
for artifact in artifacts:
|
|
print(f"{artifact.artifact_type}: {artifact.uri}")
|
|
```
|
|
|
|
Filter by type to get specific artifacts:
|
|
|
|
```python
|
|
# Get only the generated Playwright scripts
|
|
scripts = await client.get_run_artifacts(
|
|
"tsk_v2_486305187432193504",
|
|
artifact_type=["script_file"],
|
|
)
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `run_id` | `str` | Yes | The run ID. |
|
|
| `artifact_type` | `ArtifactType \| list[ArtifactType]` | No | Filter by artifact type. |
|
|
|
|
### Returns `list[Artifact]`
|
|
|
|
---
|
|
|
|
## `get_artifact`
|
|
|
|
Get a single artifact by ID.
|
|
|
|
```python
|
|
artifact = await client.get_artifact("art_486305187432193504")
|
|
print(artifact.uri)
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `artifact_id` | `str` | Yes | The artifact ID. |
|
|
|
|
### Returns `Artifact`
|
|
|
|
---
|
|
|
|
## `retry_run_webhook`
|
|
|
|
Re-send the webhook notification for a completed run. Useful if your webhook endpoint was down when the run finished.
|
|
|
|
```python
|
|
await client.retry_run_webhook("tsk_v2_486305187432193504")
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `run_id` | `str` | Yes | The run ID. |
|
|
|
|
---
|
|
|
|
## Polling pattern
|
|
|
|
If you don't use `wait_for_completion`, poll `get_run` manually:
|
|
|
|
```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)
|
|
```
|
|
|
|
<Tip>
|
|
For production, prefer `wait_for_completion=True` or [webhooks](/going-to-production/webhooks) over manual polling.
|
|
</Tip>
|