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

# Tasks and runs

> Run a browser task and inspect, cancel or retry any run.

Start a one-off browser task with `run_task`, then use the run methods with the `run_id` it returns. The run methods work for task runs (`tsk_…`) and agent runs (`wr_…`) alike.

Every method here also accepts `request_options` (Python) or a final `requestOptions` argument (TypeScript) to override the timeout, retries or headers for one call; see [request options](https://skyvern.com/docs/sdk-reference/overview.md#request-options).

## Run a task

### run\_task

Run a task

```python Python theme={null}
await skyvern.run_task(
    prompt: str,
    engine: RunEngine = RunEngine.skyvern_v1,
    model: dict[str, Any] | None = None,
    url: str | None = None,
    webhook_url: str | None = None,
    totp_identifier: str | None = None,
    totp_url: str | None = None,
    title: str | None = None,
    error_code_mapping: dict[str, str] | None = None,
    data_extraction_schema: dict[str, Any] | str | None = None,
    proxy_location: ProxyLocationInput = None,
    max_steps: int | None = None,
    wait_for_completion: bool = False,
    timeout: float = 1800,
    browser_session_id: str | None = None,
    user_agent: str | None = None,
    extra_http_headers: dict[str, str] | None = None,
    publish_workflow: bool = False,
    include_action_history_in_verification: bool | None = None,
    max_screenshot_scrolls: int | None = None,
    browser_address: str | None = None,
) -> TaskRunResponse
```

```typescript TypeScript theme={null}
skyvern.runTask(request: RunTaskOptions): Promise<TaskRunResponse>
```

**Parameters**

**prompt** `str` *required*

The goal or task description for Skyvern to accomplish

**engine** `RunEngine`

The engine that runs the task. Defaults to `skyvern_v1` (`"skyvern-1.0"`), suited to simple, single-goal tasks. `skyvern_v3` (`"skyvern-3.0"`) is the newest engine; the REST API and the Python SDK accept it, but the published TypeScript client's type does not list it yet. `skyvern_v2` remains for existing 2.0 runs. `openai_cua` and `anthropic_cua` use OpenAI's and Anthropic's computer-use models; `ui_tars` is also accepted.

Default: `RunEngine.skyvern_v1`

**model** `dict[str, Any] | None`

Optional model configuration.

Default: `None`

**url** `str | None`

The starting URL for the task. If not provided, Skyvern will attempt to determine an appropriate URL

Default: `None`

**webhook\_url** `str | None`

After a run is finished, send an update to this URL. Refer to [https://www.skyvern.com/docs/running-tasks/webhooks-faq](https://www.skyvern.com/docs/running-tasks/webhooks-faq) for more details.

Default: `None`

**totp\_identifier** `str | None`

Identifier for the TOTP/2FA/MFA code when the code is pushed to Skyvern. Refer to [https://www.skyvern.com/docs/credentials/totp#option-3-push-code-to-skyvern](https://www.skyvern.com/docs/credentials/totp#option-3-push-code-to-skyvern) for more details.

Default: `None`

**totp\_url** `str | None`

URL that serves TOTP/2FA/MFA codes for Skyvern to use during the workflow run. Refer to [https://www.skyvern.com/docs/credentials/totp#option-2-get-code-from-your-endpoint](https://www.skyvern.com/docs/credentials/totp#option-2-get-code-from-your-endpoint) for more details.

Default: `None`

**title** `str | None`

The title for the task

Default: `None`

**error\_code\_mapping** `dict[str, str] | None`

Custom mapping of error codes to error messages if Skyvern encounters an error.

Default: `None`

**data\_extraction\_schema** `dict[str, Any] | str | None`

The schema for data to be extracted from the webpage. If you're looking for consistent data schema being returned by the agent, it's highly recommended to use [https://json-schema.org/](https://json-schema.org/).

Default: `None`

**proxy\_location** `ProxyLocationInput`

Geographic Proxy location to route the browser traffic through. This is only available in Skyvern Cloud.

Default: `None`

**max\_steps** `int | None`

Maximum number of steps the task can take. Task will fail if it exceeds this number. Cautions: you are charged per step so please set this number to a reasonable value. Contact [sales@skyvern.com](mailto:sales@skyvern.com) for custom pricing.

Default: `None`

**wait\_for\_completion** `bool`

Wait for the run to reach a final status before returning.

Default: `False` · TypeScript: `waitForCompletion`

**timeout** `float`

Maximum time to wait for completion, in seconds.

Default: `1800`

**browser\_session\_id** `str | None`

Run the task or workflow in the specific Skyvern browser session. Having a browser session can persist the real-time state of the browser, so that the next run can continue from where the previous run left off.

Default: `None`

**user\_agent** `str | None`

User-Agent string the browser sends.

Default: `None` · TypeScript: `x-user-agent`

**extra\_http\_headers** `dict[str, str] | None`

The extra HTTP headers for the requests in browser.

Default: `None`

**publish\_workflow** `bool`

Deprecated. Whether to publish a `skyvern-2.0` task as a reusable workflow. For backwards compatibility, this routes the request through the legacy `skyvern-2.0` publish path. Prefer creating reusable workflows through the workflow APIs.

Default: `False`

**include\_action\_history\_in\_verification** `bool | None`

Whether to include action history when verifying that the task is complete

Default: `None`

**max\_screenshot\_scrolls** `int | None`

The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot.

Default: `None`

**browser\_address** `str | None`

The CDP address for the task.

Default: `None`

**cdp\_connect\_headers** `Record\<string, string | undefined\>`

HTTP headers attached ONLY to the CDP WebSocket handshake when connecting to a remote browser via browser\_address. Use this for browser-provider auth (e.g., x-api-key for Skyvern Cloud, Browserless, or similar). These headers are NEVER forwarded to target websites.

TypeScript only

**run\_with** `string`

Whether to run the task with agent or code. Null means use the default.

TypeScript only

**Returns** `TaskRunResponse` · TypeScript `Promise<TaskRunResponse>`

> [accordion] TaskRunResponse fields
>
> | Field | Type | Description |
> | - | - | - |
> | `run_id` | `str` | Unique identifier for this run. Run ID starts with `tsk_` for task runs and `wr_` for workflow runs. |
> | `status` | `"created" \| "queued" \| "running" \| "paused" \| "timed_out" \| "failed" \| "terminated" \| "completed" \| "canceled"` | Current status of the run |
> | `output` | `dict[str, Any \| None] \| list[Any \| None] \| str \| None` | Output data from the run, if any. Format/schema depends on the data extracted by the run. |
> | `downloaded_files` | `list[FileInfo] \| None` | List of files downloaded during the run |
> | `recording_url` | `str \| None` | URL to the recording of the run |
> | `recording_archived` | `bool \| None` | True when the recording exists but has been archived to cold storage and is not currently accessible. |
> | `screenshot_urls` | `list[str] \| None` | List of last n screenshot URLs in reverse chronological order - the first one the list is the latest screenshot. |
> | `failure_reason` | `str \| None` | Reason for failure if the run failed or terminated |
> | `created_at` | `datetime` | Timestamp when this run was created |
> | `modified_at` | `datetime` | Timestamp when this run was last modified |
> | `queued_at` | `datetime \| None` | Timestamp when this run was queued |
> | `started_at` | `datetime \| None` | Timestamp when this run started execution |
> | `finished_at` | `datetime \| None` | Timestamp when this run finished |
> | `app_url` | `str \| None` | URL to the application UI where the run can be viewed |
> | `browser_session_id` | `str \| None` | ID of the Skyvern persistent browser session used for this run |
> | `browser_profile_id` | `str \| None` | ID of the browser profile used for this run |
> | `max_screenshot_scrolls` | `int \| None` | The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot |
> | `script_run` | `ScriptRunResponse \| None` | The script run result |
> | `errors` | `list[dict[str, Any \| None]] \| None` | The errors for the run |
> | `step_count` | `int \| None` | Total number of steps executed in this run |
> | `run_request` | `TaskRunRequestOutput \| None` | The original request parameters used to start this task run |

**Example**

```python Python theme={null}
import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    result = await skyvern.run_task(prompt="Find the top post on Hacker News and return its title")
    print(result)


asyncio.run(main())
```

```typescript TypeScript theme={null}
import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const result = await skyvern.runTask({
    prompt: "Find the top post on Hacker News and return its title",
});
console.log(result);
```

## Inspect and manage runs

### get\_run

Get run information (task run, workflow run)

```python Python theme={null}
await skyvern.get_run(run_id: str) -> GetRunResponse
```

```typescript TypeScript theme={null}
skyvern.getRun(runId: string): Promise<GetRunResponse>
```

**Parameters**

**run\_id** `str` *required*

The id of the task run or the workflow run.

TypeScript: `runId`

**Returns** `GetRunResponse` · TypeScript `Promise<GetRunResponse>`

**Example**

```python Python theme={null}
import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    result = await skyvern.get_run(run_id="tsk_v2_123")
    print(result)


asyncio.run(main())
```

```typescript TypeScript theme={null}
import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const result = await skyvern.getRun("tsk_v2_123");
console.log(result);
```

***

### get\_runs\_v2

List runs

```python Python theme={null}
await skyvern.get_runs_v2(
    *,
    page: int | None = None,
    page_size: int | None = None,
    status: RunStatus | Sequence[RunStatus] | None = None,
    search_key: str | None = None,
    run_type: RunType | Sequence[RunType] | None = None,
) -> list[TaskRunListItem]
```

```typescript TypeScript theme={null}
skyvern.getRunsV2(request?: GetRunsV2Request): Promise<TaskRunListItem[]>
```

**Parameters**

**page** `int | None`

Default: `None`

**page\_size** `int | None`

Default: `None`

**status** `RunStatus | Sequence[RunStatus] | None`

Default: `None`

**search\_key** `str | None`

Case-insensitive substring search (min 3 chars for trigram index).

Default: `None`

**run\_type** `RunType | Sequence[RunType] | None`

Default: `None`

**Returns** `list[TaskRunListItem]` · TypeScript `Promise<TaskRunListItem[]>`

> [accordion] TaskRunListItem fields
>
> | Field | Type | Description |
> | - | - | - |
> | `task_run_id` | `str` | |
> | `run_id` | `str` | |
> | `task_run_type` | `str` | |
> | `status` | `str` | |
> | `title` | `str \| None` | |
> | `started_at` | `datetime \| None` | |
> | `finished_at` | `datetime \| None` | |
> | `created_at` | `datetime` | |
> | `workflow_permanent_id` | `str \| None` | |
> | `workflow_deleted` | `bool \| None` | |
> | `script_run` | `bool \| None` | |
> | `trigger_type` | `"manual" \| "mcp" \| "api" \| "scheduled" \| "webhook" \| None` | |

**Example**

```python Python theme={null}
import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    result = await skyvern.get_runs_v2()
    print(result)


asyncio.run(main())
```

```typescript TypeScript theme={null}
import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const result = await skyvern.getRunsV2();
console.log(result);
```

***

### get\_run\_timeline

Get timeline for a run (workflow run or task\_v2 run)

```python Python theme={null}
await skyvern.get_run_timeline(run_id: str) -> list[WorkflowRunTimeline]
```

```typescript TypeScript theme={null}
skyvern.getRunTimeline(runId: string): Promise<WorkflowRunTimeline[]>
```

**Parameters**

**run\_id** `str` *required*

The id of the workflow run or task\_v2 run.

TypeScript: `runId`

**Returns** `list[WorkflowRunTimeline]` · TypeScript `Promise<WorkflowRunTimeline[]>`

> [accordion] WorkflowRunTimeline fields
>
> | Field | Type | Description |
> | - | - | - |
> | `type` | `"thought" \| "block"` | |
> | `block` | `WorkflowRunBlock \| None` | |
> | `thought` | `Thought \| None` | |
> | `children` | `list[WorkflowRunTimeline] \| None` | |
> | `created_at` | `datetime` | |
> | `modified_at` | `datetime` | |

**Example**

```python Python theme={null}
import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    result = await skyvern.get_run_timeline(run_id="tsk_v2_123")
    print(result)


asyncio.run(main())
```

```typescript TypeScript theme={null}
import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const result = await skyvern.getRunTimeline("tsk_v2_123");
console.log(result);
```

***

### cancel\_run

Cancel a run (task or workflow)

```python Python theme={null}
await skyvern.cancel_run(run_id: str) -> Any | None
```

```typescript TypeScript theme={null}
skyvern.cancelRun(runId: string): Promise<unknown>
```

**Parameters**

**run\_id** `str` *required*

The id of the task run or the workflow run to cancel.

TypeScript: `runId`

**Returns** `Any | None` · TypeScript `Promise<unknown>`

**Example**

```python Python theme={null}
import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    result = await skyvern.cancel_run(run_id="tsk_v2_123")
    print(result)


asyncio.run(main())
```

```typescript TypeScript theme={null}
import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const result = await skyvern.cancelRun("tsk_v2_123");
console.log(result);
```

***

### bulk\_cancel\_runs

Cancel multiple runs (tasks or workflows) in a single request

```python Python theme={null}
await skyvern.bulk_cancel_runs(*, run_ids: Sequence[str]) -> BulkCancelRunsResponse
```

```typescript TypeScript theme={null}
skyvern.bulkCancelRuns(request: BulkCancelRunsRequest): Promise<BulkCancelRunsResponse>
```

**Parameters**

**run\_ids** `Sequence[str]` *required*

List of run IDs to cancel

**Returns** `BulkCancelRunsResponse` · TypeScript `Promise<BulkCancelRunsResponse>`

> [accordion] BulkCancelRunsResponse fields
>
> | Field | Type | Description |
> | - | - | - |
> | `cancelled` | `list[str]` | Run IDs that were successfully cancelled |
> | `failed` | `list[str]` | Run IDs that could not be cancelled |

**Example**

```python Python theme={null}
import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    result = await skyvern.bulk_cancel_runs(run_ids=["tsk_v2_123", "wr_456"])
    print(result)


asyncio.run(main())
```

```typescript TypeScript theme={null}
import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const result = await skyvern.bulkCancelRuns({ run_ids: ["tsk_v2_123", "wr_456"] });
console.log(result);
```

***

### retry\_run\_webhook

Retry sending the webhook for a run

```python Python theme={null}
await skyvern.retry_run_webhook(
    run_id: str,
    *,
    request: RetryRunWebhookRequest | None = None,
) -> RunWebhookReplayResponse
```

```typescript TypeScript theme={null}
skyvern.retryRunWebhook(runId: string, request?: RetryRunWebhookRequest): Promise<RunWebhookReplayResponse>
```

**Parameters**

**run\_id** `str` *required*

The id of the task run or the workflow run.

TypeScript: `runId`

**request** `RetryRunWebhookRequest | None`

Default: `None`

**Returns** `RunWebhookReplayResponse` · TypeScript `Promise<RunWebhookReplayResponse>`

> [accordion] RunWebhookReplayResponse fields
>
> | Field | Type | Description |
> | - | - | - |
> | `run_id` | `str` | Identifier of the run that was replayed |
> | `run_type` | `str` | Run type associated with the payload |
> | `default_webhook_url` | `str \| None` | Webhook URL stored on the original run configuration |
> | `target_webhook_url` | `str \| None` | Webhook URL that the replay attempted to reach |
> | `payload` | `str` | JSON payload that was delivered during the replay attempt |
> | `headers` | `dict[str, str]` | Signed headers that were generated for the replay attempt |
> | `status_code` | `int \| None` | HTTP status code returned by the webhook receiver, if available |
> | `latency_ms` | `int \| None` | Round-trip latency in milliseconds for the replay attempt |
> | `response_body` | `str \| None` | Body returned by the webhook receiver (truncated to 2KB) |
> | `error` | `str \| None` | Error message if the replay attempt failed |

**Example**

```python Python theme={null}
import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    result = await skyvern.retry_run_webhook(run_id="tsk_v2_123")
    print(result)


asyncio.run(main())
```

```typescript TypeScript theme={null}
import { Skyvern } from "@skyvern/client";

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const result = await skyvern.retryRunWebhook("tsk_v2_123");
console.log(result);
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.