This page covers all block types available for building workflows.Blocks are defined in the workflow_definition.blocks array. Use JSON when passing a json_definition or YAML when passing a yaml_definition — both formats are shown for every block below.
You can designate any block as a “finally” block that always executes when the workflow ends — whether it completed, failed, terminated, or timed out. The only exception is explicit cancellation.Set finally_block_label at the workflow definition level (alongside parameters and blocks):
Several blocks accept an error_code_mapping parameter. This is an object mapping custom error codes to natural language descriptions. Skyvern evaluates each description against the current page state and surfaces matching errors in the block output.
Copy
Ask AI
{ "error_code_mapping": { "INVALID_CREDENTIALS": "The page shows an error message indicating the username or password is incorrect.", "ACCOUNT_LOCKED": "The page indicates the account has been locked or suspended.", "CAPTCHA_REQUIRED": "A CAPTCHA challenge is displayed that cannot be solved." }}
Every block produces an output accessible by other blocks as {{label_output}}, where label is the block’s label value. The output shape depends on the block type:
Navigation / Action / Login / File Download: the output is null on success (the primary effect is the browser state change).
Extraction: the output matches the data_schema you provide (or a free-form object if no schema is given).
Task: null when only navigation_goal is set. When data_extraction_goal is set, the output matches the data_schema.
Code: the value of the result variable at the end of execution.
Text Prompt: the LLM response, structured according to json_schema if provided.
File Parser / PDF Parser: the parsed file content (structured if json_schema is provided).
For Loop: an array of outputs, one per iteration.
HTTP Request: the response body (as JSON if applicable, otherwise as a string).
Upload to S3 / File Upload / Download to S3: the storage URL of the uploaded/downloaded file.
Navigate through websites to take actions with a natural language goal.
Copy
Ask AI
{ "block_type": "navigation", "label": "search_registry", "url": "https://asha.org/verify", "navigation_goal": "Search for the person using the provided information. COMPLETE when search results are displayed. TERMINATE if no results found.", "parameter_keys": ["first_name", "last_name", "employee_state"], "engine": "skyvern-2.0", "max_steps_per_run": 20}
Parameter
Type
Default
Description
navigation_goal
string
—
Required. Natural language description of what to do. Include when to COMPLETE or TERMINATE.
url
string
—
Starting URL. If omitted, continues from previous block’s page.
title
string
""
Display title for this block.
engine
string
"skyvern-1.0"
"skyvern-1.0" or "skyvern-2.0".
max_steps_per_run
integer
—
Maximum steps this block can take.
max_retries
integer
0
Number of retry attempts on failure.
parameter_keys
array
—
Parameters this block can access.
error_code_mapping
object
—
Map conditions to custom error codes.
complete_on_download
boolean
false
Complete when a file download is triggered.
download_suffix
string
—
Filename for the downloaded file.
complete_criterion
string
—
Natural language condition for completion.
terminate_criterion
string
—
Natural language condition for termination.
complete_verification
boolean
true
Whether to verify completion criteria.
include_action_history_in_verification
boolean
false
Include action history when verifying completion.
totp_identifier
string
—
TOTP credential identifier for 2FA.
totp_verification_url
string
—
URL to fetch TOTP codes.
disable_cache
boolean
false
Disable caching for this block.
For guidance on which engine to choose (skyvern-1.0 vs skyvern-2.0), see Engine Selection.
Authenticate to a website using stored credentials.
Copy
Ask AI
{ "block_type": "login", "label": "login_to_portal", "url": "{{website_url}}", "parameter_keys": ["credentials"], "navigation_goal": "Log in using the provided credentials. Handle any cookie consent or promotional popups first. COMPLETE when on the logged-in dashboard."}
Parameter
Type
Default
Description
url
string
—
Login page URL.
navigation_goal
string
—
Additional instructions for complex login flows.
title
string
""
Display title for this block.
engine
string
"skyvern-1.0"
AI engine to use ("skyvern-1.0" or "skyvern-2.0").
Legacy block combining navigation and extraction. For new workflows, prefer separate Navigation and Extraction blocks.
Copy
Ask AI
{ "block_type": "task", "label": "login_and_extract", "url": "{{website_url}}", "parameter_keys": ["credentials"], "navigation_goal": "Log in using the provided credentials. Navigate to the account settings page. COMPLETE when on the settings page.", "data_extraction_goal": "Extract the account ID and subscription plan.", "data_schema": { "type": "object", "properties": { "account_id": { "type": "string" }, "subscription_plan": { "type": "string" } } }}
Parameter
Type
Default
Description
url
string
—
Starting URL.
navigation_goal
string
—
What to do on the page.
data_extraction_goal
string
—
What data to extract.
data_schema
object/array/string
—
Schema for extracted data.
title
string
""
Display title for this block.
engine
string
"skyvern-1.0"
AI engine to use ("skyvern-1.0" or "skyvern-2.0").
Simplified task block using natural language prompts. Uses computer-use agents for more flexible automation.
Copy
Ask AI
{ "block_type": "task_v2", "label": "complete_form", "url": "https://example.com/form", "prompt": "Fill out the contact form with the provided information and submit it. Wait for the confirmation message.", "max_iterations": 10, "max_steps": 25}
Parameter
Type
Default
Description
prompt
string
—
Required. Natural language description of the task.
url
string
—
Starting URL.
max_iterations
integer
10
Maximum number of iterations.
max_steps
integer
25
Maximum steps per iteration.
totp_identifier
string
—
TOTP credential identifier.
totp_verification_url
string
—
URL to fetch TOTP codes.
disable_cache
boolean
false
Disable caching.
task_v2 does not use parameter_keys. All workflow parameters and previous block outputs are automatically available as Jinja2 template variables in prompt and url. For example: "Fill the form with name {{first_name}} and email {{email}}".
Assert conditions using the LLM to control workflow flow.
Copy
Ask AI
{ "block_type": "validation", "label": "check_credential_status", "parameter_keys": ["extract_credentials_output"], "complete_criterion": "Continue if the certification_status is 'expired' or 'inactive', or if the valid_through date has changed.", "terminate_criterion": "Terminate if the certification_status is 'active' and valid_through matches current_credential_expiry."}
Iterate over an array and execute nested blocks for each item.
Copy
Ask AI
{ "block_type": "for_loop", "label": "apply_to_jobs", "loop_over_parameter_key": "job_urls", "continue_on_failure": true, "loop_blocks": [ { "block_type": "navigation", "label": "submit_application", "url": "{{submit_application.current_value}}", "navigation_goal": "Fill out and submit the job application." } ]}
Parameter
Type
Default
Description
loop_blocks
array
—
Required. Blocks to execute for each iteration.
loop_over_parameter_key
string
""
Parameter containing the array to iterate.
loop_variable_reference
string
—
Custom name for the loop variable.
complete_if_empty
boolean
false
If true, completes successfully when array is empty.
Accessing the current item inside a loopUse {{nested_block_label.current_value}} to reference the current iteration value, where nested_block_label is the label of the block insideloop_blocks — not the label of the for_loop itself.In the example above, the loop label is apply_to_jobs and the nested block label is submit_application, so the current URL is accessed as {{submit_application.current_value}}.
The output of a for_loop block is an array containing the result from each iteration.
{ "block_type": "file_download", "label": "download_ein_letter", "url": "https://irs.gov/ein/confirm", "navigation_goal": "Find and download the EIN confirmation letter PDF. Look for a \"Download\" or \"Print\" button. COMPLETE when download is triggered.", "download_suffix": "ein_confirmation.pdf"}
Parameter
Type
Default
Description
navigation_goal
string
—
Required. How to find and download the file.
url
string
—
Starting URL.
title
string
""
Display title for this block.
engine
string
"skyvern-1.0"
AI engine to use ("skyvern-1.0" or "skyvern-2.0").
download_suffix
string
—
Filename for the downloaded file.
download_timeout
number
—
Timeout in seconds for download.
parameter_keys
array
—
Parameters this block can access.
error_code_mapping
object
—
Map conditions to custom error codes.
max_retries
integer
0
Retry attempts.
max_steps_per_run
integer
—
Maximum steps.
totp_identifier
string
—
TOTP credential identifier.
totp_verification_url
string
—
URL to fetch TOTP codes.
disable_cache
boolean
false
Disable caching.
Downloaded files are stored in SKYVERN_DOWNLOAD_DIRECTORY—use this path in upload_to_s3, file_upload, or send_email’s file_attachments to access them.
The print_page block works via the REST API and TypeScript SDK, but the Python SDK’s generated types do not yet include it. If you use the Python SDK, pass the block definition through json_definition or yaml_definition — the API will accept it.
Pause the workflow and send an email requesting human approval before continuing.
Copy
Ask AI
{ "block_type": "human_interaction", "label": "request_approval", "instructions": "Please review the extracted data and approve or reject to continue.", "positive_descriptor": "Approve", "negative_descriptor": "Reject", "timeout_seconds": 7200, "sender": "workflow@company.com", "recipients": ["manager@company.com"], "subject": "Approval Required - Order Processing", "body": "An order requires your approval before processing can continue."}
Parameter
Type
Default
Description
timeout_seconds
integer
—
Required. How long to wait for a response (in seconds).
sender
string
—
Required. Email address to send from.
recipients
array
—
Required. List of email addresses to notify.
subject
string
—
Required. Email subject line.
body
string
—
Required. Email body content.
instructions
string
"Please review and approve or reject to continue the workflow."