Tasks and runs

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.

Run a task

run_task

Run a task

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

skyvern.runTask(request: RunTaskOptions): Promise<TaskRunResponse>

Parameters

str

required

The goal or task description for Skyvern to accomplish

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 and yutori_navigator are also accepted.Default: RunEngine.skyvern_v1

dict[str, Any] | None

Optional model configuration.Default: None

str | None

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

str | None

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

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 for more details.Default: None

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 for more details.Default: None

str | None

The title for the taskDefault: None

dict[str, str] | None

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

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/.Default: None

ProxyLocationInput

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

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 for custom pricing.Default: None

bool

Wait for the run to reach a final status before returning.Default: False · TypeScript: waitForCompletion

float

Maximum time to wait for completion, in seconds.Default: 1800

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

str | None

User-Agent string the browser sends.Default: None · TypeScript: x-user-agent

dict[str, str] | None

The extra HTTP headers for the requests in browser.Default: None

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

bool | None

Whether to include action history when verifying that the task is completeDefault: None

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

str | None

The CDP address for the task.Default: None

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

string

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

Returns TaskRunResponse · TypeScript Promise<TaskRunResponse>

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

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

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)

await skyvern.get_run(run_id: str) -> GetRunResponse

skyvern.getRun(runId: string): Promise<GetRunResponse>

Parameters

str

required

The id of the task run or the workflow run.TypeScript: runId

Returns GetRunResponse · TypeScript Promise<GetRunResponse> Example

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

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

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]

skyvern.getRunsV2(request?: GetRunsV2Request): Promise<TaskRunListItem[]>

Parameters

int | None

Default: None

int | None

Default: None

RunStatus | Sequence[RunStatus] | None

Default: None

str | None

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

RunType | Sequence[RunType] | None

Default: None

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

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

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

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)

await skyvern.get_run_timeline(run_id: str) -> list[WorkflowRunTimeline]

skyvern.getRunTimeline(runId: string): Promise<WorkflowRunTimeline[]>

Parameters

str

required

The id of the workflow run or task_v2 run.TypeScript: runId

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

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

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

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)

await skyvern.cancel_run(run_id: str) -> Any | None

skyvern.cancelRun(runId: string): Promise<unknown>

Parameters

str

required

The id of the task run or the workflow run to cancel.TypeScript: runId

Returns Any | None · TypeScript Promise<unknown> Example

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

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

await skyvern.bulk_cancel_runs(*, run_ids: Sequence[str]) -> BulkCancelRunsResponse

skyvern.bulkCancelRuns(request: BulkCancelRunsRequest): Promise<BulkCancelRunsResponse>

Parameters

Sequence[str]

required

List of run IDs to cancel

Returns BulkCancelRunsResponse · TypeScript Promise<BulkCancelRunsResponse>

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

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

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

await skyvern.retry_run_webhook(
    run_id: str,
    *,
    request: RetryRunWebhookRequest | None = None,
) -> RunWebhookReplayResponse

skyvern.retryRunWebhook(runId: string, request?: RetryRunWebhookRequest): Promise<RunWebhookReplayResponse>

Parameters

str

required

The id of the task run or the workflow run.TypeScript: runId

RetryRunWebhookRequest | None

Default: None

Returns RunWebhookReplayResponse · TypeScript Promise<RunWebhookReplayResponse>

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

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

import { Skyvern } from "@skyvern/client";

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

SDK

Browser automation

API client

Run a task

run_task

Inspect and manage runs

get_run

get_runs_v2

get_run_timeline

cancel_run

bulk_cancel_runs

retry_run_webhook

​Run a task

​run_task

​Inspect and manage runs

​get_run

​get_runs_v2

​get_run_timeline

​cancel_run

​bulk_cancel_runs

​retry_run_webhook

Run a task

run_task

Inspect and manage runs

get_run

get_runs_v2

get_run_timeline

cancel_run

bulk_cancel_runs

retry_run_webhook