Workflow Parameters

This page covers all parameters you can pass when creating and running workflows.

Quick reference: Creating a workflow

Parameter	Type	Use this to
`title` (Required)	string	Name the workflow for identification
`workflow_definition` (Required)	object	Define blocks, parameters, and logic
`description`	string	Document what the workflow does
`proxy_location`	string or object	Set default proxy for all blocks
`webhook_callback_url`	string	Get notified when any run of this workflow completes
`persist_browser_session`	boolean	Keep the browser session alive across blocks

Quick reference: Running a workflow

Parameter	Type	Use this to
`workflow_id` (Required)	string	Specify which workflow to run
`parameters`	object	Pass values for workflow input parameters
`title`	string	Name this specific workflow run
`proxy_location`	string or object	Override the default proxy location
`webhook_url`	string	Get notified when the workflow completes
`browser_session_id`	string	Reuse a persistent browser session
`browser_profile_id`	string	Reuse a browser profile (cookies, storage)

Creating a workflow

All create parameters (title, workflow_definition, description, proxy_location, etc.) are nested inside a json_definition object — not passed at the top level. You can alternatively use yaml_definition (a YAML string) instead.

workflow = await client.create_workflow(
    json_definition={
        "title": "...",
        "workflow_definition": {...}
    }
)

`title`

Required. Display name for the workflow. This field goes inside the json_definition object.

workflow = await client.create_workflow(
    json_definition={
        "title": "Invoice Downloader",
        "workflow_definition": {...}
    }
)

`workflow_definition`

Required. The workflow structure containing parameters and blocks.

{
  "workflow_definition": {
    "parameters": [...],
    "blocks": [...]
  }
}

`parameters`

Input parameters the workflow accepts. Each parameter has:

Field	Type	Description
`key`	string	Parameter name, used to reference via `{{ key }}`
`parameter_type`	string	Always `"workflow"` for input parameters
`workflow_parameter_type`	string	Data type: `string`, `integer`, `float`, `boolean`, `json`, `file_url`, `credential_id`
`default_value`	any	Optional default value
`description`	string	Optional description

workflow = await client.create_workflow(
    json_definition={
        "title": "Job Application Workflow",
        "workflow_definition": {
            "parameters": [
                {
                    "key": "resume",
                    "parameter_type": "workflow",
                    "workflow_parameter_type": "file_url",
                    "description": "URL to the resume PDF"
                },
                {
                    "key": "job_urls",
                    "parameter_type": "workflow",
                    "workflow_parameter_type": "json",
                    "default_value": []
                },
                {
                    "key": "cover_letter",
                    "parameter_type": "workflow",
                    "workflow_parameter_type": "string",
                    "default_value": ""
                }
            ],
            "blocks": [...]
        }
    }
)

Parameter types:

Type	Description	Example
`string`	Text value	`"John Smith"`
`integer`	Whole number	`42`
`float`	Decimal number	`99.99`
`boolean`	True/false	`true`
`json`	JSON object or array	`{"key": "value"}` or `["a", "b"]`
`file_url`	URL to a file	`"https://example.com/resume.pdf"`
`credential_id`	Reference to a stored credential	`"cred_abc123"`

`blocks`

Array of blocks that execute in sequence. See Workflow Blocks Reference for all block types.

`description`

Optional description of what the workflow does.

workflow = await client.create_workflow(
    json_definition={
        "title": "Invoice Downloader",
        "description": "Downloads all invoices from the vendor portal since a given date",
        "workflow_definition": {...}
    }
)

`proxy_location` (create)

Default proxy location for all blocks in the workflow. Individual blocks can override this. See Proxy & Geo Targeting for all available locations.

workflow = await client.create_workflow(
    json_definition={
        "title": "UK Price Checker",
        "proxy_location": "RESIDENTIAL_GB",
        "workflow_definition": {...}
    }
)

`webhook_callback_url`

URL to receive a POST request whenever any run of this workflow completes. This is set at the workflow level and applies to all runs. To set a webhook for a single run instead, use webhook_url when running the workflow.

workflow = await client.create_workflow(
    json_definition={
        "title": "Invoice Downloader",
        "webhook_callback_url": "https://your-server.com/webhook",
        "workflow_definition": {...}
    }
)

`persist_browser_session`

If true, the browser session is kept alive across all blocks in the workflow. This means blocks share the same browser context including cookies, local storage, and login state. Defaults to false.

workflow = await client.create_workflow(
    json_definition={
        "title": "Multi-Step Portal Scraper",
        "persist_browser_session": True,
        "workflow_definition": {...}
    }
)

Additional advanced parameters are available when creating a workflow, including totp_verification_url, totp_identifier, model, and extra_http_headers. See the API Reference for the full list.

Running a workflow

`workflow_id`

Required. The ID of the workflow to run. This is the workflow_permanent_id returned when creating the workflow.

run = await client.run_workflow(
    workflow_id="wpid_123456789",
    parameters={...}
)

`parameters`

Values for the workflow’s input parameters. Keys must match the key field in the workflow’s parameter definitions.

run = await client.run_workflow(
    workflow_id="wpid_123456789",
    parameters={
        "resume": "https://example.com/resume.pdf",
        "job_urls": [
            "https://jobs.lever.co/company/position-1",
            "https://jobs.lever.co/company/position-2"
        ],
        "cover_letter": "I am excited to apply for this position..."
    }
)

Parameters with default_value in the workflow definition are optional. Parameters without defaults are required.

`proxy_location` (run)

Override the workflow’s default proxy location for this run.

run = await client.run_workflow(
    workflow_id="wpid_123456789",
    parameters={...},
    proxy_location="RESIDENTIAL_CA"
)

Proxy locations:

Value	Location
`RESIDENTIAL`	United States (default)
`RESIDENTIAL_ISP`	United States (static ISP IPs)
`RESIDENTIAL_AR`	Argentina
`RESIDENTIAL_AU`	Australia
`RESIDENTIAL_BR`	Brazil
`RESIDENTIAL_CA`	Canada
`RESIDENTIAL_DE`	Germany
`RESIDENTIAL_ES`	Spain
`RESIDENTIAL_FR`	France
`RESIDENTIAL_GB`	United Kingdom
`RESIDENTIAL_IE`	Ireland
`RESIDENTIAL_IN`	India
`RESIDENTIAL_IT`	Italy
`RESIDENTIAL_JP`	Japan
`RESIDENTIAL_MX`	Mexico
`RESIDENTIAL_NL`	Netherlands
`RESIDENTIAL_NZ`	New Zealand
`RESIDENTIAL_PH`	Philippines
`RESIDENTIAL_KR`	South Korea
`RESIDENTIAL_TR`	Türkiye
`RESIDENTIAL_ZA`	South Africa
`NONE`	No proxy

For US state or city-level targeting, pass a GeoTarget object instead:

{
  "proxy_location": {
    "country": "US",
    "subdivision": "CA",
    "city": "San Francisco"
  }
}

country is required (ISO 3166-1 alpha-2 code). subdivision and city are optional. See Proxy & Geo Targeting for more details.

`webhook_url`

URL to receive a POST request when the workflow completes.

run = await client.run_workflow(
    workflow_id="wpid_123456789",
    parameters={...},
    webhook_url="https://your-server.com/webhook"
)

The webhook payload contains the same data as the polling response. See Webhooks for authentication and retry options.

`title` (run)

Optional display name for this specific workflow run. Useful for distinguishing runs in the UI and API responses.

run = await client.run_workflow(
    workflow_id="wpid_123456789",
    title="January 2025 Invoice Batch",
    parameters={...}
)

`browser_session_id`

ID of an existing Skyvern browser session to reuse. The workflow run continues from the current screen state of that session. Browser session IDs start with pbs_.

run = await client.run_workflow(
    workflow_id="wpid_123456789",
    browser_session_id="pbs_abc123",
    parameters={...}
)

`browser_profile_id`

ID of a browser profile to reuse. Browser profiles persist cookies, local storage, and other browser state across runs. Profile IDs start with bp_.

run = await client.run_workflow(
    workflow_id="wpid_123456789",
    browser_profile_id="bp_xyz789",
    parameters={...}
)

Additional advanced parameters are available when running a workflow, including totp_url, totp_identifier, browser_address, extra_http_headers, and max_screenshot_scrolls. See the API Reference for the full list.

Run response

When you run a workflow, the response contains:

Field	Type	Description
`run_id`	string	Unique ID for this run (starts with `wr_`).
`status`	string	One of: `created`, `queued`, `running`, `completed`, `failed`, `terminated`, `timed_out`, `canceled`.
`output`	object/array/string/null	Extracted data from the workflow, if any.
`failure_reason`	string/null	Why the run failed, if applicable.
`errors`	array/null	List of errors encountered during the run.
`downloaded_files`	array/null	Files downloaded during the run.
`recording_url`	string/null	URL to the browser recording.
`screenshot_urls`	array/null	Latest screenshots in reverse chronological order.
`app_url`	string/null	Link to view this run in the Skyvern UI.
`created_at`	datetime	When the run was created.
`started_at`	datetime/null	When execution started.
`finished_at`	datetime/null	When execution finished.

Next steps

Build a Workflow

Create and run your first workflow

Workflow Blocks Reference

Detailed documentation for all block types

Proxy & Geo Targeting

Full list of proxy locations

Webhooks

Handle webhook authentication and retries

Getting Started

Running Automations

Multi-Step Automations

Optimization

Going to Production

Debugging

Self-Hosted Deployment

Workflow Parameters

Quick reference: Creating a workflow

Quick reference: Running a workflow

Creating a workflow

`title`

`workflow_definition`

`parameters`

`blocks`

`description`

`proxy_location` (create)

`webhook_callback_url`

`persist_browser_session`

Running a workflow

`workflow_id`

`parameters`

`proxy_location` (run)

`webhook_url`

`title` (run)

`browser_session_id`

`browser_profile_id`

Run response

Next steps

Build a Workflow

Workflow Blocks Reference

Proxy & Geo Targeting

Webhooks

Getting Started

Running Automations

Multi-Step Automations

Optimization

Going to Production

Debugging

Self-Hosted Deployment

​Quick reference: Creating a workflow

​Quick reference: Running a workflow

​Creating a workflow

​title

​workflow_definition

​parameters

​blocks

​description

​proxy_location (create)

​webhook_callback_url

​persist_browser_session

​Running a workflow

​workflow_id

​parameters

​proxy_location (run)

​webhook_url

​title (run)

​browser_session_id

​browser_profile_id

​Run response

​Next steps

Build a Workflow

Workflow Blocks Reference

Proxy & Geo Targeting

Webhooks

Quick reference: Creating a workflow

Quick reference: Running a workflow

Creating a workflow

`title`

`workflow_definition`

`parameters`

`blocks`

`description`

`proxy_location` (create)

`webhook_callback_url`

`persist_browser_session`

Running a workflow

`workflow_id`

`parameters`

`proxy_location` (run)

`webhook_url`

`title` (run)

`browser_session_id`

`browser_profile_id`

Run response

Next steps