Agents

Agents are saved, multi-step automations (called workflows in older SDK versions and in method names). Agent IDs start with wpid_; agent run IDs start with wr_. 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 an agent

run_workflow

Run an agent

await skyvern.run_workflow(
    workflow_id: str,
    parameters: dict[str, Any] | None = None,
    template: bool | None = None,
    title: str | None = None,
    proxy_location: ProxyLocationInput = None,
    webhook_url: str | None = None,
    totp_url: str | None = None,
    totp_identifier: str | None = None,
    browser_session_id: str | None = None,
    max_steps_override: int | None = None,
    user_agent: str | None = None,
    browser_profile_id: str | None = None,
    max_screenshot_scrolls: int | None = None,
    max_elapsed_time_minutes: int | None = None,
    extra_http_headers: dict[str, str] | None = None,
    browser_address: str | None = None,
    ai_fallback: bool | None = None,
    run_with: str | None = None,
    run_metadata: dict[str, str] | None = None,
    wait_for_completion: bool = False,
    timeout: float = 1800,
) -> WorkflowRunResponse

skyvern.runWorkflow(request: RunWorkflowOptions): Promise<WorkflowRunResponse>

Parameters

str

required

ID of the agent (wpid_…).TypeScript: agent_id

dict[str, Any] | None

Parameters to pass to the workflowDefault: None

bool | None

Default: None

str | None

The title for this workflow runDefault: None

ProxyLocationInput

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

str | None

URL to send workflow status updates to after a run is finished. Refer to https://www.skyvern.com/docs/running-tasks/webhooks-faq for webhook questions.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

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

ID of a Skyvern browser session to reuse, having it continue from the current screen stateDefault: None

int | None

Override the agent’s maximum number of steps for this run.Default: None · TypeScript: x-max-steps-override

str | None

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

str | None

ID of a browser profile to reuse for this workflow runDefault: 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

int | None

Timeout this workflow run after the configured elapsed runtime in minutes. When omitted, the platform default is 240 minutes. The maximum configurable value is 480 minutes.Default: None

dict[str, str] | None

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

str | None

The CDP address for the workflow run.Default: None

bool | None

Whether to fallback to AI if the workflow run fails.Default: None

str | None

Whether to run the workflow with agent or code. Null inherits from the workflow setting.Default: None

dict[str, str] | None

String key/value metadata to attach to this workflow run for analytics tag filtering.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

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

Returns WorkflowRunResponse · TypeScript Promise<WorkflowRunResponse>

WorkflowRunResponse 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_with`	`str \| None`	Whether the workflow run was executed with agent or code
`ai_fallback`	`bool \| None`	Whether to fallback to AI if code run fails.
`script_id`	`str \| None`	ID of the cached script used for this workflow run, if any.
`run_request`	`WorkflowRunRequestOutput \| None`	The original request parameters used to start this workflow run

Example

import asyncio

from skyvern import Skyvern

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

asyncio.run(main())

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

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const result = await skyvern.runWorkflow({ agent_id: "wpid_123" });
console.log(result);

retry_workflow_run

Retry a workflow run using the original run parameters.

await skyvern.retry_workflow_run(
    workflow_run_id: str,
    *,
    max_steps_override: int | None = None,
    user_agent: str | None = None,
) -> WorkflowRunResponse

skyvern.retryWorkflowRun(workflowRunId: string, request?: RetryWorkflowRunRequest): Promise<WorkflowRunResponse>

Parameters

str

required

The id of the workflow run to retry.TypeScript: workflowRunId

int | None

Override the agent’s maximum number of steps for this run.Default: None · TypeScript: x-max-steps-override

str | None

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

Returns WorkflowRunResponse · TypeScript Promise<WorkflowRunResponse>

WorkflowRunResponse 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_with`	`str \| None`	Whether the workflow run was executed with agent or code
`ai_fallback`	`bool \| None`	Whether to fallback to AI if code run fails.
`script_id`	`str \| None`	ID of the cached script used for this workflow run, if any.
`run_request`	`WorkflowRunRequestOutput \| None`	The original request parameters used to start this workflow run

Example

import asyncio

from skyvern import Skyvern

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

asyncio.run(main())

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

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

Manage agents

create_workflow

Create a new agent

await skyvern.create_workflow(
    *,
    folder_id: str | None = None,
    json_definition: WorkflowCreateYamlRequest | None = ...,
    yaml_definition: str | None = ...,
) -> Workflow

skyvern.createWorkflow(request: CreateWorkflowRequest): Promise<Workflow>

Parameters

str | None

Optional folder ID to assign the workflow toDefault: None

WorkflowCreateYamlRequest | None

Workflow definition in JSON formatSent only when you pass it · TypeScript: body.json_definition

str | None

Workflow definition in YAML formatSent only when you pass it · TypeScript: body.yaml_definition

WorkflowRequest

required

TypeScript only

Returns Workflow · TypeScript Promise<Workflow>

Workflow fields

Field	Type	Description
`workflow_id`	`str`
`organization_id`	`str`
`title`	`str`
`workflow_permanent_id`	`str`
`version`	`int`
`is_saved_task`	`bool`
`is_template`	`bool \| None`
`description`	`str \| None`
`workflow_definition`	`WorkflowDefinition`
`proxy_location`	"RESIDENTIAL" \| "US-CA" \| "US-NY" \| "US-TX" \| "US-FL" \| "US-WA" \| "RESIDENTIAL_ES" \| "RESIDENTIAL_IE" \| "RESIDENTIAL_GB" \| "RESIDENTIAL_IN" \| "RESIDENTIAL_JP" \| "RESIDENTIAL_FR" \| "RESIDENTIAL_DE" \| "RESIDENTIAL_NZ" \| "RESIDENTIAL_ZA" \| "RESIDENTIAL_AR" \| "RESIDENTIAL_AU" \| "RESIDENTIAL_BR" \| "RESIDENTIAL_TR" \| "RESIDENTIAL_CA" \| "RESIDENTIAL_MX" \| "RESIDENTIAL_IT" \| "RESIDENTIAL_NL" \| "RESIDENTIAL_PH" \| "RESIDENTIAL_KR" \| "RESIDENTIAL_SA" \| "RESIDENTIAL_ISP" \| "NONE" \| Any \| GeoTarget \| dict[str, Any \| None] \| None
`webhook_callback_url`	`str \| None`
`totp_verification_url`	`str \| None`
`totp_identifier`	`str \| None`
`persist_browser_session`	`bool \| None`
`pin_saved_session_ip`	`bool \| None`
`browser_profile_id`	`str \| None`
`browser_profile_key`	`str \| None`
`model`	`dict[str, Any \| None] \| None`
`status`	`"published" \| "draft" \| "auto_generated" \| "importing" \| "import_failed" \| None`
`max_screenshot_scrolls`	`int \| None`
`max_elapsed_time_minutes`	`int \| None`
`extra_http_headers`	`dict[str, str \| None] \| None`
`cdp_connect_headers`	`dict[str, str \| None] \| None`
`run_with`	`str \| None`
`ai_fallback`	`bool \| None`
`cache_key`	`str \| None`
`adaptive_caching`	`bool \| None`
`enable_self_healing`	`bool \| None`
`code_version`	`int \| None`
`generate_script_on_terminal`	`bool \| None`
`run_sequentially`	`bool \| None`
`sequential_key`	`str \| None`
`folder_id`	`str \| None`
`import_error`	`str \| None`
`created_by`	`str \| None`
`edited_by`	`str \| None`
`copilot_authored`	`bool \| None`
`created_at`	`datetime`
`modified_at`	`datetime`
`deleted_at`	`datetime \| None`
`agent_id`	`str \| None`	Alias of `workflow_permanent_id` — the stable agent identifier (starts with `wpid_`).

Example

import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    result = await skyvern.create_workflow(
        json_definition={
            "title": "Hacker News top post",
            "workflow_definition": {
                "parameters": [],
                "blocks": [
                    {
                        "block_type": "task",
                        "label": "top_post",
                        "url": "https://news.ycombinator.com",
                        "navigation_goal": "Find the top post 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.createWorkflow({
    body: {
        json_definition: {
            title: "Hacker News top post",
            workflow_definition: {
                parameters: [],
                blocks: [
                    {
                        block_type: "task",
                        label: "top_post",
                        url: "https://news.ycombinator.com",
                        navigation_goal: "Find the top post and return its title",
                    },
                ],
            },
        },
    },
});
console.log(result);

get_workflow

Get an agent by id

await skyvern.get_workflow(
    workflow_permanent_id: str,
    *,
    version: int | None = None,
    template: bool | None = None,
) -> Workflow

skyvern.getWorkflow(workflowPermanentId: string, request?: GetWorkflowRequest): Promise<Workflow>

Parameters

str

required

ID of the agent (wpid_…).TypeScript: workflowPermanentId

int | None

Default: None

bool | None

Default: None

Returns Workflow · TypeScript Promise<Workflow>

Workflow fields

Field	Type	Description
`workflow_id`	`str`
`organization_id`	`str`
`title`	`str`
`workflow_permanent_id`	`str`
`version`	`int`
`is_saved_task`	`bool`
`is_template`	`bool \| None`
`description`	`str \| None`
`workflow_definition`	`WorkflowDefinition`
`proxy_location`	"RESIDENTIAL" \| "US-CA" \| "US-NY" \| "US-TX" \| "US-FL" \| "US-WA" \| "RESIDENTIAL_ES" \| "RESIDENTIAL_IE" \| "RESIDENTIAL_GB" \| "RESIDENTIAL_IN" \| "RESIDENTIAL_JP" \| "RESIDENTIAL_FR" \| "RESIDENTIAL_DE" \| "RESIDENTIAL_NZ" \| "RESIDENTIAL_ZA" \| "RESIDENTIAL_AR" \| "RESIDENTIAL_AU" \| "RESIDENTIAL_BR" \| "RESIDENTIAL_TR" \| "RESIDENTIAL_CA" \| "RESIDENTIAL_MX" \| "RESIDENTIAL_IT" \| "RESIDENTIAL_NL" \| "RESIDENTIAL_PH" \| "RESIDENTIAL_KR" \| "RESIDENTIAL_SA" \| "RESIDENTIAL_ISP" \| "NONE" \| Any \| GeoTarget \| dict[str, Any \| None] \| None
`webhook_callback_url`	`str \| None`
`totp_verification_url`	`str \| None`
`totp_identifier`	`str \| None`
`persist_browser_session`	`bool \| None`
`pin_saved_session_ip`	`bool \| None`
`browser_profile_id`	`str \| None`
`browser_profile_key`	`str \| None`
`model`	`dict[str, Any \| None] \| None`
`status`	`"published" \| "draft" \| "auto_generated" \| "importing" \| "import_failed" \| None`
`max_screenshot_scrolls`	`int \| None`
`max_elapsed_time_minutes`	`int \| None`
`extra_http_headers`	`dict[str, str \| None] \| None`
`cdp_connect_headers`	`dict[str, str \| None] \| None`
`run_with`	`str \| None`
`ai_fallback`	`bool \| None`
`cache_key`	`str \| None`
`adaptive_caching`	`bool \| None`
`enable_self_healing`	`bool \| None`
`code_version`	`int \| None`
`generate_script_on_terminal`	`bool \| None`
`run_sequentially`	`bool \| None`
`sequential_key`	`str \| None`
`folder_id`	`str \| None`
`import_error`	`str \| None`
`created_by`	`str \| None`
`edited_by`	`str \| None`
`copilot_authored`	`bool \| None`
`created_at`	`datetime`
`modified_at`	`datetime`
`deleted_at`	`datetime \| None`
`agent_id`	`str \| None`	Alias of `workflow_permanent_id` — the stable agent identifier (starts with `wpid_`).

Example

import asyncio

from skyvern import Skyvern

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

asyncio.run(main())

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

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

get_workflows

Get all workflows with the latest version for the organization. Search semantics:

If search_key is provided, its value is used as a unified search term for workflows.title, folders.title, and workflow parameter metadata (key, description, and default_value for WorkflowParameterModel).
Falls back to deprecated title (title-only search) if search_key is not provided.
Parameter metadata search excludes soft-deleted parameter rows across all parameter tables.

await skyvern.get_workflows(
    *,
    page: int | None = None,
    page_size: int | None = None,
    only_saved_tasks: bool | None = None,
    only_workflows: bool | None = None,
    only_templates: bool | None = None,
    search_key: str | None = None,
    title: str | None = None,
    folder_id: str | None = None,
    status: WorkflowStatus | Sequence[WorkflowStatus] | None = None,
    tags: str | Sequence[str] | None = None,
    template: bool | None = None,
) -> list[Workflow]

skyvern.getWorkflows(request?: GetWorkflowsRequest): Promise<Workflow[]>

Parameters

int | None

Default: None

int | None

Default: None

bool | None

Default: None

bool | None

Default: None

bool | None

Default: None

str | None

Case-insensitive substring search across: workflow title, folder name, and parameter metadata (key, description, default_value). A workflow is returned if any of these fields match. Soft-deleted parameter definitions are excluded. Takes precedence over the deprecated title parameter.Default: None

str | None

Deprecated: use search_key instead. Falls back to title-only search if search_key is not provided.Default: None

str | None

Filter workflows by folder IDDefault: None

WorkflowStatus | Sequence[WorkflowStatus] | None

Default: None

str | Sequence[str] | None

Filter by tags. Each term is a label (production), a group (env:*), or a group:label (env:prod). Repeat the param or comma-separate (?tags=env:prod,env:staging). AND across distinct terms, OR within a group’s labels (?tags=customer:acme,env:prod,env:staging -> customer=acme AND env in (prod, staging)). A label term matches the value across any/no group. Matches current tag values only. Not supported with template=true.Default: None

bool | None

Default: None

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

Workflow fields

Field	Type	Description
`workflow_id`	`str`
`organization_id`	`str`
`title`	`str`
`workflow_permanent_id`	`str`
`version`	`int`
`is_saved_task`	`bool`
`is_template`	`bool \| None`
`description`	`str \| None`
`workflow_definition`	`WorkflowDefinition`
`proxy_location`	"RESIDENTIAL" \| "US-CA" \| "US-NY" \| "US-TX" \| "US-FL" \| "US-WA" \| "RESIDENTIAL_ES" \| "RESIDENTIAL_IE" \| "RESIDENTIAL_GB" \| "RESIDENTIAL_IN" \| "RESIDENTIAL_JP" \| "RESIDENTIAL_FR" \| "RESIDENTIAL_DE" \| "RESIDENTIAL_NZ" \| "RESIDENTIAL_ZA" \| "RESIDENTIAL_AR" \| "RESIDENTIAL_AU" \| "RESIDENTIAL_BR" \| "RESIDENTIAL_TR" \| "RESIDENTIAL_CA" \| "RESIDENTIAL_MX" \| "RESIDENTIAL_IT" \| "RESIDENTIAL_NL" \| "RESIDENTIAL_PH" \| "RESIDENTIAL_KR" \| "RESIDENTIAL_SA" \| "RESIDENTIAL_ISP" \| "NONE" \| Any \| GeoTarget \| dict[str, Any \| None] \| None
`webhook_callback_url`	`str \| None`
`totp_verification_url`	`str \| None`
`totp_identifier`	`str \| None`
`persist_browser_session`	`bool \| None`
`pin_saved_session_ip`	`bool \| None`
`browser_profile_id`	`str \| None`
`browser_profile_key`	`str \| None`
`model`	`dict[str, Any \| None] \| None`
`status`	`"published" \| "draft" \| "auto_generated" \| "importing" \| "import_failed" \| None`
`max_screenshot_scrolls`	`int \| None`
`max_elapsed_time_minutes`	`int \| None`
`extra_http_headers`	`dict[str, str \| None] \| None`
`cdp_connect_headers`	`dict[str, str \| None] \| None`
`run_with`	`str \| None`
`ai_fallback`	`bool \| None`
`cache_key`	`str \| None`
`adaptive_caching`	`bool \| None`
`enable_self_healing`	`bool \| None`
`code_version`	`int \| None`
`generate_script_on_terminal`	`bool \| None`
`run_sequentially`	`bool \| None`
`sequential_key`	`str \| None`
`folder_id`	`str \| None`
`import_error`	`str \| None`
`created_by`	`str \| None`
`edited_by`	`str \| None`
`copilot_authored`	`bool \| None`
`created_at`	`datetime`
`modified_at`	`datetime`
`deleted_at`	`datetime \| None`
`agent_id`	`str \| None`	Alias of `workflow_permanent_id` — the stable agent identifier (starts with `wpid_`).

Example

import asyncio

from skyvern import Skyvern

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

asyncio.run(main())

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

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

get_workflow_versions

Get all versions of a workflow by its permanent ID.

await skyvern.get_workflow_versions(
    workflow_permanent_id: str,
    *,
    template: bool | None = None,
) -> list[Workflow]

skyvern.getWorkflowVersions(workflowPermanentId: string, request?: GetWorkflowVersionsRequest): Promise<Workflow[]>

Parameters

str

required

ID of the agent (wpid_…).TypeScript: workflowPermanentId

bool | None

Default: None

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

Workflow fields

Field	Type	Description
`workflow_id`	`str`
`organization_id`	`str`
`title`	`str`
`workflow_permanent_id`	`str`
`version`	`int`
`is_saved_task`	`bool`
`is_template`	`bool \| None`
`description`	`str \| None`
`workflow_definition`	`WorkflowDefinition`
`proxy_location`	"RESIDENTIAL" \| "US-CA" \| "US-NY" \| "US-TX" \| "US-FL" \| "US-WA" \| "RESIDENTIAL_ES" \| "RESIDENTIAL_IE" \| "RESIDENTIAL_GB" \| "RESIDENTIAL_IN" \| "RESIDENTIAL_JP" \| "RESIDENTIAL_FR" \| "RESIDENTIAL_DE" \| "RESIDENTIAL_NZ" \| "RESIDENTIAL_ZA" \| "RESIDENTIAL_AR" \| "RESIDENTIAL_AU" \| "RESIDENTIAL_BR" \| "RESIDENTIAL_TR" \| "RESIDENTIAL_CA" \| "RESIDENTIAL_MX" \| "RESIDENTIAL_IT" \| "RESIDENTIAL_NL" \| "RESIDENTIAL_PH" \| "RESIDENTIAL_KR" \| "RESIDENTIAL_SA" \| "RESIDENTIAL_ISP" \| "NONE" \| Any \| GeoTarget \| dict[str, Any \| None] \| None
`webhook_callback_url`	`str \| None`
`totp_verification_url`	`str \| None`
`totp_identifier`	`str \| None`
`persist_browser_session`	`bool \| None`
`pin_saved_session_ip`	`bool \| None`
`browser_profile_id`	`str \| None`
`browser_profile_key`	`str \| None`
`model`	`dict[str, Any \| None] \| None`
`status`	`"published" \| "draft" \| "auto_generated" \| "importing" \| "import_failed" \| None`
`max_screenshot_scrolls`	`int \| None`
`max_elapsed_time_minutes`	`int \| None`
`extra_http_headers`	`dict[str, str \| None] \| None`
`cdp_connect_headers`	`dict[str, str \| None] \| None`
`run_with`	`str \| None`
`ai_fallback`	`bool \| None`
`cache_key`	`str \| None`
`adaptive_caching`	`bool \| None`
`enable_self_healing`	`bool \| None`
`code_version`	`int \| None`
`generate_script_on_terminal`	`bool \| None`
`run_sequentially`	`bool \| None`
`sequential_key`	`str \| None`
`folder_id`	`str \| None`
`import_error`	`str \| None`
`created_by`	`str \| None`
`edited_by`	`str \| None`
`copilot_authored`	`bool \| None`
`created_at`	`datetime`
`modified_at`	`datetime`
`deleted_at`	`datetime \| None`
`agent_id`	`str \| None`	Alias of `workflow_permanent_id` — the stable agent identifier (starts with `wpid_`).

Example

import asyncio

from skyvern import Skyvern

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

asyncio.run(main())

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

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

update_workflow

Update an agent

await skyvern.update_workflow(
    workflow_id: str,
    *,
    json_definition: WorkflowCreateYamlRequest | None = ...,
    yaml_definition: str | None = ...,
) -> Workflow

skyvern.updateWorkflow(workflowId: string, request: WorkflowRequest): Promise<Workflow>

Parameters

str

required

The ID of the agent to update. Starts with wpid_.TypeScript: workflowId

WorkflowCreateYamlRequest | None

Workflow definition in JSON formatSent only when you pass it

str | None

Workflow definition in YAML formatSent only when you pass it

Returns Workflow · TypeScript Promise<Workflow>

Workflow fields

Field	Type	Description
`workflow_id`	`str`
`organization_id`	`str`
`title`	`str`
`workflow_permanent_id`	`str`
`version`	`int`
`is_saved_task`	`bool`
`is_template`	`bool \| None`
`description`	`str \| None`
`workflow_definition`	`WorkflowDefinition`
`proxy_location`	"RESIDENTIAL" \| "US-CA" \| "US-NY" \| "US-TX" \| "US-FL" \| "US-WA" \| "RESIDENTIAL_ES" \| "RESIDENTIAL_IE" \| "RESIDENTIAL_GB" \| "RESIDENTIAL_IN" \| "RESIDENTIAL_JP" \| "RESIDENTIAL_FR" \| "RESIDENTIAL_DE" \| "RESIDENTIAL_NZ" \| "RESIDENTIAL_ZA" \| "RESIDENTIAL_AR" \| "RESIDENTIAL_AU" \| "RESIDENTIAL_BR" \| "RESIDENTIAL_TR" \| "RESIDENTIAL_CA" \| "RESIDENTIAL_MX" \| "RESIDENTIAL_IT" \| "RESIDENTIAL_NL" \| "RESIDENTIAL_PH" \| "RESIDENTIAL_KR" \| "RESIDENTIAL_SA" \| "RESIDENTIAL_ISP" \| "NONE" \| Any \| GeoTarget \| dict[str, Any \| None] \| None
`webhook_callback_url`	`str \| None`
`totp_verification_url`	`str \| None`
`totp_identifier`	`str \| None`
`persist_browser_session`	`bool \| None`
`pin_saved_session_ip`	`bool \| None`
`browser_profile_id`	`str \| None`
`browser_profile_key`	`str \| None`
`model`	`dict[str, Any \| None] \| None`
`status`	`"published" \| "draft" \| "auto_generated" \| "importing" \| "import_failed" \| None`
`max_screenshot_scrolls`	`int \| None`
`max_elapsed_time_minutes`	`int \| None`
`extra_http_headers`	`dict[str, str \| None] \| None`
`cdp_connect_headers`	`dict[str, str \| None] \| None`
`run_with`	`str \| None`
`ai_fallback`	`bool \| None`
`cache_key`	`str \| None`
`adaptive_caching`	`bool \| None`
`enable_self_healing`	`bool \| None`
`code_version`	`int \| None`
`generate_script_on_terminal`	`bool \| None`
`run_sequentially`	`bool \| None`
`sequential_key`	`str \| None`
`folder_id`	`str \| None`
`import_error`	`str \| None`
`created_by`	`str \| None`
`edited_by`	`str \| None`
`copilot_authored`	`bool \| None`
`created_at`	`datetime`
`modified_at`	`datetime`
`deleted_at`	`datetime \| None`
`agent_id`	`str \| None`	Alias of `workflow_permanent_id` — the stable agent identifier (starts with `wpid_`).

Example

import asyncio

from skyvern import Skyvern


async def main() -> None:
    skyvern = Skyvern(api_key="YOUR_API_KEY")
    result = await skyvern.update_workflow(
        workflow_id="wpid_123",
        json_definition={
            "title": "Hacker News top post",
            "workflow_definition": {
                "parameters": [],
                "blocks": [
                    {
                        "block_type": "task",
                        "label": "top_post",
                        "url": "https://news.ycombinator.com",
                        "navigation_goal": "Find the top post and return its title and URL",
                    },
                ],
            },
        },
    )
    print(result)


asyncio.run(main())

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

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const result = await skyvern.updateWorkflow("wpid_123", {
    json_definition: {
        title: "Hacker News top post",
        workflow_definition: {
            parameters: [],
            blocks: [
                {
                    block_type: "task",
                    label: "top_post",
                    url: "https://news.ycombinator.com",
                    navigation_goal: "Find the top post and return its title and URL",
                },
            ],
        },
    },
});
console.log(result);

delete_workflow

Delete an agent

await skyvern.delete_workflow(workflow_id: str) -> Any | None

skyvern.deleteWorkflow(workflowId: string): Promise<unknown>

Parameters

str

required

The ID of the agent to delete. Starts with wpid_.TypeScript: workflowId

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.delete_workflow(workflow_id="wpid_123")
    print(result)

asyncio.run(main())

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

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

Agent runs

get_workflow_runs

List workflow runs across all workflows for the current organization. Results are paginated and can be filtered by status, search_key, and error_code. All filters are combined with AND logic — a run must match every supplied filter to be returned. search_key A case-insensitive substring search that matches against any of the following fields:

Searched field	Description
`workflow_run_id`	The unique run identifier (e.g. `wr_123…`)
Parameter key	The `key` of any workflow parameter definition associated with the run
Parameter description	The `description` of any workflow parameter definition
Run parameter value	The actual value supplied for any parameter when the run was created
`extra_http_headers`	Extra HTTP headers attached to the run (searched as raw JSON text)

Soft-deleted parameter definitions are excluded from key/description matching. A run is returned if any of the fields above contain the search term. error_code An exact-match filter against the error_code field inside each task’s errors JSON array. A run matches if any of its tasks contains an error object with a matching error_code value. Error codes are user-defined strings set during workflow execution (e.g. INVALID_CREDENTIALS, LOGIN_FAILED, CAPTCHA_DETECTED). Combining filters All query parameters use AND logic:

?status=failed — only failed runs
?status=failed&error_code=LOGIN_FAILED — failed runs and have a LOGIN_FAILED error
?status=failed&error_code=LOGIN_FAILED&search_key=prod_credential — all three conditions must match

await skyvern.get_workflow_runs(
    *,
    page: int | None = None,
    page_size: int | None = None,
    status: WorkflowRunStatus | Sequence[WorkflowRunStatus] | None = None,
    search_key: str | None = None,
    error_code: str | None = None,
) -> list[WorkflowRun]

skyvern.getWorkflowRuns(request?: GetWorkflowRunsRequest): Promise<WorkflowRun[]>

Parameters

int | None

Page number for pagination.Default: None

int | None

Number of runs to return per page.Default: None

WorkflowRunStatus | Sequence[WorkflowRunStatus] | None

Filter by one or more run statuses.Default: None

str | None

Case-insensitive substring search across: workflow run ID, parameter key, parameter description, run parameter value, and extra HTTP headers. A run is returned if any of these fields match. Soft-deleted parameter definitions are excluded from key/description matching.Default: None

str | None

Exact-match filter on the error_code field inside each task’s errors JSON array. A run matches if any of its tasks contains an error with a matching error_code. Error codes are user-defined strings set during workflow execution.Default: None

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

WorkflowRun fields

Field	Type	Description
`workflow_run_id`	`str`
`workflow_id`	`str`
`workflow_permanent_id`	`str`
`organization_id`	`str`
`browser_session_id`	`str \| None`
`browser_profile_id`	`str \| None`
`debug_session_id`	`str \| None`
`status`	`"created" \| "queued" \| "running" \| "failed" \| "terminated" \| "canceled" \| "timed_out" \| "completed" \| "paused"`
`extra_http_headers`	`dict[str, str \| None] \| None`
`cdp_connect_headers`	`dict[str, str \| None] \| None`
`proxy_location`	"RESIDENTIAL" \| "US-CA" \| "US-NY" \| "US-TX" \| "US-FL" \| "US-WA" \| "RESIDENTIAL_ES" \| "RESIDENTIAL_IE" \| "RESIDENTIAL_GB" \| "RESIDENTIAL_IN" \| "RESIDENTIAL_JP" \| "RESIDENTIAL_FR" \| "RESIDENTIAL_DE" \| "RESIDENTIAL_NZ" \| "RESIDENTIAL_ZA" \| "RESIDENTIAL_AR" \| "RESIDENTIAL_AU" \| "RESIDENTIAL_BR" \| "RESIDENTIAL_TR" \| "RESIDENTIAL_CA" \| "RESIDENTIAL_MX" \| "RESIDENTIAL_IT" \| "RESIDENTIAL_NL" \| "RESIDENTIAL_PH" \| "RESIDENTIAL_KR" \| "RESIDENTIAL_SA" \| "RESIDENTIAL_ISP" \| "NONE" \| Any \| GeoTarget \| dict[str, Any \| None] \| None
`webhook_callback_url`	`str \| None`
`webhook_failure_reason`	`str \| None`
`totp_verification_url`	`str \| None`
`totp_identifier`	`str \| None`
`failure_reason`	`str \| None`
`failure_category`	`list[dict[str, Any \| None]] \| None`
`parent_workflow_run_id`	`str \| None`
`workflow_title`	`str \| None`
`max_screenshot_scrolls`	`int \| None`
`max_elapsed_time_minutes`	`int \| None`
`browser_address`	`str \| None`
`run_with`	`str \| None`
`script_run`	`ScriptRunResponse \| None`
`job_id`	`str \| None`
`depends_on_workflow_run_id`	`str \| None`
`sequential_key`	`str \| None`
`ai_fallback`	`bool \| None`
`code_gen`	`bool \| None`
`trigger_type`	`"manual" \| "mcp" \| "api" \| "scheduled" \| "webhook" \| None`
`workflow_schedule_id`	`str \| None`
`ignore_inherited_workflow_system_prompt`	`bool \| None`
`copilot_session_id`	`str \| None`
`credits_used`	`int \| None`
`cached_credits_used`	`int \| None`
`queued_at`	`datetime \| None`
`started_at`	`datetime \| None`
`finished_at`	`datetime \| 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_workflow_runs()
    print(result)

asyncio.run(main())

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

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

get_workflow_runs_by_id

List runs for a specific workflow. Supports filtering by status, search_key, and error_code. All filters are combined with AND logic. search_key Case-insensitive substring search across: workflow run ID, parameter key, parameter description, run parameter value, and extra HTTP headers. Soft-deleted parameter definitions are excluded. error_code Exact-match filter on the error_code field inside each task’s errors JSON array. A run matches if any of its tasks contains an error with a matching error_code.

await skyvern.get_workflow_runs_by_id(
    workflow_id: str,
    *,
    page: int | None = None,
    page_size: int | None = None,
    status: WorkflowRunStatus | Sequence[WorkflowRunStatus] | None = None,
    search_key: str | None = None,
    error_code: str | None = None,
    created_at_start: datetime | None = None,
    created_at_end: datetime | None = None,
) -> list[WorkflowRun]

skyvern.getWorkflowRunsById(workflowId: string, request?: GetWorkflowRunsByIdRequest): Promise<WorkflowRun[]>

Parameters

str

required

ID of the agent (wpid_…).TypeScript: workflowId

int | None

Page number for pagination.Default: None

int | None

Number of runs to return per page.Default: None

WorkflowRunStatus | Sequence[WorkflowRunStatus] | None

Filter by one or more run statuses.Default: None

str | None

datetime | None

Only include runs created at or after this UTC timestamp (ISO 8601).Default: None

datetime | None

Only include runs created strictly before this UTC timestamp (ISO 8601).Default: None

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

WorkflowRun fields

Field	Type	Description
`workflow_run_id`	`str`
`workflow_id`	`str`
`workflow_permanent_id`	`str`
`organization_id`	`str`
`browser_session_id`	`str \| None`
`browser_profile_id`	`str \| None`
`debug_session_id`	`str \| None`
`status`	`"created" \| "queued" \| "running" \| "failed" \| "terminated" \| "canceled" \| "timed_out" \| "completed" \| "paused"`
`extra_http_headers`	`dict[str, str \| None] \| None`
`cdp_connect_headers`	`dict[str, str \| None] \| None`
`proxy_location`	"RESIDENTIAL" \| "US-CA" \| "US-NY" \| "US-TX" \| "US-FL" \| "US-WA" \| "RESIDENTIAL_ES" \| "RESIDENTIAL_IE" \| "RESIDENTIAL_GB" \| "RESIDENTIAL_IN" \| "RESIDENTIAL_JP" \| "RESIDENTIAL_FR" \| "RESIDENTIAL_DE" \| "RESIDENTIAL_NZ" \| "RESIDENTIAL_ZA" \| "RESIDENTIAL_AR" \| "RESIDENTIAL_AU" \| "RESIDENTIAL_BR" \| "RESIDENTIAL_TR" \| "RESIDENTIAL_CA" \| "RESIDENTIAL_MX" \| "RESIDENTIAL_IT" \| "RESIDENTIAL_NL" \| "RESIDENTIAL_PH" \| "RESIDENTIAL_KR" \| "RESIDENTIAL_SA" \| "RESIDENTIAL_ISP" \| "NONE" \| Any \| GeoTarget \| dict[str, Any \| None] \| None
`webhook_callback_url`	`str \| None`
`webhook_failure_reason`	`str \| None`
`totp_verification_url`	`str \| None`
`totp_identifier`	`str \| None`
`failure_reason`	`str \| None`
`failure_category`	`list[dict[str, Any \| None]] \| None`
`parent_workflow_run_id`	`str \| None`
`workflow_title`	`str \| None`
`max_screenshot_scrolls`	`int \| None`
`max_elapsed_time_minutes`	`int \| None`
`browser_address`	`str \| None`
`run_with`	`str \| None`
`script_run`	`ScriptRunResponse \| None`
`job_id`	`str \| None`
`depends_on_workflow_run_id`	`str \| None`
`sequential_key`	`str \| None`
`ai_fallback`	`bool \| None`
`code_gen`	`bool \| None`
`trigger_type`	`"manual" \| "mcp" \| "api" \| "scheduled" \| "webhook" \| None`
`workflow_schedule_id`	`str \| None`
`ignore_inherited_workflow_system_prompt`	`bool \| None`
`copilot_session_id`	`str \| None`
`credits_used`	`int \| None`
`cached_credits_used`	`int \| None`
`queued_at`	`datetime \| None`
`started_at`	`datetime \| None`
`finished_at`	`datetime \| 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_workflow_runs_by_id(workflow_id="wpid_123")
    print(result)

asyncio.run(main())

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

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

SDK

Browser automation

API client

Run an agent

run_workflow

retry_workflow_run

Manage agents

create_workflow

get_workflow

get_workflows

get_workflow_versions

update_workflow

delete_workflow

Agent runs

get_workflow_runs

get_workflow_runs_by_id

​Run an agent

​run_workflow

​retry_workflow_run

​Manage agents

​create_workflow

​get_workflow

​get_workflows

​get_workflow_versions

​update_workflow

​delete_workflow

​Agent runs

​get_workflow_runs

​get_workflow_runs_by_id

Run an agent

run_workflow

retry_workflow_run

Manage agents

create_workflow

get_workflow

get_workflows

get_workflow_versions

update_workflow

delete_workflow

Agent runs

get_workflow_runs

get_workflow_runs_by_id