Skip to main content
Skyvern has eight core concepts. Master these and you can build any browser automation.

​
Tasks

A Task is a single automation job—think of it as asking Skyvern to do one thing. You provide a prompt describing the goal, and Skyvern navigates the browser to complete it. 
from skyvern import Skyvern

skyvern = Skyvern(api_key="YOUR_API_KEY")

result = await skyvern.run_task(
    prompt="Find the top 3 posts on the front page",
    url="https://news.ycombinator.com",
    data_extraction_schema={
        "type": "object",
        "properties": {
            "posts": {
                "type": "array",
                "items": {"type": "string"}
            }
        }
    }
)

print(result.output)  # {"posts": ["Post 1", "Post 2", "Post 3"]}

​
Key Properties

PropertyDescription
promptNatural language description of the goal (required)
urlStarting URL for the task
data_extraction_schemaJSON Schema defining expected output structure
max_stepsMaximum steps allowed (controls cost)
engineAI model to use (see Engines below)
browser_session_idRun in an existing browser session
webhook_urlCallback URL for async completion
Use Tasks for: one-off automations, quick data extraction, prototyping before building a workflow. When you need reusable, multi-step automations, use Workflows instead.

​
Workflows

A Workflow is a reusable template composed of blocks. Unlike tasks, workflows can be versioned, shared across your team, and executed repeatedly with different parameters. 
┌─────────────────────────────────────────────────────────────┐
│                        WORKFLOW                             │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐  │
│  │ Navigate │ → │  Login   │ → │ Extract  │ → │ Download │  │
│  │  Block   │   │  Block   │   │  Block   │   │  Block   │  │
│  └──────────┘   └──────────┘   └──────────┘   └──────────┘  │
│                                                             │
│  Parameters: {{search_query}}, {{max_price}}                │
│  Each block can reference outputs from previous blocks      │
└─────────────────────────────────────────────────────────────┘

result = await skyvern.run_workflow(
    workflow_id="wpid_abc123",
    parameters={
        "search_query": "wireless headphones",
        "max_price": 100
    }
)

print(result.output)
Workflows support Jinja templating:
  • Reference parameters: {{search_query}}
  • Reference previous block outputs: {{extract_block.product_name}}
Use Workflows for: repeatable automations, multi-step processes, team-shared templates, complex logic with loops or conditionals.

​
Blocks

Blocks are the building units of workflows. Each block performs one specific task, and blocks execute sequentially—each can reference outputs from previous blocks.
BlockPurpose
NavigationAI-guided navigation toward a goal—Skyvern figures out the clicks and inputs
ActionPerform a single specific action (click, type, select, upload)
Go to URLNavigate directly to a specific URL
LoginAuthenticate using stored credentials
WaitPause execution for a specified duration
Human InteractionPause for manual intervention (CAPTCHA, approval, etc.)

​
Data & Files

BlockPurpose
ExtractPull structured data from a page into JSON
File DownloadDownload files from websites
File UploadUpload files to form fields
File ParserProcess PDFs, CSVs, and Excel files
PDF ParserSpecialized PDF text extraction

​
Logic & Control Flow

BlockPurpose
ConditionalBranch workflow based on conditions (if/else)
For LoopRepeat a sequence of blocks over a list
ValidationAssert conditions; halt workflow on failure
CodeExecute custom Python/Playwright scripts

​
Communication & Integration

BlockPurpose
HTTP RequestMake API calls to external services
Text PromptText-only LLM prompt (no browser interaction)
Send EmailSend email messages

​
Runs

Every time you execute a task or workflow, Skyvern creates a Run to track progress and store outputs. 
                    ┌→ completed
                    │
                    ├→ failed
                    │
created → queued → running ─┼→ timed_out
                    │
                    ├→ terminated
                    │
                    └→ canceled

result = await skyvern.run_task(
    prompt="Extract the main heading",
    url="https://example.com"
)

print(result.run_id)   # "tsk_abc123"
print(result.status)   # "completed"
print(result.output)   # {"heading": "Welcome"}

​
Run Identifiers

  • Task runs: tsk_* prefix
  • Workflow runs: wr_* prefix

​
Run Response Fields

FieldDescription
run_idUnique identifier
statusCurrent lifecycle state
outputExtracted data (matches your schema)
recording_urlVideo of the execution
screenshot_urlsScreenshots captured during execution
downloaded_filesFiles retrieved (with URLs and checksums)
failure_reasonError details if failed
step_countNumber of steps taken
Billing: You’re billed per step. A step is one AI decision + action cycle. Use max_steps to cap costs during development.

​
Credentials

Credentials provide secure storage for authentication data. Skyvern encrypts credentials at rest and in transit, and injects them directly into the browser—credentials are never sent to or seen by the LLM. 
┌─────────────────────────────────────────────────────────────┐
│                    SECURITY MODEL                           │
│                                                             │
│  You store credentials      Skyvern encrypts & stores       │
│         │                            │                      │
│         ▼                            ▼                      │
│  ┌─────────────┐             ┌─────────────────┐            │
│  │ Skyvern UI  │             │ Encrypted Vault │            │
│  │ or API      │ ─────────── │ (or Bitwarden,  │            │
│  └─────────────┘             │  1Password)     │            │
│                              └────────┬────────┘            │
│                                       │                     │
│                                       ▼                     │
│                              ┌─────────────────┐            │
│                              │ Login Block     │            │
│                              │ injects into    │            │
│                              │ browser fields  │            │
│                              └─────────────────┘            │
│                                       │                     │
│                    LLM sees: "login happened"               │
│                    LLM never sees: actual credentials       │
└─────────────────────────────────────────────────────────────┘

​
Supported Credential Types

  • Usernames and passwords
  • TOTP codes (authenticator apps)
  • Credit cards

​
Credential Sources

  • Skyvern — Native encrypted storage
  • Bitwarden — Sync from your Bitwarden vault
  • 1Password — Sync from your 1Password vault
  • Azure Key Vault — Enterprise secret management

​
Browser Sessions & Profiles

Skyvern offers two ways to manage browser state across runs: 
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   BROWSER SESSION                  BROWSER PROFILE          │
│   (live, temporary)                (saved, reusable)        │
│                                                             │
│   ┌─────────────┐                 ┌─────────────┐           │
│   │  Active     │   ──save──▶     │  Snapshot   │           │
│   │  Browser    │                 │  of state   │           │
│   │  Instance   │   ◀──restore──  │  (cookies,  │           │
│   └─────────────┘                 │  storage)   │           │
│                                   └─────────────┘           │
│   • Expires after timeout         • Persists indefinitely  │
│   • For real-time chaining        • For skipping login     │
│   • Max 24 hours                  • Shared across team     │
│                                                             │
└─────────────────────────────────────────────────────────────┘

​
Browser Sessions

A live browser instance that maintains state across multiple tasks. Use sessions when you need to chain tasks in real-time or allow human intervention. 
# Create a session (default: 60 minutes, max: 24 hours)
session = await skyvern.create_browser_session(timeout=120)

# Run tasks in the same session
await skyvern.run_task(
    prompt="Log in with the test account",
    url="https://example.com/login",
    browser_session_id=session.browser_session_id
)

# Second task reuses the authenticated state
await skyvern.run_task(
    prompt="Extract the account balance",
    url="https://example.com/dashboard",
    browser_session_id=session.browser_session_id
)

# Clean up
await skyvern.close_browser_session(
    browser_session_id=session.browser_session_id
)
Session limits: 5 to 1,440 minutes (24 hours max). Default: 60 minutes.

​
Browser Profiles

A saved snapshot of browser state. Unlike sessions, profiles persist indefinitely and can be reused across days or weeks—perfect for skipping login on repeated runs. 
# Create a profile from a completed run
profile = await skyvern.create_browser_profile(
    name="my-authenticated-profile",
    workflow_run_id=run.run_id
)

# Future runs restore the authenticated state
await skyvern.run_workflow(
    workflow_id="wpid_extract_data",
    browser_profile_id=profile.browser_profile_id
)
What’s saved: Cookies, authentication tokens, local storage, session storage.

​
Artifacts

Every run generates artifacts for observability, debugging, and audit trails. 
result = await skyvern.run_task(
    prompt="Download the quarterly report",
    url="https://example.com"
)

print(result.recording_url)      # Full video of execution
print(result.screenshot_urls)    # List of screenshot URLs
print(result.downloaded_files)   # [{"url": "...", "checksum": "..."}]
ArtifactDescription
RecordingsEnd-to-end video of the entire run
ScreenshotsCaptured after each action
Downloaded filesFiles retrieved during execution
LogsJSON-structured logs at step, task, and workflow levels
HAR filesHTTP Archive data for network debugging
In the Skyvern UI, go to Runs → click a run → view the Actions and Recording tabs.

​
Engines

Skyvern supports multiple AI engines for task execution:
EngineDescription
skyvern-2.0Latest Skyvern model (default, recommended)
skyvern-1.0Previous Skyvern model
openai-cuaOpenAI Computer Use Agent
anthropic-cuaAnthropic Computer Use Agent
ui-tarsUI-TARS model
Specify the engine when running a task: 
from skyvern.schemas.runs import RunEngine

result = await skyvern.run_task(
    prompt="Extract pricing data",
    url="https://example.com",
    engine=RunEngine.skyvern_v2
)

​
Quick Reference

I want to…Use
Run a one-off automationTask
Build a reusable multi-step processWorkflow
Keep a browser open between tasksBrowser Session
Skip login on repeated runsBrowser Profile
Store secrets securelyCredentials
Debug a failed runArtifacts

​
Next Steps

API Quickstart

Run your first task in 5 minutes

Build Workflows

Create multi-step automations

Extract Structured Data

Define schemas for consistent JSON output

Handle Authentication

Store credentials securely with password managers

Build docs developers (and LLMs) love

Get started for freeTalk to us