Skip to main content
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.

Quick reference

Block TypeUse this to
navigationNavigate websites and take actions with a goal
actionTake a single action on the current page
extractionExtract structured data from a page
loginAuthenticate using stored credentials
taskLegacy block combining navigation and extraction
task_v2Simplified task block using natural language prompts
validationAssert conditions and control workflow flow
conditionalBranch workflow based on conditions
for_loopIterate over arrays and repeat nested blocks
goto_urlNavigate directly to a URL
file_downloadDownload files from websites
file_url_parserParse CSV, Excel, or PDF files
pdf_parserParse PDF files specifically (deprecated, use file_url_parser)
download_to_s3Download a file from URL to S3
upload_to_s3Upload workflow files to S3
file_uploadUpload files to S3 or Azure storage
http_requestMake HTTP API calls
send_emailSend emails with attachments
codeExecute custom Python code
text_promptMake LLM calls for text generation
print_pageSave current page as PDF
waitPause execution for a duration
human_interactionPause for human approval via email

Common parameters

These parameters are available on all block types:
ParameterTypeDefaultDescription
labelstringRequired. Unique identifier for this block within the workflow. Used for referencing outputs as {{label_output}}.
continue_on_failurebooleanfalseIf true, workflow continues even if this block fails.
next_loop_on_failurebooleanfalseIf true and inside a loop, skips to next iteration on failure.
next_block_labelstringLabel of the next block to execute. If omitted, uses sequential order.
modelobjectOverride model configuration for this block.

Finally block

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):
workflow_definition:
  parameters: [...]
  blocks:
    - block_type: navigation
      label: main_task
      # ...
    - block_type: send_email
      label: notify_team
      # ...
  finally_block_label: notify_team
The referenced block must be a terminal block — it cannot have a next_block_label.

Error code mapping

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.
{
  "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."
  }
}

Block outputs

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.
  • Print Page: the file path of the saved PDF.
  • Validation / Conditional / Goto URL / Wait / Send Email / Human Interaction: null (control-flow blocks).

Navigate through websites to take actions with a natural language goal.
{
  "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
}
ParameterTypeDefaultDescription
navigation_goalstringRequired. Natural language description of what to do. Include when to COMPLETE or TERMINATE.
urlstringStarting URL. If omitted, continues from previous block’s page.
titlestring""Display title for this block.
enginestring"skyvern-1.0""skyvern-1.0" or "skyvern-2.0".
max_steps_per_runintegerMaximum steps this block can take.
max_retriesinteger0Number of retry attempts on failure.
parameter_keysarrayParameters this block can access.
error_code_mappingobjectMap conditions to custom error codes.
complete_on_downloadbooleanfalseComplete when a file download is triggered.
download_suffixstringFilename for the downloaded file.
complete_criterionstringNatural language condition for completion.
terminate_criterionstringNatural language condition for termination.
complete_verificationbooleantrueWhether to verify completion criteria.
include_action_history_in_verificationbooleanfalseInclude action history when verifying completion.
totp_identifierstringTOTP credential identifier for 2FA.
totp_verification_urlstringURL to fetch TOTP codes.
disable_cachebooleanfalseDisable caching for this block.
For guidance on which engine to choose (skyvern-1.0 vs skyvern-2.0), see Engine Selection.

Action

Take a single action on the current page without navigation.
{
  "block_type": "action",
  "label": "click_download_button",
  "navigation_goal": "Click the \"Download PDF\" button",
  "engine": "skyvern-1.0"
}
ParameterTypeDefaultDescription
navigation_goalstringDescription of the action to take.
urlstringURL to navigate to first.
titlestring""Display title for this block.
enginestring"skyvern-1.0"AI engine to use ("skyvern-1.0" or "skyvern-2.0").
max_retriesinteger0Number of retry attempts.
parameter_keysarrayParameters this block can access.
error_code_mappingobjectMap conditions to custom error codes.
complete_on_downloadbooleanfalseComplete when download triggered.
download_suffixstringFilename for the downloaded file.
totp_identifierstringTOTP credential identifier.
totp_verification_urlstringURL to fetch TOTP codes.
disable_cachebooleanfalseDisable caching for this block.

Extraction

Extract structured data from a page without taking any actions.
{
  "block_type": "extraction",
  "label": "extract_credentials",
  "data_extraction_goal": "Extract the professional credentials including ASHA account number, certification status, and valid through date.",
  "data_schema": {
    "type": "object",
    "properties": {
      "asha_account_number": { "type": "string" },
      "certification_status": { "type": "string" },
      "valid_through": { "type": "string" }
    }
  }
}
ParameterTypeDefaultDescription
data_extraction_goalstringRequired. What data to extract.
urlstringURL to extract from. If omitted, uses current page.
titlestring""Display title for this block.
data_schemaobject/array/stringJSON Schema for the output structure.
enginestring"skyvern-1.0"AI engine to use ("skyvern-1.0" or "skyvern-2.0").
max_retriesinteger0Retry attempts.
max_steps_per_runintegerMaximum steps allowed.
parameter_keysarrayParameters this block can access.
disable_cachebooleanfalseDisable caching for this block.

Login

Authenticate to a website using stored credentials.
{
  "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."
}
ParameterTypeDefaultDescription
urlstringLogin page URL.
navigation_goalstringAdditional instructions for complex login flows.
titlestring""Display title for this block.
enginestring"skyvern-1.0"AI engine to use ("skyvern-1.0" or "skyvern-2.0").
parameter_keysarrayParameters including credential reference.
error_code_mappingobjectMap conditions to custom error codes.
max_retriesinteger0Retry attempts.
max_steps_per_runintegerMaximum steps allowed.
complete_criterionstringCondition for completion.
terminate_criterionstringCondition for termination.
complete_verificationbooleantrueVerify completion criteria.
totp_identifierstringTOTP credential identifier for 2FA.
totp_verification_urlstringURL to fetch TOTP codes.
disable_cachebooleanfalseDisable caching for this block.

Task

Legacy block combining navigation and extraction. For new workflows, prefer separate Navigation and Extraction blocks.
{
  "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" }
    }
  }
}
ParameterTypeDefaultDescription
urlstringStarting URL.
navigation_goalstringWhat to do on the page.
data_extraction_goalstringWhat data to extract.
data_schemaobject/array/stringSchema for extracted data.
titlestring""Display title for this block.
enginestring"skyvern-1.0"AI engine to use ("skyvern-1.0" or "skyvern-2.0").
parameter_keysarrayAvailable parameters.
error_code_mappingobjectCustom error codes.
max_steps_per_runintegerMaximum steps.
max_retriesinteger0Retry attempts.
complete_on_downloadbooleanfalseComplete when download triggered.
download_suffixstringFilename for the downloaded file.
complete_criterionstringCondition for completion.
terminate_criterionstringCondition for termination.
complete_verificationbooleantrueVerify completion criteria.
include_action_history_in_verificationbooleanfalseInclude action history in verification.
totp_identifierstringTOTP credential identifier.
totp_verification_urlstringURL to fetch TOTP codes.
disable_cachebooleanfalseDisable caching.

Task V2

Simplified task block using natural language prompts. Uses computer-use agents for more flexible automation.
{
  "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
}
ParameterTypeDefaultDescription
promptstringRequired. Natural language description of the task.
urlstringStarting URL.
max_iterationsinteger10Maximum number of iterations.
max_stepsinteger25Maximum steps per iteration.
totp_identifierstringTOTP credential identifier.
totp_verification_urlstringURL to fetch TOTP codes.
disable_cachebooleanfalseDisable 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}}".

Validation

Assert conditions using the LLM to control workflow flow.
{
  "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."
}
ParameterTypeDefaultDescription
complete_criterionstringCondition that must be true to continue.
terminate_criterionstringCondition that terminates the workflow.
parameter_keysarrayParameters to evaluate.
error_code_mappingobjectMap conditions to custom error codes.
disable_cachebooleanfalseDisable caching.

Conditional

Branch workflow execution based on conditions. Supports Jinja2 templates or LLM-based evaluation.
{
  "block_type": "conditional",
  "label": "check_status",
  "branch_conditions": [
    {
      "criteria": {
        "criteria_type": "jinja2_template",
        "expression": "{{ status == 'approved' }}"
      },
      "next_block_label": "process_approved",
      "description": "Route to approval processing"
    },
    {
      "criteria": {
        "criteria_type": "jinja2_template",
        "expression": "{{ status == 'rejected' }}"
      },
      "next_block_label": "handle_rejection"
    },
    {
      "is_default": true,
      "next_block_label": "handle_pending"
    }
  ]
}
ParameterTypeDefaultDescription
branch_conditionsarrayRequired. List of conditions and their target blocks.
Branch Condition properties:
PropertyTypeDefaultDescription
criteriaobjectThe condition to evaluate.
criteria.criteria_typestring"jinja2_template""jinja2_template" or "prompt".
criteria.expressionstringRequired. Jinja2 expression or natural language prompt.
criteria.descriptionstringDescription of the criteria.
next_block_labelstringBlock to execute if condition is true.
descriptionstringDescription of this branch.
is_defaultbooleanfalseIf true, this branch is used when no other conditions match.

For Loop

Iterate over an array and execute nested blocks for each item.
{
  "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."
    }
  ]
}
ParameterTypeDefaultDescription
loop_blocksarrayRequired. Blocks to execute for each iteration.
loop_over_parameter_keystring""Parameter containing the array to iterate.
loop_variable_referencestringCustom name for the loop variable.
complete_if_emptybooleanfalseIf 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 inside loop_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.

Goto URL

Navigate directly to a URL without any AI processing.
{
  "block_type": "goto_url",
  "label": "go_to_dashboard",
  "url": "https://app.example.com/dashboard"
}
ParameterTypeDefaultDescription
urlstringRequired. URL to navigate to.

File Download

Navigate to download a file from a website.
{
  "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"
}
ParameterTypeDefaultDescription
navigation_goalstringRequired. How to find and download the file.
urlstringStarting URL.
titlestring""Display title for this block.
enginestring"skyvern-1.0"AI engine to use ("skyvern-1.0" or "skyvern-2.0").
download_suffixstringFilename for the downloaded file.
download_timeoutnumberTimeout in seconds for download.
parameter_keysarrayParameters this block can access.
error_code_mappingobjectMap conditions to custom error codes.
max_retriesinteger0Retry attempts.
max_steps_per_runintegerMaximum steps.
totp_identifierstringTOTP credential identifier.
totp_verification_urlstringURL to fetch TOTP codes.
disable_cachebooleanfalseDisable 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.

File Parser

Download and parse a file from a URL. Supports CSV, Excel, and PDF files.
{
  "block_type": "file_url_parser",
  "label": "parse_order_csv",
  "file_url": "{{order_file_url}}",
  "file_type": "csv"
}
ParameterTypeDefaultDescription
file_urlstringRequired. URL of the file to parse.
file_typestringRequired. One of: csv, excel, pdf.
json_schemaobjectSchema for structured extraction.

PDF Parser

Deprecated. Use File Parser with file_type: "pdf" instead. This block will be removed in a future version.
Parse a PDF file specifically for text extraction.
{
  "block_type": "pdf_parser",
  "label": "parse_resume",
  "file_url": "{{resume}}"
}
ParameterTypeDefaultDescription
file_urlstringRequired. URL of the PDF file.
json_schemaobjectSchema for structured extraction from PDF.

Download to S3

Download a file from a URL directly to S3 storage.
{
  "block_type": "download_to_s3",
  "label": "save_report",
  "url": "https://example.com/report.pdf"
}
ParameterTypeDefaultDescription
urlstringRequired. URL of the file to download.

Upload to S3

Upload files from the workflow to S3 storage.
{
  "block_type": "upload_to_s3",
  "label": "upload_results",
  "path": "{{download_report_output}}"
}
ParameterTypeDefaultDescription
pathstringPath to the file to upload.

File Upload

Upload downloaded files to AWS S3 or Azure Blob storage.
{
  "block_type": "file_upload",
  "label": "upload_to_s3",
  "storage_type": "s3",
  "aws_access_key_id": "{{aws_access_key}}",
  "aws_secret_access_key": "{{aws_secret_key}}",
  "s3_bucket": "company-invoices",
  "region_name": "us-west-2",
  "path": "SKYVERN_DOWNLOAD_DIRECTORY"
}
S3 Parameters:
ParameterTypeDefaultDescription
storage_typestringSet to "s3" for AWS S3.
aws_access_key_idstringAWS access key.
aws_secret_access_keystringAWS secret key.
s3_bucketstringTarget S3 bucket name.
region_namestringAWS region.
pathstringPath to the file to upload.
Azure Parameters:
ParameterTypeDefaultDescription
storage_typestringSet to "azure" for Azure Blob Storage.
azure_storage_account_namestringAzure storage account name.
azure_storage_account_keystringAzure storage account key.
azure_blob_container_namestringAzure blob container name.
azure_folder_pathstringFolder path within the container.
pathstringPath to the file to upload.

HTTP Request

Make HTTP API calls to external services.
{
  "block_type": "http_request",
  "label": "post_to_webhook",
  "method": "POST",
  "url": "https://api.example.com/webhook",
  "headers": {
    "Authorization": "Bearer {{api_token}}",
    "Content-Type": "application/json"
  },
  "body": {
    "data": "{{extracted_data}}"
  },
  "timeout": 30
}
ParameterTypeDefaultDescription
urlstringURL to make the request to.
methodstring"GET"HTTP method: GET, POST, PUT, DELETE, etc.
headersobjectHTTP headers as key-value pairs.
bodyobjectRequest body (for POST, PUT, etc.).
filesobjectFiles to upload as multipart form data.
timeoutinteger30Request timeout in seconds.
follow_redirectsbooleantrueWhether to follow HTTP redirects.
download_filenamestringFilename for downloaded response.
save_response_as_filebooleanfalseSave response body as a file.
parameter_keysarrayParameters this block can access.

Send Email

Send an email with optional attachments.
{
  "block_type": "send_email",
  "label": "send_confirmation",
  "smtp_host_secret_parameter_key": "smtp_host",
  "smtp_port_secret_parameter_key": "smtp_port",
  "smtp_username_secret_parameter_key": "smtp_username",
  "smtp_password_secret_parameter_key": "smtp_password",
  "sender": "notifications@company.com",
  "recipients": ["{{recipient_email}}", "compliance@company.com"],
  "subject": "EIN Registration Complete - {{company_name}}",
  "body": "Your EIN registration has been completed. See attached for details.",
  "file_attachments": ["SKYVERN_DOWNLOAD_DIRECTORY"]
}
ParameterTypeDefaultDescription
smtp_host_secret_parameter_keystringRequired. Parameter key for SMTP host.
smtp_port_secret_parameter_keystringRequired. Parameter key for SMTP port.
smtp_username_secret_parameter_keystringRequired. Parameter key for SMTP username.
smtp_password_secret_parameter_keystringRequired. Parameter key for SMTP password.
senderstringRequired. Sender email address.
recipientsarrayRequired. List of recipient email addresses.
subjectstringRequired. Email subject line.
bodystringRequired. Email body content.
file_attachmentsarrayFiles to attach. Use SKYVERN_DOWNLOAD_DIRECTORY for downloaded files.

Code

Execute custom Python code for data transformation or browser control.
{
  "block_type": "code",
  "label": "calculate_price_diff",
  "parameter_keys": ["alibaba_price", "amazon_price"],
  "code": "if amazon_price and alibaba_price:\n    result = {'difference': alibaba_price - amazon_price}\nelse:\n    result = None"
}
ParameterTypeDefaultDescription
codestringRequired. Python code to execute. Store result in result variable.
parameter_keysarrayParameters available to the code.
Available objects: skyvern_page (Playwright page object for browser control).
Code Block with browser control is invite-only on Skyvern Cloud. Contact support@skyvern.com for access.

Text Prompt

Make an LLM call for text generation or analysis.
{
  "block_type": "text_prompt",
  "label": "summarize_credentials",
  "llm_key": "OPENAI_GPT4O",
  "parameter_keys": ["extract_credentials_output"],
  "prompt": "Analyze these professional credentials and provide a summary including current status, any concerns, and recommended actions: {{extract_credentials_output}}",
  "json_schema": {
    "type": "object",
    "properties": {
      "status_summary": { "type": "string" },
      "concerns": { "type": "array", "items": { "type": "string" } }
    }
  }
}
ParameterTypeDefaultDescription
promptstringRequired. The prompt to send to the LLM.
parameter_keysarrayParameters available in the prompt.
llm_keystringModel to use (e.g., OPENAI_GPT4O).
json_schemaobjectSchema for structured output.

Save the current browser page as a PDF file.
{
  "block_type": "print_page",
  "label": "save_receipt",
  "custom_filename": "receipt_{{order_id}}",
  "format": "Letter",
  "landscape": false,
  "print_background": true
}
ParameterTypeDefaultDescription
custom_filenamestringCustom filename for the PDF.
formatstring"A4"Page format: A4, Letter, Legal, or Tabloid.
landscapebooleanfalsePrint in landscape orientation.
print_backgroundbooleantrueInclude background colors and images.
include_timestampbooleantrueInclude timestamp in filename.
parameter_keysarrayParameters this block can access.
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.

Wait

Pause workflow execution for a specified duration.
{
  "block_type": "wait",
  "label": "wait_for_processing",
  "wait_sec": 30
}
ParameterTypeDefaultDescription
wait_secinteger0Seconds to wait.

Human Interaction

Pause the workflow and send an email requesting human approval before continuing.
{
  "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."
}
ParameterTypeDefaultDescription
timeout_secondsintegerRequired. How long to wait for a response (in seconds).
senderstringRequired. Email address to send from.
recipientsarrayRequired. List of email addresses to notify.
subjectstringRequired. Email subject line.
bodystringRequired. Email body content.
instructionsstring"Please review and approve or reject to continue the workflow."Instructions shown in the approval interface.
positive_descriptorstring"Approve"Label for the approval button.
negative_descriptorstring"Reject"Label for the rejection button.

Next steps

Build a Workflow

Create and run your first workflow

Workflow Parameters

Pass data between blocks with parameters

File Operations

Parse, download, and upload files

Webhooks

Get notified when workflows complete