Dorod-Sky/docs/getting-started/core-concepts.mdx

---
title: Core Concepts
subtitle: The building blocks of Skyvern automations
slug: getting-started/core-concepts
---

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.

```python
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:**

| Property | Description |
|----------|-------------|
| `prompt` | Natural language description of the goal (required) |
| `url` | Starting URL for the task |
| `data_extraction_schema` | JSON Schema defining expected output structure |
| `max_steps` | Maximum steps allowed (controls cost) |
| `engine` | AI model to use (see [Engines](#engines) below) |
| `browser_session_id` | Run in an existing browser session |
| `webhook_url` | Callback 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      │
└─────────────────────────────────────────────────────────────┘
```

```python
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.

See [Workflow Blocks](/workflows/workflow-blocks-details) for the full block reference.

---

## 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.

### Navigation & Interaction

| Block | Purpose |
|-------|---------|
| **Navigation** | AI-guided navigation toward a goal—Skyvern figures out the clicks and inputs |
| **Action** | Perform a single specific action (click, type, select, upload) |
| **Go to URL** | Navigate directly to a specific URL |
| **Login** | Authenticate using stored credentials |
| **Wait** | Pause execution for a specified duration |
| **Human Interaction** | Pause for manual intervention (CAPTCHA, approval, etc.) |

### Data & Files

| Block | Purpose |
|-------|---------|
| **Extract** | Pull structured data from a page into JSON |
| **File Download** | Download files from websites |
| **File Upload** | Upload files to form fields |
| **File Parser** | Process PDFs, CSVs, and Excel files |
| **PDF Parser** | Specialized PDF text extraction |

### Logic & Control Flow

| Block | Purpose |
|-------|---------|
| **Conditional** | Branch workflow based on conditions (if/else) |
| **For Loop** | Repeat a sequence of blocks over a list |
| **Validation** | Assert conditions; halt workflow on failure |
| **Code** | Execute custom Python/Playwright scripts |

### Communication & Integration

| Block | Purpose |
|-------|---------|
| **HTTP Request** | Make API calls to external services |
| **Text Prompt** | Text-only LLM prompt (no browser interaction) |
| **Send Email** | Send email messages |

For detailed block configuration, see [Workflow Blocks](/workflows/workflow-blocks-details).

---

## 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
```

```python
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:**

| Field | Description |
|-------|-------------|
| `run_id` | Unique identifier |
| `status` | Current lifecycle state |
| `output` | Extracted data (matches your schema) |
| `recording_url` | Video of the execution |
| `screenshot_urls` | Screenshots captured during execution |
| `downloaded_files` | Files retrieved (with URLs and checksums) |
| `failure_reason` | Error details if failed |
| `step_count` | Number of steps taken |

<Warning>
**Billing:** You're billed per step. A step is one AI decision + action cycle. Use `max_steps` to cap costs during development.
</Warning>

---

## 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

See [Credentials](/credentials/introduction) for setup instructions.

---

## 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.

```python
# 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.

```python
# Create a profile from a completed run
profile = await skyvern.browser_profiles.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.

See [Browser Sessions](/browser-sessions/introduction) for details.

---

## Artifacts

Every run generates artifacts for observability, debugging, and audit trails.

```python
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": "..."}]
```

| Artifact | Description |
|----------|-------------|
| **Recordings** | End-to-end video of the entire run |
| **Screenshots** | Captured after each action |
| **Downloaded files** | Files retrieved during execution |
| **Logs** | JSON-structured logs at step, task, and workflow levels |
| **HAR files** | HTTP 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:

| Engine | Description |
|--------|-------------|
| `skyvern-2.0` | Latest Skyvern model (default, recommended) |
| `skyvern-1.0` | Previous Skyvern model |
| `openai-cua` | OpenAI Computer Use Agent |
| `anthropic-cua` | Anthropic Computer Use Agent |
| `ui-tars` | UI-TARS model |

Specify the engine when running a task:

```python
result = await skyvern.run_task(
    prompt="Extract pricing data",
    url="https://example.com",
    engine="skyvern-2.0"
)
```

---

## Quick Reference

| I want to... | Use |
|--------------|-----|
| Run a one-off automation | [Task](#tasks) |
| Build a reusable multi-step process | [Workflow](#workflows) |
| Keep a browser open between tasks | [Browser Session](#browser-sessions) |
| Skip login on repeated runs | [Browser Profile](#browser-profiles) |
| Store secrets securely | [Credentials](#credentials) |
| Debug a failed run | [Artifacts](#artifacts) |

---

## Next Steps

<CardGroup cols={2}>
  <Card
    title="API Quickstart"
    icon="rocket"
    href="/getting-started/quickstart"
  >
    Run your first task in 5 minutes
  </Card>
  <Card
    title="Build Workflows"
    icon="diagram-project"
    href="/workflows/run-workflows"
  >
    Create multi-step automations
  </Card>
  <Card
    title="Workflow Blocks"
    icon="cube"
    href="/workflows/workflow-blocks-details"
  >
    Full reference for all block types
  </Card>
  <Card
    title="API Reference"
    icon="code"
    href="/api-reference"
  >
    Complete API documentation
  </Card>
</CardGroup>