API ReferenceWorkflows

Run a workflow

Run a workflow

Headers

x-api-keystring or nullOptional
Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.
x-max-steps-overrideinteger or nullOptional
x-user-agentstring or nullOptional

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_PH: Philippines - RESIDENTIAL_ZA: South Africa - RESIDENTIAL_AR: Argentina - RESIDENTIAL_AU: Australia - RESIDENTIAL_ISP: ISP proxy - US-CA: California (deprecated, routes through RESIDENTIAL_ISP) - US-NY: New York (deprecated, routes through RESIDENTIAL_ISP) - US-TX: Texas (deprecated, routes through RESIDENTIAL_ISP) - US-FL: Florida (deprecated, routes through RESIDENTIAL_ISP) - US-WA: Washington (deprecated, routes through RESIDENTIAL_ISP) - 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
step_countinteger or null
Total number of steps executed in this 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