Run a workflow

Query parameters

templatebooleanOptionalDefaults to false

Request

This endpoint expects an object.

workflow_idstringRequired

ID of the workflow to run. Workflow ID starts with wpid_.

parametersmap from strings to any or nullOptional

Parameters to pass to the workflow

titlestring or nullOptional

The title for this workflow run

proxy_locationenum or object or map from strings to any or nullOptional

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

Available geotargeting options:

RESIDENTIAL: the default value. Skyvern Cloud uses a random US residential proxy.
RESIDENTIAL_ES: Spain
RESIDENTIAL_IE: Ireland
RESIDENTIAL_GB: United Kingdom
RESIDENTIAL_IN: India
RESIDENTIAL_JP: Japan
RESIDENTIAL_FR: France
RESIDENTIAL_DE: Germany
RESIDENTIAL_NZ: New Zealand
RESIDENTIAL_ZA: South Africa
RESIDENTIAL_AR: Argentina
RESIDENTIAL_AU: Australia
RESIDENTIAL_ISP: ISP proxy
US-CA: California
US-NY: New York
US-TX: Texas
US-FL: Florida
US-WA: Washington
NONE: No proxy Can also be a GeoTarget object for granular city/state targeting: {“country”: “US”, “subdivision”: “CA”, “city”: “San Francisco”}

Geographic Proxy location to route the browser traffic through. This is only available in Skyvern Cloud. Available geotargeting options: - RESIDENTIAL: the default value. Skyvern Cloud uses a random US residential proxy. - RESIDENTIAL_ES: Spain - RESIDENTIAL_IE: Ireland - RESIDENTIAL_GB: United Kingdom - RESIDENTIAL_IN: India - RESIDENTIAL_JP: Japan - RESIDENTIAL_FR: France - RESIDENTIAL_DE: Germany - RESIDENTIAL_NZ: New Zealand - RESIDENTIAL_ZA: South Africa - RESIDENTIAL_AR: Argentina - RESIDENTIAL_AU: Australia - RESIDENTIAL_ISP: ISP proxy - US-CA: California - US-NY: New York - US-TX: Texas - US-FL: Florida - US-WA: Washington - NONE: No proxy Can also be a GeoTarget object for granular city/state targeting: {"country": "US", "subdivision": "CA", "city": "San Francisco"}

webhook_urlstring or nullOptional

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.

totp_urlstring or nullOptional

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.

totp_identifierstring or nullOptional

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.

browser_session_idstring or nullOptional

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

browser_profile_idstring or nullOptional

ID of a browser profile to reuse for this workflow run

max_screenshot_scrollsinteger or nullOptional

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

extra_http_headersmap from strings to strings or nullOptional

The extra HTTP headers for the requests in browser.

browser_addressstring or nullOptional

The CDP address for the workflow run.

ai_fallbackboolean or nullOptional

Whether to fallback to AI if the workflow run fails.

run_withstring or nullOptional

Whether to run the workflow with agent or code.

Response

Successfully run workflow

run_idstring

Unique identifier for this run. Run ID starts with tsk_ for task runs and wr_ for workflow runs.

statusenum

Current status of the run

created_atstringformat: "date-time"

Timestamp when this run was created

modified_atstringformat: "date-time"

Timestamp when this run was last modified

run_type"workflow_run"

Type of run - always workflow_run for workflow runs

outputmap from strings to any or list of any or string or null

Output data from the run, if any. Format/schema depends on the data extracted by the run.

downloaded_fileslist of objects or null

List of files downloaded during the run

recording_urlstring or null

URL to the recording of the run

screenshot_urlslist of strings or null

List of last n screenshot URLs in reverse chronological order - the first one the list is the latest screenshot.

failure_reasonstring or null

Reason for failure if the run failed or terminated

queued_atstring or nullformat: "date-time"

Timestamp when this run was queued

started_atstring or nullformat: "date-time"

Timestamp when this run started execution

finished_atstring or nullformat: "date-time"

Timestamp when this run finished

app_urlstring or null

URL to the application UI where the run can be viewed

browser_session_idstring or null

ID of the Skyvern persistent browser session used for this run

browser_profile_idstring or null

ID of the browser profile used for this run

max_screenshot_scrollsinteger or null

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

script_runobject or null

The script run result

errorslist of maps from strings to any or null

The errors for the run

run_withstring or null

Whether the workflow run was executed with agent or code

ai_fallbackboolean or null

Whether to fallback to AI if code run fails.

run_requestobject or null

The original request parameters used to start this workflow run

Errors