Workflow Blocks Reference

Overview

Blocks are the building blocks of workflows. Each block performs a specific action: navigating a website, extracting data, downloading files, sending emails, or controlling flow. Blocks are defined in the workflow_definition.blocks array and execute in sequence. You can use JSON or YAML format.

Quick Reference

Block Type	Use this to
`navigation`	Navigate websites and take actions with a goal
`action`	Take a single action on the current page
`extraction`	Extract structured data from a page
`login`	Authenticate using stored credentials
`task`	Legacy block combining navigation and extraction
`task_v2`	Simplified task block using natural language prompts
`validation`	Assert conditions and control workflow flow
`conditional`	Branch workflow based on conditions
`for_loop`	Iterate over arrays and repeat nested blocks
`goto_url`	Navigate directly to a URL
`file_download`	Download files from websites
`file_url_parser`	Parse CSV, Excel, or PDF files
`pdf_parser`	Parse PDF files specifically (deprecated)
`download_to_s3`	Download a file from URL to S3
`upload_to_s3`	Upload workflow files to S3
`file_upload`	Upload files to S3 or Azure storage
`http_request`	Make HTTP API calls
`send_email`	Send emails with attachments
`code`	Execute custom Python code
`text_prompt`	Make LLM calls for text generation
`print_page`	Save current page as PDF
`wait`	Pause execution for a duration
`human_interaction`	Pause for human approval via email

Common Parameters

These parameters are available on all block types:

label

string

required

Required. Unique identifier for this block within the workflow. Used for referencing outputs as {{label_output}}.

continue_on_failure

boolean

default:"false"

If true, workflow continues even if this block fails.

next_loop_on_failure

boolean

default:"false"

If true and inside a loop, skips to next iteration on failure.

next_block_label

string

Label of the next block to execute. If omitted, uses sequential order.

model

object

Override model configuration for this block.

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.",
  "parameter_keys": ["first_name", "last_name", "state"],
  "engine": "skyvern-2.0",
  "max_steps_per_run": 20
}

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

default:""

Display title for this block.

engine

string

default:"skyvern-1.0"

AI engine: skyvern-1.0 or skyvern-2.0.

max_steps_per_run

integer

Maximum steps this block can take.

max_retries

integer

default:"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

default:"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.

totp_identifier

string

TOTP credential identifier for 2FA.

disable_cache

boolean

default:"false"

Disable caching for this block.

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

Description of the action to take.

url

string

URL to navigate to first.

Same additional parameters as navigation block.

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. COMPLETE when on the logged-in dashboard."
}

url

string

Additional instructions for complex login flows.

parameter_keys

array

Parameters including credential reference.

Same additional parameters as navigation block.

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

url

string

required

URL to navigate to.

Data Extraction Blocks

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

data_extraction_goal

string

required

What data to extract.

url

string

URL to extract from. If omitted, uses current page.

data_schema

object

JSON Schema for the output structure.

engine

string

default:"skyvern-1.0"

AI engine to use.

parameter_keys

array

Parameters this block can access.

Text Prompt

Make an LLM call for text generation or analysis.

{
  "block_type": "text_prompt",
  "label": "summarize_credentials",
  "llm_key": "OPENAI_GPT4O",
  "prompt": "Analyze these professional credentials: {{extract_credentials_output}}",
  "json_schema": {
    "type": "object",
    "properties": {
      "status_summary": {"type": "string"},
      "concerns": {"type": "array", "items": {"type": "string"}}
    }
  }
}

prompt

string

required

The prompt to send to the LLM.

llm_key

string

Model to use (e.g., OPENAI_GPT4O).

json_schema

object

Schema for structured output.

parameter_keys

array

Parameters available in the prompt.

Control Flow Blocks

Validation

Assert conditions using the LLM to control workflow flow.

{
  "block_type": "validation",
  "label": "check_credential_status",
  "complete_criterion": "Continue if the certification_status is 'expired' or 'inactive'",
  "terminate_criterion": "Terminate if the certification_status is 'active'"
}

complete_criterion

string

Condition that must be true to continue.

terminate_criterion

string

Condition that terminates the workflow.

parameter_keys

array

Parameters to evaluate.

Conditional

Branch workflow execution based on conditions.

{
  "block_type": "conditional",
  "label": "check_status",
  "branch_conditions": [
    {
      "criteria": {
        "criteria_type": "jinja2_template",
        "expression": "{{ status == 'approved' }}"
      },
      "next_block_label": "process_approved"
    },
    {
      "is_default": true,
      "next_block_label": "handle_pending"
    }
  ]
}

branch_conditions

array

required

List of conditions and their target blocks.

Branch Condition Properties:

criteria.criteria_type

string

default:"jinja2_template"

jinja2_template or prompt.

criteria.expression

string

required

Jinja2 expression or natural language prompt.

next_block_label

string

Block to execute if condition is true.

is_default

boolean

default:"false"

If true, this branch is used when no 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."
    }
  ]
}

loop_blocks

array

required

Blocks to execute for each iteration.

loop_over_parameter_key

string

default:""

Parameter containing the array to iterate.

complete_if_empty

boolean

default:"false"

If true, completes successfully when array is empty.

Accessing the current item: Use {{nested_block_label.current_value}} to reference the current iteration value, where nested_block_label is the label of the block inside loop_blocks.

File Operation Blocks

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.",
  "download_suffix": "ein_confirmation.pdf"
}

How to find and download the file.

url

string

Starting URL.

download_suffix

string

Filename for the downloaded file.

download_timeout

number

Timeout in seconds for download.

Downloaded files are stored in SKYVERN_DOWNLOAD_DIRECTORY.

File URL Parser

Download and parse a file from a URL.

{
  "block_type": "file_url_parser",
  "label": "parse_order_csv",
  "file_url": "{{order_file_url}}",
  "file_type": "csv"
}

file_url

string

required

URL of the file to parse.

file_type

string

required

One of: csv, excel, pdf.

json_schema

object

Schema for structured extraction.

Upload to S3

Upload files from the workflow to S3 storage.

{
  "block_type": "upload_to_s3",
  "label": "upload_results",
  "path": "{{download_report_output}}"
}

path

string

Path 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:

storage_type

string

Set to s3 for AWS S3.

aws_access_key_id

string

AWS access key.

aws_secret_access_key

string

AWS secret key.

s3_bucket

string

Target S3 bucket name.

region_name

string

AWS region.

path

string

Path to the file to upload.

Print Page

Save the current browser page as a PDF file.

{
  "block_type": "print_page",
  "label": "save_receipt",
  "custom_filename": "receipt_{{order_id}}",
  "format": "Letter",
  "print_background": true
}

custom_filename

string

Custom filename for the PDF.

format

string

default:"A4"

Page format: A4, Letter, Legal, or Tabloid.

landscape

boolean

default:"false"

Print in landscape orientation.

print_background

boolean

default:"true"

Include background colors and images.

Integration Blocks

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

url

string

URL to make the request to.

method

string

default:"GET"

HTTP method: GET, POST, PUT, DELETE, etc.

headers

object

HTTP headers as key-value pairs.

body

object

Request body (for POST, PUT, etc.).

timeout

integer

default:"30"

Request timeout in seconds.

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": "[email protected]",
  "recipients": ["{{recipient_email}}"],
  "subject": "EIN Registration Complete",
  "body": "Your EIN registration has been completed.",
  "file_attachments": ["SKYVERN_DOWNLOAD_DIRECTORY"]
}

smtp_host_secret_parameter_key

string

required

Parameter key for SMTP host.

smtp_port_secret_parameter_key

string

required

Parameter key for SMTP port.

smtp_username_secret_parameter_key

string

required

Parameter key for SMTP username.

smtp_password_secret_parameter_key

string

required

Parameter key for SMTP password.

sender

string

required

Sender email address.

recipients

array

required

List of recipient email addresses.

subject

string

required

Email subject line.

body

string

required

Email body content.

file_attachments

array

Files to attach. Use SKYVERN_DOWNLOAD_DIRECTORY for downloaded files.

Human Interaction

Pause the workflow and send an email requesting human approval.

{
  "block_type": "human_interaction",
  "label": "request_approval",
  "instructions": "Please review the data and approve or reject.",
  "positive_descriptor": "Approve",
  "negative_descriptor": "Reject",
  "timeout_seconds": 7200,
  "sender": "[email protected]",
  "recipients": ["[email protected]"],
  "subject": "Approval Required",
  "body": "An order requires your approval."
}

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

default:"Please review and approve or reject."

Instructions shown in the approval interface.

positive_descriptor

string

default:"Approve"

Label for the approval button.

negative_descriptor

string

default:"Reject"

Label for the rejection button.

Utility Blocks

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

code

string

required

Python code to execute. Store result in result variable.

parameter_keys

array

Parameters 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 [email protected] for access.

Wait

Pause workflow execution for a specified duration.

{
  "block_type": "wait",
  "label": "wait_for_processing",
  "wait_sec": 30
}

wait_sec

integer

default:"0"

Seconds to wait.

Legacy Blocks

Task

Deprecated. For new workflows, use separate navigation and extraction blocks instead.

Legacy block combining navigation and extraction.

{
  "block_type": "task",
  "label": "login_and_extract",
  "url": "{{website_url}}",
  "navigation_goal": "Log in and navigate to settings.",
  "data_extraction_goal": "Extract the account ID.",
  "data_schema": {
    "type": "object",
    "properties": {
      "account_id": {"type": "string"}
    }
  }
}

Task V2

Simplified task block using natural language prompts.

{
  "block_type": "task_v2",
  "label": "complete_form",
  "url": "https://example.com/form",
  "prompt": "Fill out the contact form and submit it.",
  "max_iterations": 10
}

prompt

string

required

Natural language description of the task.

url

string

Starting URL.

max_iterations

integer

default:"10"

Maximum number of iterations.

task_v2 does not use parameter_keys. All workflow parameters and block outputs are automatically available in prompt and url.

Block Outputs

Every block produces an output accessible by other blocks as {{label_output}}. The output shape depends on the block type:

Block Type	Output
Navigation / Action / Login / File Download	`null` on success (effect is browser state change)
Extraction	Matches the `data_schema` you provide
Task	`null` when only `navigation_goal` is set; matches `data_schema` when `data_extraction_goal` is set
Code	Value of the `result` variable
Text Prompt	LLM response, structured according to `json_schema`
File Parser	Parsed file content
For Loop	Array of outputs, one per iteration
HTTP Request	Response body (JSON if applicable)
Upload / File Upload	Storage URL of uploaded file
Print Page	File path of saved PDF
Validation / Conditional / Wait / Send Email	`null` (control-flow blocks)

Error Code Mapping

Several blocks accept an error_code_mapping parameter to map custom error codes to natural language descriptions:

{
  "error_code_mapping": {
    "INVALID_CREDENTIALS": "The page shows an error indicating the username or password is incorrect.",
    "ACCOUNT_LOCKED": "The page indicates the account has been locked.",
    "CAPTCHA_REQUIRED": "A CAPTCHA challenge is displayed."
  }
}

Skyvern evaluates each description against the current page state and surfaces matching errors in the block output.

Finally Block

Designate any block as a “finally” block that always executes when the workflow ends:

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 (cannot have a next_block_label).

Next Steps

Parameters & Context

Learn how to use parameters and pass data between blocks

Running Workflows

Execute workflows and retrieve results

Creating Workflows

Build workflows with SDK, API, or UI

Get Started

Running Tasks

Building Workflows

SDK & API

Credentials & Authentication

Advanced Features

Self-Hosted

Integrations

Debugging & Troubleshooting

​Overview

​Quick Reference

​Common Parameters

​Navigation & Interaction Blocks

​Navigation

​Action

​Login

​Goto URL

​Data Extraction Blocks

​Extraction

​Text Prompt

​Control Flow Blocks

​Validation

​Conditional

​For Loop

​File Operation Blocks

​File Download

​File URL Parser

​Upload to S3

​File Upload

​Print Page

​Integration Blocks

​HTTP Request

​Send Email

​Human Interaction

​Utility Blocks

​Code

​Wait

​Legacy Blocks

​Task

​Task V2

​Block Outputs

​Error Code Mapping

​Finally Block

​Next Steps

Parameters & Context

Running Workflows

Creating Workflows

Build docs developers (and LLMs) love

Overview

Quick Reference

Common Parameters

Navigation & Interaction Blocks

Navigation

Action

Login

Goto URL

Data Extraction Blocks

Extraction

Text Prompt

Control Flow Blocks

Validation

Conditional

For Loop

File Operation Blocks

File Download

File URL Parser

Upload to S3

File Upload

Print Page

Integration Blocks

HTTP Request

Send Email

Human Interaction

Utility Blocks

Code

Wait

Legacy Blocks

Task

Task V2

Block Outputs

Error Code Mapping

Finally Block

Next Steps