同步完整源码 - 2026-05-24

This commit is contained in:
xiaoxue
2026-05-24 23:27:44 +08:00
commit 4608c06bb3
366 changed files with 53434 additions and 0 deletions
File diff suppressed because it is too large Load Diff
+613
View File
@@ -0,0 +1,613 @@
---
title: "Changelog"
description: "New features, improvements, and fixes in Skyvern"
mode: custom
keywords:
- changelog
- release notes
- new features
- improvements
- bug fixes
---
<div className="cl-page">
<div className="cl-sidebar">
<p className="cl-sidebar-title">TIMELINE</p>
<a href="#week-may-18-2026" className="cl-sidebar-link">Week of May 18, 2026</a>
<a href="#week-may-11-2026" className="cl-sidebar-link">Week of May 11, 2026</a>
<a href="#week-may-4-2026" className="cl-sidebar-link">Week of May 4, 2026</a>
<a href="#week-apr-27-2026" className="cl-sidebar-link">Week of Apr 27, 2026</a>
<a href="#v1-0-24" className="cl-sidebar-link">v1.0.24 — Apr 21, 2026</a>
<a href="#v1-0-23" className="cl-sidebar-link">v1.0.23 — Apr 14, 2026</a>
<a href="#v1-0-22" className="cl-sidebar-link">v1.0.22 — Feb 26, 2026</a>
<a href="#v1-0-21" className="cl-sidebar-link">v1.0.21 — Feb 24, 2026</a>
<a href="#v1-0-20" className="cl-sidebar-link">v1.0.20 — Feb 21, 2026</a>
<a href="#v1-0-19" className="cl-sidebar-link">v1.0.19 — Feb 20, 2026</a>
<a href="#v1-0-18" className="cl-sidebar-link">v1.0.18 — Feb 19, 2026</a>
<a href="#v1-0-17" className="cl-sidebar-link">v1.0.17 — Feb 19, 2026</a>
<a href="#v1-0-16" className="cl-sidebar-link">v1.0.16 — Feb 19, 2026</a>
<a href="#v1-0-15" className="cl-sidebar-link">v1.0.15 — Feb 17, 2026</a>
<a href="#v1-0-14" className="cl-sidebar-link">v1.0.14 — Feb 17, 2026</a>
<a href="#v1-0-13" className="cl-sidebar-link">v1.0.13 — Feb 10, 2026</a>
<a href="#v1-0-12" className="cl-sidebar-link">v1.0.12 — Feb 3, 2026</a>
<a href="#v1-0-11" className="cl-sidebar-link">v1.0.11 — Jan 29, 2026</a>
<a href="#v1-0-10" className="cl-sidebar-link">v1.0.10 — Jan 22, 2026</a>
<a href="#v1-0-9" className="cl-sidebar-link">v1.0.9 — Jan 20, 2026</a>
<a href="#v1-0-8" className="cl-sidebar-link">v1.0.8 — Jan 9, 2026</a>
</div>
<div className="cl-content">
<h1 className="cl-title">Changelog</h1>
<p className="cl-subtitle">New features, improvements, and fixes in Skyvern</p>
<a id="week-may-18-2026"></a>
<Update label="Week of May 18, 2026" description="Guided browser profile setup, archived artifact status, webhook retry, download fixes">
## New features
- **Guided Browser Profile Setup** — A new step-by-step flow walks you through creating a saved browser profile, making it easier to set up persistent login sessions. ([#6043](https://github.com/Skyvern-AI/skyvern/pull/6043))
- **MCP Setup in Cloud Settings** — Added a dedicated MCP setup section to cloud account settings for easier MCP client configuration.
## Improvements
- **Archived Artifact Status** — Workflow runs now show when their artifacts have been archived, with a clear status indicator in the UI. ([#6075](https://github.com/Skyvern-AI/skyvern/pull/6075))
- **Automatic Webhook Retry on Infrastructure Failures** — Workflow webhooks are now retried automatically after transient infrastructure failures, reducing missed notifications. ([#6062](https://github.com/Skyvern-AI/skyvern/pull/6062))
- **Faster Script-Mode Runs** — Speculative extract-action steps are skipped in script-mode workflows, cutting unnecessary LLM calls. ([#6057](https://github.com/Skyvern-AI/skyvern/pull/6057))
- **LLM Router Length-Truncation Fallback** — When a model response is cut off by a length limit, the router now automatically retries with a fallback model instead of returning a partial response. ([#6079](https://github.com/Skyvern-AI/skyvern/pull/6079))
## Bug fixes
- Fixed popup pages opened during a run not being included in session recordings. ([#6078](https://github.com/Skyvern-AI/skyvern/pull/6078))
- Fixed XHR-triggered file downloads not being captured when using download action blocks. ([#6054](https://github.com/Skyvern-AI/skyvern/pull/6054))
- Fixed transient download-error popups incorrectly causing run failures. ([#6080](https://github.com/Skyvern-AI/skyvern/pull/6080))
- Fixed child tasks not being terminated and workflow runs getting resurrected after a cleanup cron timeout. ([#6047](https://github.com/Skyvern-AI/skyvern/pull/6047))
- Fixed copilot feasibility check stalling when given diagnostic input for an existing workflow. ([#6061](https://github.com/Skyvern-AI/skyvern/pull/6061))
- Fixed reCAPTCHA v2 invisible variant being misidentified as v3, causing solve failures.
</Update>
<a id="week-may-11-2026"></a>
<Update label="Week of May 11, 2026" description="Analytics dashboard, browser profile pages, scheduled run badges, faster API">
## New features
- **Analytics Dashboard** — A new /analytics page provides a breakdown of workflow run activity and performance over time. ([#5980](https://github.com/Skyvern-AI/skyvern/pull/5980))
- **Browser Profile Management Page** — A dedicated browser profiles page lets you view, search, and rename your saved browser profiles. ([#5990](https://github.com/Skyvern-AI/skyvern/pull/5990))
- **Smarter Element Targeting** — The agent now uses deterministic HTML element-tree compression, improving selector reliability on complex pages. ([#5970](https://github.com/Skyvern-AI/skyvern/pull/5970))
- **Block-Scoped Parameter Prompts in Debugger** — The workflow debugger now prompts for parameters scoped to the specific block being tested, making per-block runs easier to set up.
## Improvements
- **Scheduled Trigger Badge on Runs Page** — The global Runs page now shows a badge on runs triggered by a schedule, making scheduled runs easy to identify. ([#5948](https://github.com/Skyvern-AI/skyvern/pull/5948))
- **Signed Artifact Content URLs** — Artifact content URLs are now always signed with configurable expiry for secure access control. ([#5940](https://github.com/Skyvern-AI/skyvern/pull/5940))
- **Faster Workflow Run API** — The GET workflow run endpoint has been significantly optimized for speed. ([#5993](https://github.com/Skyvern-AI/skyvern/pull/5993))
- **Copilot Diff View Detects Nested Changes** — The Copilot diff panel now correctly highlights changes inside nested conditional and loop blocks. ([#5945](https://github.com/Skyvern-AI/skyvern/pull/5945))
- **Output Parameter Size Protection** — Workflow output parameter values are now capped to prevent oversized JSON payloads from causing downstream failures. ([#5974](https://github.com/Skyvern-AI/skyvern/pull/5974))
## Bug fixes
- Fixed scheduled workflow runs not appearing on the global Runs page. ([#5949](https://github.com/Skyvern-AI/skyvern/pull/5949))
- Fixed webhook delivery silently failing on transient 403, 5xx, or network errors. ([#5952](https://github.com/Skyvern-AI/skyvern/pull/5952))
- Fixed artifact downloads failing for clients that send HTTP Range request headers. ([#5982](https://github.com/Skyvern-AI/skyvern/pull/5982))
- Fixed FileParserBlock failures not appearing in workflow run outputs. ([#5964](https://github.com/Skyvern-AI/skyvern/pull/5964))
</Update>
<a id="week-may-4-2026"></a>
<Update label="Week of May 4, 2026" description="While Loop block, multiple schedules per workflow, Google Sheets connector, browser session runs tab">
## New features
- **While Loop Block** — A new workflow block type that repeats a sub-workflow until a condition is met, enabling dynamic iteration without a fixed loop count. ([#5809](https://github.com/Skyvern-AI/skyvern/pull/5809))
- **Multiple Schedules per Workflow** — Workflows can now have multiple independent schedules (e.g., run at 9am on weekdays and noon on weekends). ([#5799](https://github.com/Skyvern-AI/skyvern/pull/5799))
- **Google Sheets Connector (Open Source)** — The Google Sheets connector authentication flow is now part of the open source package. ([#5815](https://github.com/Skyvern-AI/skyvern/pull/5815))
- **Runs Tab on Browser Session Page** — The browser session detail page now includes a Runs tab listing all workflow runs associated with that session. ([#5830](https://github.com/Skyvern-AI/skyvern/pull/5830))
- **Per-Workflow Total Step Cap** — A new workflow-run step cap lets you limit the maximum number of agent steps across all blocks in a single run. ([#5834](https://github.com/Skyvern-AI/skyvern/pull/5834))
## Improvements
- **TOTP Scoped to Active Credential** — Credential-derived TOTP values are now scoped to the active credential, preventing stale tokens from being used mid-run. ([#5805](https://github.com/Skyvern-AI/skyvern/pull/5805))
- **Browser Dialogs Surfaced to Agent** — JavaScript dialogs (alerts, confirms, prompts) that the browser blocks are now surfaced to the agent so it can adapt its next action. ([#5810](https://github.com/Skyvern-AI/skyvern/pull/5810))
## Bug fixes
- Fixed the workflow-deleted banner not appearing on the run detail page when the parent workflow has been deleted. ([#5800](https://github.com/Skyvern-AI/skyvern/pull/5800))
</Update>
<a id="week-apr-27-2026"></a>
<Update label="Week of April 27, 2026" description="MCP CLI for schedules and config, copilot hard-cancel, cursor in recordings, artifact URL improvements">
## New features
- **Workflow Schedule Management via MCP** — Manage workflow schedules from MCP clients (e.g., Claude Code) using the new `skyvern schedule` CLI commands. ([#5713](https://github.com/Skyvern-AI/skyvern/pull/5713))
- **Org Settings via MCP** — Configure organization settings from MCP clients using the new `skyvern config` CLI tool. ([#5694](https://github.com/Skyvern-AI/skyvern/pull/5694))
- **MCP OAuth Org Selection** — Multi-org users can now choose which organization to connect to during MCP OAuth authentication. ([#5699](https://github.com/Skyvern-AI/skyvern/pull/5699))
- **Platform-Level JS Dialog Handler** — The agent now handles JavaScript dialogs at the browser level using LLM-guided decision logic, improving reliability on dialog-heavy pages. ([#5679](https://github.com/Skyvern-AI/skyvern/pull/5679))
- **Print-to-PDF in Downloaded Files** — Workflow blocks that trigger a browser print-to-PDF now expose the resulting file in the block's downloaded files list. ([#5784](https://github.com/Skyvern-AI/skyvern/pull/5784))
## Improvements
- **Cursor Visualization in Run Recordings** — Playwright recordings now overlay a visible cursor, making it easy to follow the agent's actions when reviewing a recording. ([#5683](https://github.com/Skyvern-AI/skyvern/pull/5683))
- **Short Signed Recording URLs** — Browser session recording links are now compact signed URLs instead of full S3 paths. ([#5686](https://github.com/Skyvern-AI/skyvern/pull/5686))
- **Configurable Artifact URL Expiry** — A settings field lets you control how long artifact content URLs stay valid before expiring. ([#5690](https://github.com/Skyvern-AI/skyvern/pull/5690))
- **Copilot Hard-Cancel** — A hard-cancel button immediately stops an in-progress copilot run without waiting for the current step to finish. ([#5726](https://github.com/Skyvern-AI/skyvern/pull/5726))
- **Copilot Reuses Live Debug Browser Session** — When testing a workflow from the debugger, the copilot now reuses the open browser session instead of starting a new one. ([#5709](https://github.com/Skyvern-AI/skyvern/pull/5709))
- **Copilot Surfaces WIP Workflow on Timeout** — If the copilot times out or a test fails, it now offers the in-progress workflow so you can review and continue. ([#5755](https://github.com/Skyvern-AI/skyvern/pull/5755))
- **Pre-Filled Debugger Run Dialog** — The Run dialog in the workflow debugger now pre-fills with values from your last run. ([#5724](https://github.com/Skyvern-AI/skyvern/pull/5724))
- **Copilot Atomic Workflow Accept** — Accepting a copilot workflow proposal now applies all block changes atomically, preventing partial updates. ([#5695](https://github.com/Skyvern-AI/skyvern/pull/5695))
- **Loop Block Failure-Handling Clarity** — The loop block UI has clearer controls and labels for configuring how failures inside the loop are handled. ([#5731](https://github.com/Skyvern-AI/skyvern/pull/5731))
## Bug fixes
- Fixed the in-progress workflow not being preserved when closing the copilot mid-run. ([#5787](https://github.com/Skyvern-AI/skyvern/pull/5787))
</Update>
<a id="v1-0-24"></a>
<Update label="v1.0.24 — April 21, 2026" description="Copilot reliability, run recordings, 2FA improvements, and more">
## Improvements
- **Copilot Live Status Narration** — The workflow editor copilot now displays a short live status line while it works, so you can see what the agent is doing instead of waiting in silence. ([#5567](https://github.com/Skyvern-AI/skyvern/pull/5567))
- **Renamed Browser Profile Reset Action** — The API endpoint for clearing a persisted browser session has been renamed from `/browser_session/refresh` to `/browser_session/reset_profile` for clarity. The old path remains available as a deprecated alias. ([#5572](https://github.com/Skyvern-AI/skyvern/pull/5572))
- **Fewer Screenshots for API Runs** — Screenshot capture frequency has been reduced for API-triggered runs, lowering storage overhead on long-running automations without affecting interactive sessions. ([#5565](https://github.com/Skyvern-AI/skyvern/pull/5565))
## Bug fixes
- Fixed the workflow copilot incorrectly proposing a workflow it had just failed to build. The copilot now only surfaces an Accept/Reject panel when the last test actually passed. ([#5574](https://github.com/Skyvern-AI/skyvern/pull/5574))
- Fixed 2FA entry failing on pages with custom overlay input components where the real input field is hidden. The agent now types digit keys directly when no interactable input exists. ([#5568](https://github.com/Skyvern-AI/skyvern/pull/5568))
</Update>
<a id="v1-0-23"></a>
<Update label="v1.0.23 — April 14, 2026" description="Saudi Arabia proxy, workflow error mapping, smarter caching, MCP OAuth, AI output summaries, and reliability fixes">
## New features
- **Saudi Arabia Proxy Location** — Added `RESIDENTIAL_SA` as a proxy geolocation option for automations targeting Saudi Arabian websites.
- **Workflow-Level Error Code Mapping** — Workflows now support an `error_code_mapping` field that all blocks inherit automatically. Block-level mappings still take precedence, giving you a single place to define default error handling without repeating it on every block. ([#5506](https://github.com/Skyvern-AI/skyvern/pull/5506))
- **AI Summarize for Workflow Run Outputs** — A magic-wand "Summarize with AI" button now appears next to block and workflow run output sections, generating a plain-language summary of raw JSON output on demand. ([#5556](https://github.com/Skyvern-AI/skyvern/pull/5556))
- **Reset Browser Profile API** — A new `POST /workflows/{workflow_permanent_id}/browser_session/reset_profile` endpoint clears a corrupted persisted browser session so the next run starts from a fresh browser state. ([#5544](https://github.com/Skyvern-AI/skyvern/pull/5544))
- **MCP OAuth for Remote Clients** — MCP clients (e.g. Claude Code, Codex) can now complete browser-based OAuth to authenticate with Skyvern without getting stuck in redirect chains. ([#5558](https://github.com/Skyvern-AI/skyvern/pull/5558))
- **OpenClaw MCP Setup** — `skyvern setup openclaw` and `skyvern mcp switch` now support OpenClaw as an MCP client target for both remote and local stdio configurations. ([#5536](https://github.com/Skyvern-AI/skyvern/pull/5536))
## Improvements
- **Smarter Extraction Cache Keys** — The extraction cache now normalizes session-volatile tokens (random UUIDs, CSRF values, nonce query params, timestamps) before hashing cache keys. Semantically identical page visits now share cached extraction results, improving cache hit rates across workflow re-runs. ([#5504](https://github.com/Skyvern-AI/skyvern/pull/5504))
- **Reduced Rate-Limit Errors on Extraction Prompts** — Extraction prompts are now capped in size before being sent to the LLM. Oversized `previous_extracted_information`, `extracted_information_schema`, and element trees are truncated rather than sent whole, significantly reducing `429 RESOURCE_EXHAUSTED` errors on high-volume workflows. ([#5502](https://github.com/Skyvern-AI/skyvern/pull/5502))
- **Cross-Run Extraction Cache** — Extraction results are now cached in Redis across workflow runs, scoped to the workflow. Recurring scheduled workflows skip redundant LLM calls when the page content hasn't changed. ([#5562](https://github.com/Skyvern-AI/skyvern/pull/5562))
- **Copilot Survives Tab Switches and Reconnects** — The workflow copilot agent now runs to completion even if the browser tab is closed or the connection drops mid-request, and the AI reply is persisted so it appears when you reconnect. ([#5560](https://github.com/Skyvern-AI/skyvern/pull/5560))
- **Copilot Fails Fast on Unresolvable URLs** — The workflow copilot now immediately surfaces the real error (e.g. DNS resolution failure) and stops retrying when a URL cannot be reached, rather than reporting success. ([#5563](https://github.com/Skyvern-AI/skyvern/pull/5563))
## Bug fixes
- Fixed CSV parsing failing on files whose first header row exceeded ~1 MB, causing valid wide-format CSVs to be rejected with "Could not determine delimiter". ([#5510](https://github.com/Skyvern-AI/skyvern/pull/5510))
- Fixed a browser automation crash on sites with cross-origin stylesheets (e.g. MUI-based apps). CSS hover styles are now parsed entirely in memory without modifying the DOM, preventing React reconciliation errors that caused the agent to loop until max steps. ([#5508](https://github.com/Skyvern-AI/skyvern/pull/5508))
- Fixed context-window overflow failures being misdiagnosed. Steps that fail due to oversized input are now correctly counted and short-circuit to a clear `LLM_ERROR` failure reason instead of triggering a redundant LLM-based failure analysis. ([#5507](https://github.com/Skyvern-AI/skyvern/pull/5507))
- Fixed workflow file-download blocks losing their configured `download_suffix` at task finalization, causing downloaded files to be persisted without the expected filename suffix. ([#5499](https://github.com/Skyvern-AI/skyvern/pull/5499))
- Fixed cached scripts for non-ATS workflows incorrectly generating `fill_form()` calls, which defeated the performance benefits of caching by delegating back to AI at runtime. ([#5497](https://github.com/Skyvern-AI/skyvern/pull/5497))
- Fixed the pagination navigator on the Workflow Past Runs and Run History pages being right-aligned instead of centered.
- Fixed run recordings missing an end timestamp and broken scrubbing. Recordings are now finalized with a stream-copy remux so players correctly show duration and support seeking. ([#5551](https://github.com/Skyvern-AI/skyvern/pull/5551))
- Fixed tag input fields (e.g. skill set fields on job application forms) not selecting values from the dropdown. These fields are now correctly treated as auto-completion inputs. ([#5557](https://github.com/Skyvern-AI/skyvern/pull/5557))
- Fixed per-step video sync spawning a redundant ffmpeg process on every step, causing CPU spikes and log noise. ([#5559](https://github.com/Skyvern-AI/skyvern/pull/5559))
- Fixed workflow parameter edit and delete buttons being hidden when a parameter name was too long.
- Fixed webhook delivery failing silently when a stored webhook URL had a leading or trailing space. ([#5550](https://github.com/Skyvern-AI/skyvern/pull/5550))
</Update>
<a id="v1-0-22"></a>
<Update label="v1.0.22 — February 26, 2026" description="Adaptive caching, Workflow Trigger block, CLI signup, and more">
## New features
- **Adaptive Caching (Script Generation)** — Skyvern can now learn from repeated workflow runs and generate cached scripts that speed up future executions. When a block runs successfully, Skyvern records a reusable script and replays it on subsequent runs, falling back to the AI agent only if the script fails. ([#4908](https://github.com/Skyvern-AI/skyvern/pull/4908), [#4916](https://github.com/Skyvern-AI/skyvern/pull/4916), [#4917](https://github.com/Skyvern-AI/skyvern/pull/4917), [#4920](https://github.com/Skyvern-AI/skyvern/pull/4920), [#4922](https://github.com/Skyvern-AI/skyvern/pull/4922), [#4931](https://github.com/Skyvern-AI/skyvern/pull/4931))
- **Workflow Trigger Block** — A new block type that lets one workflow trigger another from within the workflow editor. Chain workflows together as building blocks for complex automations. ([#4885](https://github.com/Skyvern-AI/skyvern/pull/4885))
- **Browser-based CLI Signup** — New users can sign up for Skyvern Cloud directly from the CLI. Running `skyvern signup` opens a browser flow that creates your account and stores your API key locally. ([#4925](https://github.com/Skyvern-AI/skyvern/pull/4925))
- **Interactive ngrok Tunnel** — `skyvern browser serve` can now create an ngrok tunnel automatically, making it easy to expose your local browser to Skyvern Cloud without manual network configuration. ([#4924](https://github.com/Skyvern-AI/skyvern/pull/4924))
- **South Korea Proxy Location** — Added `RESIDENTIAL_KR` as a proxy geolocation option for automations targeting South Korean websites. ([#4918](https://github.com/Skyvern-AI/skyvern/pull/4918))
- **Downloaded Files Tab** — Browser session detail pages now include a Downloaded Files tab for viewing and accessing files captured during a session. ([#4911](https://github.com/Skyvern-AI/skyvern/pull/4911))
- **CDP Proxy Authentication** — Remote browser connections now support authenticated proxies via the CDP `Fetch.authRequired` protocol. ([#4936](https://github.com/Skyvern-AI/skyvern/pull/4936))
- **Remote Browser Download Interception** — File downloads triggered by XHR requests and other non-navigation events are now captured when using remote CDP browser connections. ([#4906](https://github.com/Skyvern-AI/skyvern/pull/4906), [#4921](https://github.com/Skyvern-AI/skyvern/pull/4921), [#4934](https://github.com/Skyvern-AI/skyvern/pull/4934))
## Improvements
- **Renamed "Login-Free" to "Saved Profile"** — Clearer terminology throughout the UI. Browser session checkbox wording has also been improved. ([#4914](https://github.com/Skyvern-AI/skyvern/pull/4914))
- **TOTP Verification Improvements** — Better timer handling, expired code retry, 2FA banner suppression, and more reliable goal-text extraction during TOTP flows. ([#4860](https://github.com/Skyvern-AI/skyvern/pull/4860))
- **TOTP Webhook includes `workflow_permanent_id`** — Easier to identify which workflow is requesting a 2FA code. ([#4871](https://github.com/Skyvern-AI/skyvern/pull/4871))
- **Consolidated Gemini 3 Pro Model Key** — `VERTEX_GEMINI_3_PRO` now auto-resolves to the latest version, so you no longer need to update config when Google releases point versions. ([#4926](https://github.com/Skyvern-AI/skyvern/pull/4926))
- **Browser Rotation for Remote Connections** — Remote browser environments now support context rotation, improving reliability for long-running automations. ([#4929](https://github.com/Skyvern-AI/skyvern/pull/4929))
## Bug fixes
- Fixed a race condition where final task status could be overwritten by a late-arriving non-final status. ([#4928](https://github.com/Skyvern-AI/skyvern/pull/4928))
- Conditional blocks no longer crash when evaluating empty or null parameters. ([#4907](https://github.com/Skyvern-AI/skyvern/pull/4907))
- Browser sessions using `FORCE_BROWSER_SESSION` no longer time out prematurely. ([#4903](https://github.com/Skyvern-AI/skyvern/pull/4903))
- SVG-based captcha text is now correctly extracted during DOM scraping. ([#4880](https://github.com/Skyvern-AI/skyvern/pull/4880))
- MCP remote tool handlers now route to the correct API environment. ([#4869](https://github.com/Skyvern-AI/skyvern/pull/4869))
- MCP remote auth token comparison no longer fails on encrypted tokens. ([#4863](https://github.com/Skyvern-AI/skyvern/pull/4863))
- `skyvern quickstart` now handles local PostgreSQL without a pre-existing `skyvern` role. ([#4878](https://github.com/Skyvern-AI/skyvern/pull/4878))
- WebSocket URLs through ngrok tunnels now rewrite correctly for live browser streaming. ([#4927](https://github.com/Skyvern-AI/skyvern/pull/4927))
</Update>
<a id="v1-0-21"></a>
<Update label="v1.0.21 — February 24, 2026" description="Reserved parameters, data_schema for loops, new LLM models">
## New features
- **`current_date` Reserved Parameter** — Workflows now have a built-in `current_date` parameter that resolves to today's date automatically. ([#4854](https://github.com/Skyvern-AI/skyvern/pull/4854))
- **Reserved Parameters in Block Editor** — The workflow block parameter picker now shows reserved system parameters, making them discoverable without memorizing names. ([#4857](https://github.com/Skyvern-AI/skyvern/pull/4857))
- **Natural Language Loop `data_schema`** — Loop blocks driven by natural language extraction now support a `data_schema` field for consistent output structure. ([#4851](https://github.com/Skyvern-AI/skyvern/pull/4851))
- **Gemini 3.1 Pro and Inception Mercury-2** — Two new LLM engine options for your automations. ([#4847](https://github.com/Skyvern-AI/skyvern/pull/4847))
- **MCP Server on API Service** — The MCP remote server is now mounted at `/mcp` on the existing API, eliminating the need for a separate process. ([#4843](https://github.com/Skyvern-AI/skyvern/pull/4843))
## Improvements
- Workflow save validation (HTTP 422) now returns clear, field-level error messages. ([#4852](https://github.com/Skyvern-AI/skyvern/pull/4852))
- Browser launch errors now show actionable messages instead of raw exceptions. ([#4844](https://github.com/Skyvern-AI/skyvern/pull/4844))
- Cloud LLM fallback overrides are now properly applied when selecting models. ([#4839](https://github.com/Skyvern-AI/skyvern/pull/4839))
## Bug fixes
- Conditional blocks no longer crash when all branches use Jinja templates. ([#4849](https://github.com/Skyvern-AI/skyvern/pull/4849))
- Conditional blocks no longer misinterpret resolved Jinja template variables. ([#4841](https://github.com/Skyvern-AI/skyvern/pull/4841))
</Update>
<a id="v1-0-20"></a>
<Update label="v1.0.20 — February 21, 2026" description="Browser profile testing UI and 2FA verification flow">
## New features
- **Browser Profile Testing UI (Frontend)** — The Browsers page now lets you launch a test run against a saved browser profile to confirm its login state is still valid before scheduling production workflows. ([#4833](https://github.com/Skyvern-AI/skyvern/pull/4833))
- **2FA Verification Code UI and Notifications** — When a workflow pauses for a 2FA code, the UI now shows a clear prompt and pushes a notification so you don't miss it. ([#4787](https://github.com/Skyvern-AI/skyvern/pull/4787))
## Improvements
- **2FA Backend Cleanup** — Refactored the 2FA pipeline to make code delivery more reliable across both the UI form and the API endpoint. ([#4826](https://github.com/Skyvern-AI/skyvern/pull/4826))
</Update>
<a id="v1-0-19"></a>
<Update label="v1.0.19 — February 20, 2026" description="Admin impersonation controls and configuration improvements">
## New features
- **Gated Admin Impersonation for MCP API Keys** — Adds gated admin controls so support engineers can impersonate an organization scope when troubleshooting MCP-based automations, with audit-friendly access controls. ([#4822](https://github.com/Skyvern-AI/skyvern/pull/4822))
## Improvements
- **Environment Variables Override Mounted API Keys** — In Skyvern's Streamlit-based deployment, env vars now take precedence over keys baked into the image, making local overrides simpler. ([#4824](https://github.com/Skyvern-AI/skyvern/pull/4824))
</Update>
<a id="v1-0-18"></a>
<Update label="v1.0.18 — February 19, 2026" description="Browser profile testing and saved-profile workflows">
## New features
- **Browser Profile Testing** — Test browser profiles directly from the UI to verify that saved login sessions are still valid. Workflows can also run with a saved browser profile, enabling login-free automations that reuse authenticated sessions. ([#4818](https://github.com/Skyvern-AI/skyvern/pull/4818))
## Bug fixes
- When both a TOTP credential and a webhook are configured for 2FA, the credential is now correctly prioritized. ([#4811](https://github.com/Skyvern-AI/skyvern/pull/4811))
</Update>
<a id="v1-0-17"></a>
<Update label="v1.0.17 — February 19, 2026" description="Skills package and cached script management">
## New features
- **Skyvern Skills Package** — The new `skyvern skill` CLI command provides pre-built workflow templates and reference documentation for common automation patterns. ([#4817](https://github.com/Skyvern-AI/skyvern/pull/4817))
- **Clear Cached Scripts API** — A new endpoint lets you clear cached automation scripts for a workflow when a target website changes and you want to force Skyvern to re-learn. ([#4809](https://github.com/Skyvern-AI/skyvern/pull/4809))
</Update>
<a id="v1-0-16"></a>
<Update label="v1.0.16 — February 19, 2026" description="2FA detection, full CLI parity, Claude Opus 4.6 CUA">
## New features
- **Automatic 2FA Detection Without TOTP Credentials** — Skyvern now detects when a website asks for a 2FA code even without pre-configured TOTP credentials. The system pauses and waits for you to provide the code via the UI or webhook. ([#4786](https://github.com/Skyvern-AI/skyvern/pull/4786))
- **Full CLI Parity with MCP** — The CLI now supports browser session management, credential management, block operations, and enhanced workflow commands. Everything available through MCP is now accessible from the command line. ([#4789](https://github.com/Skyvern-AI/skyvern/pull/4789), [#4792](https://github.com/Skyvern-AI/skyvern/pull/4792), [#4793](https://github.com/Skyvern-AI/skyvern/pull/4793))
- **Claude Opus 4.6 CUA Support** — Anthropic's Claude Opus 4.6 is now available as a Computer Use Agent model for driving browser interactions. ([#4780](https://github.com/Skyvern-AI/skyvern/pull/4780))
## Improvements
- The workflow run timeline now properly displays loop iterations and conditional branches, making complex runs easier to debug. ([#4782](https://github.com/Skyvern-AI/skyvern/pull/4782))
## Bug fixes
- Fixed conditional blocks evaluating the wrong value after Jinja template rendering. ([#4801](https://github.com/Skyvern-AI/skyvern/pull/4801))
- Fixed MFA resolution priority when both TOTP credentials and webhooks are configured. ([#4800](https://github.com/Skyvern-AI/skyvern/pull/4800))
</Update>
<a id="v1-0-15"></a>
<Update label="v1.0.15 — February 17, 2026" description="Claude Opus 4.6 model support">
## New features
- **Anthropic Claude Opus 4.6** — Added Claude Opus 4.6 as an available LLM engine for web automation tasks. ([#4777](https://github.com/Skyvern-AI/skyvern/pull/4777), [#4778](https://github.com/Skyvern-AI/skyvern/pull/4778))
</Update>
<a id="v1-0-14"></a>
<Update label="v1.0.14 — February 17, 2026" description="Unified Browser Task block, MCP block discovery, and credential editing">
## New features
- **Unified Browser Task Block** — The Navigation V1 and Task V2 blocks have been merged into a single **Browser Task** block. The block now exposes both engines as a dropdown, simplifying the workflow editor and reducing block-type confusion. ([#4695](https://github.com/Skyvern-AI/skyvern/pull/4695))
- **Block Discovery MCP Tools** — Added MCP tools that let AI assistants enumerate available block types and their schemas, plus richer instructions for building workflows through MCP. ([#4683](https://github.com/Skyvern-AI/skyvern/pull/4683))
- **Edit Existing Credentials API** — A new endpoint lets you update credential values without deleting and recreating them, preserving credential IDs across changes. ([#4693](https://github.com/Skyvern-AI/skyvern/pull/4693))
- **Filter Workflow Runs by Error Code and Search Key** — The workflow runs list endpoint now supports `error_code` and `search_key` query parameters for narrowing down failed runs. ([#4694](https://github.com/Skyvern-AI/skyvern/pull/4694))
- **GPT-5 Mini in Model Selector** — GPT-5 Mini is now selectable as an LLM engine. GPT-5 has been hidden in favor of more reliable variants. ([#4686](https://github.com/Skyvern-AI/skyvern/pull/4686))
## Improvements
- **Block Failure Reasons Surfaced in UI** — Every block type now shows its `failure_reason` in the run timeline, making debugging non-obvious failures faster. ([#4672](https://github.com/Skyvern-AI/skyvern/pull/4672))
- **Webhook Payload Truncation in Logs** — Large webhook payloads are now truncated in log entries, keeping logs readable without losing context. ([#4701](https://github.com/Skyvern-AI/skyvern/pull/4701))
## Bug fixes
- Fixed the cursor jumping to the end while editing conditional expressions in the workflow editor. ([#4682](https://github.com/Skyvern-AI/skyvern/pull/4682))
- Fixed dotted Jinja variables (e.g. `{{ block_output.field }}`) rendering incorrectly in the expression preview. ([#4684](https://github.com/Skyvern-AI/skyvern/pull/4684))
- The API now returns 404 instead of 500 when a workflow is not found. ([#4699](https://github.com/Skyvern-AI/skyvern/pull/4699))
</Update>
<a id="v1-0-13"></a>
<Update label="v1.0.13 — February 10, 2026" description="Cached scripts for control-flow blocks, OTEL, and workflow editor polish">
## New features
- **Conditional Block Caching** — The script cache now supports Conditional blocks, so workflows that branch based on page state can replay from cache instead of re-running the AI agent. ([#4642](https://github.com/Skyvern-AI/skyvern/pull/4642))
- **OpenTelemetry Backend** — Skyvern can now export metrics, traces, and logs to any OTEL-compatible collector for centralized observability. ([#4632](https://github.com/Skyvern-AI/skyvern/pull/4632))
- **Workflow API Route Reorganization** — Workflow API endpoints have been split into focused routers, making the OpenAPI surface easier to navigate. ([#4628](https://github.com/Skyvern-AI/skyvern/pull/4628))
## Improvements
- **Workflow Copilot Auto-Opens for Empty Workflows** — When you create a new workflow with no blocks yet, the Workflow Copilot opens by default to help you get started. ([#4625](https://github.com/Skyvern-AI/skyvern/pull/4625))
- **Run Workflow Button Moved to Top** — The Run button now lives at the top of the workflow editor for easier access. ([#4626](https://github.com/Skyvern-AI/skyvern/pull/4626))
- **Skip LLM for Single-Match Location Autocomplete** — Location autocomplete now skips the LLM call when only one option matches the user's input, reducing cost and latency. ([#4631](https://github.com/Skyvern-AI/skyvern/pull/4631))
- **Improved Version History Icon** — The workflow version history button now uses an icon that better represents document versions. ([#4640](https://github.com/Skyvern-AI/skyvern/pull/4640))
## Bug fixes
- Fixed `ForLoop` blocks failing to execute under script caching (regression from v1.0.12). ([#4630](https://github.com/Skyvern-AI/skyvern/pull/4630))
- Fixed `ActionDragPath` subscript error in CUA drag-action parsing. ([#4623](https://github.com/Skyvern-AI/skyvern/pull/4623))
- Fixed cron-scheduled tasks getting stuck with "task not found" errors. ([#4627](https://github.com/Skyvern-AI/skyvern/pull/4627))
- Fixed parameter creation dialog not clearing default-value state when switching to credential type. ([#4622](https://github.com/Skyvern-AI/skyvern/pull/4622))
- Fixed debugger loop-block visual overlap when the status row appeared. ([#4641](https://github.com/Skyvern-AI/skyvern/pull/4641))
</Update>
<a id="v1-0-12"></a>
<Update label="v1.0.12 — February 3, 2026" description="Task V2 termination, ForLoop caching, and cleaner conditional debugging">
## New features
- **Task V2 Termination** — Task V2 (the planner-agent-validator system) can now be terminated mid-run via API, matching the cancel behavior already available for Task V1. ([#4589](https://github.com/Skyvern-AI/skyvern/pull/4589))
- **ForLoop Block Caching** — Cached scripts now support `ForLoop` blocks. Workflows that iterate over lists can replay from cache after the first successful run. ([#4600](https://github.com/Skyvern-AI/skyvern/pull/4600))
- **Conditional Block Caching** — Initial support for caching workflows that include conditional branching. ([#4603](https://github.com/Skyvern-AI/skyvern/pull/4603))
- **`run_with` Parameter for Run Task** — The `run_task` endpoint now accepts a `run_with` parameter so you can target Task V2 (or future variants) without changing the endpoint. ([#4576](https://github.com/Skyvern-AI/skyvern/pull/4576))
- **`skyvern run dev` Command** — A new CLI command spins up a Superset workspace alongside the standard dev environment for local analytics work. ([#4593](https://github.com/Skyvern-AI/skyvern/pull/4593))
## Improvements
- **All Branch Evaluations Shown in Conditional Block Timeline** — The run timeline now shows every conditional branch's evaluation result, not just the chosen one — useful when debugging "why did it pick that branch?" ([#4577](https://github.com/Skyvern-AI/skyvern/pull/4577))
- **Sidebar Expand/Collapse Icon** — Replaced the pin icon with a chevron, matching common conventions. ([#4586](https://github.com/Skyvern-AI/skyvern/pull/4586))
- **PDF Parsing Token Cap** — PDF parsing now caps token volume per request to avoid total failure on very large documents. ([#4602](https://github.com/Skyvern-AI/skyvern/pull/4602))
- **`DATABASE_STRING` Parameter on Quickstart** — `skyvern quickstart` now accepts a `DATABASE_STRING` argument for explicit DB connection configuration. ([#4580](https://github.com/Skyvern-AI/skyvern/pull/4580))
## Bug fixes
- Fixed credentials not clearing from the Login block when deselected from the picker. ([#4581](https://github.com/Skyvern-AI/skyvern/pull/4581))
- Fixed workflow run timeline missing recent steps until a manual refresh. ([#4587](https://github.com/Skyvern-AI/skyvern/pull/4587))
- Fixed the workflow editor showing spurious "unsaved changes" when switching between conditional branches. ([#4588](https://github.com/Skyvern-AI/skyvern/pull/4588))
</Update>
<a id="v1-0-11"></a>
<Update label="v1.0.11 — January 29, 2026" description="Workflow Copilot GA, Browser Sessions v2 frontend, and TOTP improvements">
## New features
- **Workflow Copilot Generally Available** — The Workflow Copilot is now enabled for all users. Describe what you want in natural language and it generates a multi-block workflow you can edit. ([#4533](https://github.com/Skyvern-AI/skyvern/pull/4533))
- **Browser Sessions v2 Frontend** — The new browser session management UI lands on the Browsers page, building on the v2 backend shipped in v1.0.10. ([#4514](https://github.com/Skyvern-AI/skyvern/pull/4514))
- **TOTP Endpoint OTP Type Filter** — The TOTP listing endpoint now accepts an `otp_type` query parameter for filtering numeric codes vs. magic links. ([#4529](https://github.com/Skyvern-AI/skyvern/pull/4529))
- **Mintlify Documentation Setup** — Skyvern's documentation site moves to Mintlify, with redirects for the legacy Fern URLs. ([#4516](https://github.com/Skyvern-AI/skyvern/pull/4516))
## Improvements
- **Async File I/O via aiofiles** — Replaced blocking file I/O with `aiofiles` throughout the agent runtime, improving throughput on I/O-heavy workloads. ([#4520](https://github.com/Skyvern-AI/skyvern/pull/4520))
- **Cached Experimentation Provider TTL** — `BaseExperimentationProvider` now caches feature-flag lookups with a per-item TTL, reducing pressure on the experimentation backend. ([#4536](https://github.com/Skyvern-AI/skyvern/pull/4536), [#4540](https://github.com/Skyvern-AI/skyvern/pull/4540))
## Bug fixes
- Fixed `ai_fallback` not being read correctly from the database for cached workflow runs. ([#4524](https://github.com/Skyvern-AI/skyvern/pull/4524))
- Fixed iframe-tree extraction crashing when the page raised a transient exception. ([#4530](https://github.com/Skyvern-AI/skyvern/pull/4530))
- Fixed the workflow version comparison view ordering versions on the wrong sides. ([#4531](https://github.com/Skyvern-AI/skyvern/pull/4531))
- Fixed the workflow history panel scroll behavior in debug mode. ([#4532](https://github.com/Skyvern-AI/skyvern/pull/4532))
- Fixed `TypeError` when comparing offset-naive and offset-aware datetimes during workflow scheduling. ([#4534](https://github.com/Skyvern-AI/skyvern/pull/4534))
- Fixed schema regeneration overwriting unchanged block field names. ([#4535](https://github.com/Skyvern-AI/skyvern/pull/4535))
- Fixed `uvicorn` reload breaking on Windows due to async event loop policy. ([#4538](https://github.com/Skyvern-AI/skyvern/pull/4538))
</Update>
<a id="v1-0-10"></a>
<Update label="v1.0.10 — January 22, 2026" description="Browser Sessions v2 backend, general text CAPTCHA, and TOTP webhook retries">
## New features
- **Browser Sessions v2 (Backend)** — A new persistent browser session architecture with cleaner lifecycle management, better resource reuse, and improved reliability for long-running automations. The frontend follows in v1.0.11. ([#4515](https://github.com/Skyvern-AI/skyvern/pull/4515))
- **General Text CAPTCHA Solver** — Skyvern can now solve a wider range of text-based CAPTCHAs without site-specific configuration. ([#4517](https://github.com/Skyvern-AI/skyvern/pull/4517))
- **TOTP Webhook Retries** — TOTP webhook delivery now retries automatically on transient failures, reducing the rate of "no code received" errors during 2FA flows. ([#4518](https://github.com/Skyvern-AI/skyvern/pull/4518))
- **Block-Label Validation in `run_blocks`** — The `run_blocks` endpoint now validates block labels up front, returning a clear error instead of failing partway through execution. ([#4500](https://github.com/Skyvern-AI/skyvern/pull/4500))
## Improvements
- **Confirmation Dialog Shows Affected Blocks** — Deleting a parameter or block now lists every block that references it, so you don't accidentally break downstream logic. ([#4519](https://github.com/Skyvern-AI/skyvern/pull/4519))
- **Workflow Updates Return 409 on Race** — Concurrent workflow updates now return HTTP 409 instead of silently overwriting each other. ([#4510](https://github.com/Skyvern-AI/skyvern/pull/4510))
- **Tiktoken Caching** — Tokenizer instances are now cached, cutting per-step overhead on token counting. ([#4521](https://github.com/Skyvern-AI/skyvern/pull/4521))
## Bug fixes
- Fixed a Gemini 3 Flash cache-creation bug that caused false-positive fallback detection. ([#4502](https://github.com/Skyvern-AI/skyvern/pull/4502))
- Fixed Bitwarden item-ID format validation rejecting valid IDs. ([#4508](https://github.com/Skyvern-AI/skyvern/pull/4508))
- Fixed dangling block-output and parameter references after rename or deletion. ([#4507](https://github.com/Skyvern-AI/skyvern/pull/4507))
</Update>
<a id="v1-0-9"></a>
<Update label="v1.0.9 — January 20, 2026" description="Print PDF block, Workflow Copilot streaming, and persistent session billing">
## New features
- **Print PDF Block** — A new workflow block that prints the current page to PDF and saves it to your run's downloaded files, useful for archiving receipts, invoices, and reports. ([#4452](https://github.com/Skyvern-AI/skyvern/pull/4452))
- **HTTP File Downloads** — The HTTP Request block can now download files directly via HTTP (not just GET JSON), enabling workflows that pull artifacts from authenticated APIs. ([#4440](https://github.com/Skyvern-AI/skyvern/pull/4440))
- **Workflow Copilot Streaming with Cancel** — The Workflow Copilot now streams its responses with a cancel button, so you can stop generation mid-stream if you want to refine your prompt. ([#4437](https://github.com/Skyvern-AI/skyvern/pull/4437), [#4456](https://github.com/Skyvern-AI/skyvern/pull/4456))
- **"Execute on Any Outcome" (Finally) Block Option** — Blocks can now be configured to run regardless of whether prior blocks succeeded, enabling cleanup steps and "always send report" workflows. ([#4443](https://github.com/Skyvern-AI/skyvern/pull/4443))
- **Persistent Browser Session Uptime Billing** — Billing v2 now meters persistent browser session uptime separately, with PostHog feature flags controlling rollout. ([#4444](https://github.com/Skyvern-AI/skyvern/pull/4444))
- **GPT-5 Mini Flex Engine** — Added GPT-5 Mini Flex as an available LLM engine. ([#4432](https://github.com/Skyvern-AI/skyvern/pull/4432))
- **Clipboard Copy over HTTP** — The browser now exposes clipboard copy functionality that works in HTTP-served browser sessions, not just HTTPS. ([#4446](https://github.com/Skyvern-AI/skyvern/pull/4446))
## Improvements
- **HTTP Block Boolean and Integer Templates** — The HTTP Request block now correctly passes boolean and integer template values without coercing them to strings. ([#4435](https://github.com/Skyvern-AI/skyvern/pull/4435))
- **Bitwarden and Azure Vault Tooltips** — Added inline help tooltips explaining how to set up Bitwarden and Azure Key Vault credential sources. ([#4447](https://github.com/Skyvern-AI/skyvern/pull/4447))
- **Smaller S3 Objects Use STANDARD Tier** — Storage cost optimization: small artifacts now use STANDARD instead of GLACIER_IR. ([#4453](https://github.com/Skyvern-AI/skyvern/pull/4453))
- **Reduced Max SVG Parsing** — Lowered the SVG parsing cap to prevent runaway memory usage on pathological pages. ([#4430](https://github.com/Skyvern-AI/skyvern/pull/4430))
</Update>
<a id="v1-0-8"></a>
<Update label="v1.0.8 — January 9, 2026" description="Workflow Copilot v1, Azure secret storage, and per-action billing">
## New features
- **Workflow Copilot v1** — The first version of the Workflow Copilot ships behind a feature flag. Describe a workflow in natural language and the copilot generates blocks, parameters, and connections you can edit on the canvas. ([#4401](https://github.com/Skyvern-AI/skyvern/pull/4401), [#4413](https://github.com/Skyvern-AI/skyvern/pull/4413), [#4416](https://github.com/Skyvern-AI/skyvern/pull/4416), [#4423](https://github.com/Skyvern-AI/skyvern/pull/4423))
- **Per-Action Credit Billing (Billing v2)** — A new billing model meters credits per browser action instead of per step, giving more predictable cost behavior on action-heavy workflows. ([#4398](https://github.com/Skyvern-AI/skyvern/pull/4398))
- **Azure Key Vault Secret Storage** — Skyvern can now store and retrieve credentials from Azure Key Vault as a managed secret backend. ([#4384](https://github.com/Skyvern-AI/skyvern/pull/4384))
- **Conditional Inside Conditional** — Conditional blocks can now be nested inside other conditional blocks for richer branching logic. ([#4362](https://github.com/Skyvern-AI/skyvern/pull/4362))
- **Reference Workflow Output in Sub-Blocks** — Blocks can now reference upstream `workflow_output` variables, simplifying multi-stage workflows. ([#4414](https://github.com/Skyvern-AI/skyvern/pull/4414))
- **Browser Type Choice for Persistent Browser Sessions** — Persistent sessions now let you choose the browser type (Chromium, etc.) at create time. ([#4406](https://github.com/Skyvern-AI/skyvern/pull/4406))
- **Browser Extension Support for PBS** — Persistent browser sessions can launch with a specified browser extension. ([#4364](https://github.com/Skyvern-AI/skyvern/pull/4364))
- **Step Count in Webhooks and Run Payloads** — Webhook payloads and `get_run` responses now include `step_count` for cost reconciliation. ([#4410](https://github.com/Skyvern-AI/skyvern/pull/4410))
- **PH (Philippines) Proxy Location** — Added Philippines as a residential proxy option. ([#4395](https://github.com/Skyvern-AI/skyvern/pull/4395))
- **TextPromptBlock Artifact Storage** — TextPromptBlock now saves the LLM prompt and response as run artifacts for debugging. ([#4361](https://github.com/Skyvern-AI/skyvern/pull/4361))
- **Action–Screenshot Linking** — Actions in the run timeline now link directly to the screenshot captured at the time of execution, so you can see what the agent saw when it made each decision. ([#4403](https://github.com/Skyvern-AI/skyvern/pull/4403), [#4404](https://github.com/Skyvern-AI/skyvern/pull/4404))
## Improvements
- **Clearer Errors for Missing Workflow Parameters** — Missing required parameters now return a clear HTTP 400 instead of HTTP 500. ([#4380](https://github.com/Skyvern-AI/skyvern/pull/4380))
- **Empty-String Defaults for String Parameters** — Workflow string parameters without explicit defaults now initialize to `""` instead of `null`, matching common Jinja-template expectations. ([#4382](https://github.com/Skyvern-AI/skyvern/pull/4382))
- **HAR Files Use Zstd Compression** — HAR archives now ship as `.har.zst`, cutting storage size significantly with no fidelity loss. ([#4420](https://github.com/Skyvern-AI/skyvern/pull/4420))
- **Hydrated Workflow Title in Run Responses** — `workflow_run` responses now include the workflow title for cleaner logging without an extra API call. ([#4363](https://github.com/Skyvern-AI/skyvern/pull/4363))
- **Cached Workflow-Script Lookup** — `get_workflow_script_by_cache_key_value` is now cached and post-action execution can re-enable code generation. ([#4385](https://github.com/Skyvern-AI/skyvern/pull/4385))
- **Updated Datacenter Proxy Provider** — Datacenter proxies now route through a new provider with broader IP coverage. ([#4386](https://github.com/Skyvern-AI/skyvern/pull/4386))
- **Improved Conditional NL Branch Tooltip** — Updated tooltip and placeholder text on conditional blocks to better describe how natural-language branches are evaluated. ([#4368](https://github.com/Skyvern-AI/skyvern/pull/4368), [#4369](https://github.com/Skyvern-AI/skyvern/pull/4369))
- **OLLAMA Vision Support Toggle** — Added `OLLAMA_SUPPORTS_VISION` env var to enable vision-capable Ollama models. ([#4351](https://github.com/Skyvern-AI/skyvern/pull/4351))
## Bug fixes
- Fixed older credentials becoming inaccessible after an internal schema change. ([#4358](https://github.com/Skyvern-AI/skyvern/pull/4358))
- Fixed scrolling actions misfiring on pages with overflow-hidden ancestors. ([#4389](https://github.com/Skyvern-AI/skyvern/pull/4389))
- Fixed `close_browser_on_completion` not being honored during workflow run cleanup. ([#4381](https://github.com/Skyvern-AI/skyvern/pull/4381))
- Fixed run-ID generation collisions under high concurrency. ([#4383](https://github.com/Skyvern-AI/skyvern/pull/4383))
- Fixed empty browser-extension config crashing PBS launch. ([#4365](https://github.com/Skyvern-AI/skyvern/pull/4365))
- Fixed wrong screenshots being attached to certain actions. ([#4400](https://github.com/Skyvern-AI/skyvern/pull/4400))
- Fixed nested DB connection management in workflow execution. ([#4402](https://github.com/Skyvern-AI/skyvern/pull/4402), [#4411](https://github.com/Skyvern-AI/skyvern/pull/4411))
- Fixed `local variable not defined` errors in cached-action execution. ([#4376](https://github.com/Skyvern-AI/skyvern/pull/4376))
- Fixed artifacts endpoint incorrectly including `api/` in the path. ([#4417](https://github.com/Skyvern-AI/skyvern/pull/4417))
- Fixed S3 storage class selection for small objects (`_get_storage_class_for_org`). ([#4424](https://github.com/Skyvern-AI/skyvern/pull/4424))
- Fixed cached actions executing without a brief settling delay. ([#4418](https://github.com/Skyvern-AI/skyvern/pull/4418))
</Update>
</div>
</div>
+65
View File
@@ -0,0 +1,65 @@
---
title: API Key
subtitle: Authenticate programmatic access to Skyvern
description: Find, copy, and use your Skyvern API key from the Cloud UI Settings page to authenticate REST API and SDK requests.
slug: cloud/account-settings/api-keys
keywords:
- API key
- x-api-key
- authentication
- settings
- copy
- regenerate
---
Every API call to Skyvern requires an API key. The key identifies your organization and determines billing.
## Finding your API key
Open **Settings** in the sidebar. Your API key is shown in a masked field. Click the **eye icon** to reveal the full value, or the **copy icon** to copy it to your clipboard.
<img src="/images/cloud/settings-api-key.png" alt="API key display with reveal and copy buttons" />
<Warning>
Treat your API key like a password. Anyone with this key can create runs, read results, and manage workflows on behalf of your organization.
</Warning>
## Using your key
Every Skyvern API request requires the `x-api-key` header:
```bash
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com", "prompt": "Extract the pricing table" }'
```
With the Python SDK:
```python
from skyvern import Skyvern
client = Skyvern(api_key="YOUR_API_KEY")
```
<Tip>
Store the key in an environment variable (`SKYVERN_API_KEY`) rather than hardcoding it. In production, use your platform's secrets management (AWS Secrets Manager, Vault, etc.).
</Tip>
<CardGroup cols={2}>
<Card
title="API Reference"
icon="code"
href="/api-reference"
>
Full endpoint documentation with interactive playground
</Card>
<Card
title="Billing & Usage"
icon="receipt"
href="/cloud/account-settings/billing-usage"
>
Understand how runs are metered and billed
</Card>
</CardGroup>
@@ -0,0 +1,146 @@
---
title: Billing & Usage
subtitle: Understand what you're paying for and manage your plan
description: Understand Skyvern's credit-based billing model, compare Free, Hobby, Pro, and Enterprise plans, and manage your subscription from the Cloud UI Billing page.
slug: cloud/account-settings/billing-usage
keywords:
- billing
- credits
- plan
- pricing
- Free
- Hobby
- Pro
- Enterprise
- usage
---
Skyvern bills per **credit**: each browser action the AI takes during a run consumes credits. You pay for real work, not for workflows created or credentials stored.
## Plans
Open **Billing** in the sidebar to see available plans and your current balance.
<img src="/images/cloud/settings-billing-overview.png" alt="Billing page showing plan options and current balance" />
| Plan | Price | Credits/month | Estimated actions | Concurrent runs |
|------|-------|---------------|-------------------|-----------------|
| **Free** | $0 | 1,000 | ~170 | 1 |
| **Hobby** | $29/month | 30,000 | ~1,200 | 10 |
| **Pro** | $149/month | 150,000 | ~6,200 | 25 |
| **Enterprise** | Custom | Unlimited | Unlimited | Unlimited |
**Free** is available to all new accounts with zero commitment. **Hobby** and **Pro** are monthly subscriptions. Click **Switch to Hobby** or **Switch to Pro** to change plans. Your remaining dollar balance is applied as a credit toward your first subscription payment.
<Note>
Need HIPAA compliance, SOC-2 reports, custom code blocks, or dedicated support? Use the **Book a call** link at the bottom of the Billing page to discuss **Enterprise**, or visit [skyvern.com/pricing](https://skyvern.com/pricing) for a complete feature comparison.
</Note>
### What's included in each plan
<AccordionGroup>
<Accordion title="Free: Try Skyvern with zero commitment">
**1,000 credits/month** (~170 actions)
Perfect for evaluating Skyvern and prototyping automations.
- 1 concurrent run
- Webhooks
- Country geo-targeting
- Community support
</Accordion>
<Accordion title="Hobby: For side projects and small automations">
**30,000 credits/month** (~1,200 actions) • **$29/month**
- 10 concurrent runs
- Basic CAPTCHA solver
- Webhooks
- Stored credentials
- Country geo-targeting
- Email support
</Accordion>
<Accordion title="Pro: For teams shipping production automations">
**150,000 credits/month** (~6,200 actions) • **$149/month**
Everything in Hobby, plus:
- 25 concurrent runs
- Advanced CAPTCHA solver
- Team workspaces
- 2FA / TOTP support
- 1Password integration
- Residential proxy
- City-level geo-targeting
- Priority support
</Accordion>
<Accordion title="Enterprise: For regulated industries and large-scale operations">
**Unlimited credits** • **Custom pricing**
Everything in Pro, plus:
- Unlimited concurrent runs
- HIPAA compliant infrastructure
- SOC-2 Type II Report
- Dedicated Slack channel
- Azure Key Vault integration
- Bitwarden integration
- Custom code blocks
- Human-in-the-loop workflows
[Contact sales](https://skyvern.com/contact) to discuss Enterprise.
</Accordion>
</AccordionGroup>
## How credits are consumed
A credit maps to one discrete browser action: clicking a button, typing into a field, selecting a dropdown, or extracting data from a page. Navigation counts too.
| Example | Approximate credits |
|---------|---------------------|
| Login flow (email, password, submit) | ~3 |
| Form fill (10 fields + submit) | ~11 |
| Multi-page extraction (5 pages) | ~15–25 |
Credits consumed by a run are visible on the [Run Details](/cloud/viewing-results/run-details) page. The **Actions** counter at the top of the Overview timeline shows exactly how many actions the AI took.
<Tip>
Reduce credit usage by being specific in your prompts. "Find information about pricing" causes the AI to explore multiple pages. "Extract the monthly price from the pricing table on /pricing" gets there directly.
</Tip>
## Your current balance
The **Your Current Balance** section shows your remaining dollar balance. Credits are deducted as runs execute in real time. If your balance reaches zero, new runs won't start until you add credits or switch to a subscription plan.
## FAQ
<Accordion title="How do credits work?">
Each browser action the AI takes (clicking, typing, navigating, extracting) costs one credit. Credits are deducted in real time as runs execute. Your plan includes a monthly credit allowance that resets each billing cycle. Unused credits don't roll over.
</Accordion>
<Accordion title="Can I buy more credits?">
Yes. If you exhaust your monthly allowance, you can purchase additional credits from the Billing page. You can also upgrade to a higher plan for a larger monthly allowance.
</Accordion>
<Accordion title="Can I cancel anytime?">
Yes. Downgrade or cancel your subscription from the Billing page. The change takes effect at the end of your current billing cycle, and you keep access to your credits until then.
</Accordion>
<CardGroup cols={2}>
<Card
title="API Keys"
icon="key"
href="/cloud/account-settings/api-keys"
>
Manage API keys for programmatic access
</Card>
<Card
title="Organization Settings"
icon="building"
href="/cloud/account-settings/organization-settings"
>
Manage your team and organization details
</Card>
</CardGroup>
@@ -0,0 +1,58 @@
---
title: Organization Settings
subtitle: Manage your organization name and team access
description: Manage your organization name, invite and remove team members, and configure access settings from the Skyvern Cloud UI Settings page.
slug: cloud/account-settings/organization-settings
keywords:
- organization
- team
- invite
- members
- access
- permissions
---
Everything in Skyvern (workflows, credentials, runs, API keys) belongs to an **organization**. One is created automatically when you sign up.
## Organization details
Open **Settings** in the sidebar. The Settings page shows your organization name and current plan. The organization name appears throughout the UI and in API responses.
To rename your organization, update the **Organization Name** field and click **Save**.
## Team members
Plans that support multiple users (Pro and Enterprise) show a **Members** section below the organization details.
### Inviting members
Click **Invite Member**, enter their email address, and send the invitation. They'll receive an email with a link to join your organization. Once they accept, they appear in the members list with full access to workflows, runs, credentials, and API keys.
### Removing members
Click the **remove icon** next to a member's name to revoke their access. They lose access to all organization resources immediately.
<Warning>
When removing a team member, also review your [API keys](/cloud/account-settings/api-keys); they may have copied keys that remain active.
</Warning>
<Note>
Role-based access control (restricting what individual members can do) is available on **Enterprise** plans. On other plans, all members have full access to the organization's resources.
</Note>
<CardGroup cols={2}>
<Card
title="Profile Settings"
icon="user"
href="/cloud/account-settings/profile-settings"
>
Manage your personal account settings
</Card>
<Card
title="API Keys"
icon="key"
href="/cloud/account-settings/api-keys"
>
View and manage API keys for your organization
</Card>
</CardGroup>
@@ -0,0 +1,51 @@
---
title: Profile Settings
subtitle: Manage your personal account and security
description: Update your display name, change your password, and review active sessions from the Skyvern Cloud UI Account page.
slug: cloud/account-settings/profile-settings
keywords:
- profile
- display name
- password
- active sessions
- account security
---
Click your avatar at the bottom of the sidebar to open the **Account** page. It has two tabs: **Profile** and **Security**.
## Profile
The **Profile** tab shows your display name and email address. Update your display name and click **Save** to apply.
## Security
The **Security** tab is where you manage your password and review active sessions.
<img src="/images/cloud/change-password.png" alt="Account Security tab showing password fields and active devices" />
Under **Set password**, enter your new password and confirm it. A green checkmark appears when the password meets requirements and both fields match. Check **Sign out of all other devices** if you want to invalidate existing sessions, recommended if you suspect unauthorized access.
Click **Save** to apply.
**Active devices** lists every device currently signed into your account, showing the browser, IP address, and last access time. Use this to verify that all sessions are yours.
<Note>
If you signed up with Google or another SSO provider, password management is handled by the external provider and this section may not appear.
</Note>
<CardGroup cols={2}>
<Card
title="Organization Settings"
icon="building"
href="/cloud/account-settings/organization-settings"
>
Manage your team and organization details
</Card>
<Card
title="API Keys"
icon="key"
href="/cloud/account-settings/api-keys"
>
View and manage API keys
</Card>
</CardGroup>
@@ -0,0 +1,118 @@
---
title: Browser Profiles
subtitle: Save and reuse login state across sessions
description: Save and reuse browser state snapshots in the Skyvern Cloud UI to skip login flows by restoring cookies and session data from a previously authenticated browser session.
slug: cloud/browser-management/browser-profiles
keywords:
- state snapshot
- cookies
- session restore
- skip login
- authenticated state
- reuse
---
A **browser profile** is a saved snapshot of browser state: cookies, localStorage, and session files. Load a profile into a new [browser session](/cloud/browser-management/browser-sessions) and the browser starts with that saved state restored, skipping login flows you've already completed.
Profiles are ideal when you:
- Run the same automation repeatedly with the same account (daily reports, scheduled data extraction)
- Want to skip login steps that consume credits and time
- Need multiple workflows to share the same authenticated state
<Note>
Looking to manage profiles from code? See the [API & SDK guide](/developers/optimization/browser-profiles) instead.
</Note>
---
## How profiles are created
Browser profiles are created automatically when you test a password credential with the **Save browser session** option enabled. There is no standalone "create profile" button; the profile is a byproduct of a successful login test.
### Creating a profile from a credential
<Steps>
<Step title="Go to the Credentials page">
Click **Credentials** in the left sidebar under **General**.
</Step>
<Step title="Create or edit a password credential">
Click **+ Add → Password** to create a new credential, or click the **pencil icon** on an existing one. Enter the username and password. See [Password Credentials](/cloud/managing-credentials/password-credentials) for details.
<img src="/images/cloud/credential-add-password-form.png" alt="Add password credential dialog with name, username, and password fields" />
</Step>
<Step title="Enable Save browser session">
Below the password fields, enable the **Save browser session** option. Enter the **login URL** for the site (e.g., `https://app.example.com/login`). You can also add optional context to help the AI navigate the login flow.
</Step>
<Step title="Test the credential">
Click **Test**. Skyvern opens a browser, navigates to the login URL, signs in with the credential, and, if the login succeeds, saves the browser state as a profile. The profile is linked to this credential automatically.
</Step>
<Step title="Confirm the profile was saved">
When the test completes, the credential row shows a **saved-profile** badge with the site hostname. This means the browser profile is ready to use.
<img src="/images/cloud/credential-save-profile.png" alt="Credential listed with a profile badge" />
</Step>
</Steps>
<Tip>
The **Save browser session** flow is the easiest way to create a profile. It handles the full lifecycle: open browser, log in, save state. No workflows or API calls required.
</Tip>
---
## When to refresh profiles
Cookies and session tokens expire. A profile that worked last week may not work today if the site's authentication tokens have a short lifespan.
**Signs a profile needs refreshing:**
- Tasks that use the profile start failing with login-related errors
- The browser loads a login page instead of the authenticated dashboard
- The site forces re-authentication after a set period
**To refresh:** go back to the credential, click **Test** again with **Save browser session** enabled. The new profile replaces the old one.
<Tip>
For sites with short-lived sessions (banks, healthcare portals), refresh profiles before each batch of runs. For sites with long-lived cookies (most SaaS apps), weekly or monthly refreshes are usually sufficient.
</Tip>
---
## Sessions vs profiles
| | Browser Session | Browser Profile |
|---|----------------|-----------------|
| **What it is** | Live browser instance | Saved snapshot of browser state |
| **Lifetime** | Minutes to hours | Days to months |
| **State** | Current page, cookies, open connections | Cookies, localStorage, session files |
| **Billing** | Charged while open | No cost when not in use |
| **Best for** | Back-to-back tasks, human-in-the-loop | Repeated logins, scheduled workflows |
---
## What's next
<CardGroup cols={3}>
<Card
title="Browser Sessions"
icon="browser"
href="/cloud/browser-management/browser-sessions"
>
Keep a browser open across multiple tasks
</Card>
<Card
title="Password Credentials"
icon="key"
href="/cloud/managing-credentials/password-credentials"
>
Store the login details that profiles are built from
</Card>
<Card
title="Browser Profiles (API)"
icon="code"
href="/developers/optimization/browser-profiles"
>
Create and manage profiles programmatically
</Card>
</CardGroup>
@@ -0,0 +1,181 @@
---
title: Browser Sessions
subtitle: Keep a browser open across multiple tasks
description: Create and manage persistent browser sessions in the Skyvern Cloud UI to preserve cookies, login state, and page context across multiple tasks and workflows.
slug: cloud/browser-management/browser-sessions
keywords:
- persistent browser
- cookies
- local storage
- page context
- timeout
- live session
---
A **browser session** is a live browser instance that stays open between runs. Cookies, login state, cart contents, and page context all persist, like keeping a browser tab open. Use sessions when you need back-to-back tasks to share state, or when you want to interact with the browser yourself between automated steps.
<Note>
Looking to use browser sessions from code? See the [API & SDK guide](/developers/optimization/browser-sessions) instead.
</Note>
---
## The Browsers page
Click **Browsers** in the left sidebar to open the Browsers page. It lists all browser sessions in your organization.
<img src="/images/cloud/browsers-page-overview.png" alt="Browsers page with the sessions table showing columns for ID, open status, occupied status, started time, timeout, and CDP URL" />
Each row shows:
| Column | What it shows |
|--------|--------------|
| **ID** | Session identifier (starts with `pbs_`) |
| **Open** | Whether the browser is currently running |
| **Occupied** | Whether a task or workflow is actively using the session |
| **Started** | When the session launched |
| **Timeout** | How long the session stays open before auto-closing |
| **CDP URL** | Chrome DevTools Protocol address for direct connection |
---
## Creating a session
Click the **Create Browser Session** button at the top of the Browsers page. A panel opens with the following settings:
<Frame>
<img src="/images/cloud/create-session-drawer.png" alt="Create Browser Session panel showing fields for timeout, proxy location, browser type, extensions, and browser profile" width="300" />
</Frame>
| Setting | What it does |
|---------|-------------|
| **Timeout** | How long the session stays open, in minutes. Min: 5, max: 1440 (24 hours). Default: 60. |
| **Proxy Location** | Route the browser through a residential proxy in a specific country. Default: US. |
| **Browser Type** | Chrome (default, widest compatibility) or Microsoft Edge. |
| **Extensions** | Optional add-ons: **Ad Blocker** (removes overlay ads that interfere with clicks) and **Captcha Solver** (auto-solves CAPTCHAs). |
| **Browser Profile** | Load a saved [browser profile](/cloud/browser-management/browser-profiles) to restore cookies and login state from a previous session. |
Click **Create** to launch the session. It appears in the table within a few seconds.
<Warning>
Sessions bill while open, even when idle. Set the timeout to match your use case and close sessions when you're done.
</Warning>
---
## Viewing a live session
Click any session row in the table to open its detail page. The detail page has three tabs:
### Stream
A live view of the browser. You can watch pages load and actions fire in real time.
Click on <kbd>Take Control</kbd> to interact with the browser yourself. Use this to log in, dismiss a popup, solve a CAPTCHA.
<img src="/images/cloud/session-detail-stream.png" alt="Browser session detail page with the Stream tab active, showing a live browser view and session controls" />
### Recordings
Video recordings of activity in the session. Each recording captures what happened during a task or workflow that ran inside this session.
### Downloads
Files downloaded by the browser during the session. Click any file to save it locally.
<img src="/images/cloud/browser-session-downloads.png" alt="Browser session download page with the preview or download links for anything downloaded during the session" />
---
## Using a session with a task
Once you have a running session, you can run tasks inside it from the [Discover page](/cloud/getting-started/run-a-task):
1. Copy the session ID (`pbs_...`) from the Browsers page
2. Go to the **Discover** page
3. Click the **gear icon** to open Advanced Settings
4. Paste the ID into the **Browser Session ID** field
5. Write your prompt and run
The task executes inside your existing session. Cookies, login state, and page context from previous tasks are still there.
<img src="/images/cloud/discover-session-id-field.png" alt="Advanced settings panel on the Discover page with a pbs_ session ID entered in the Browser Session ID field" />
---
## Using a session with a workflow
You can also run workflows inside an existing session:
1. Copy the session ID from the Browsers page
2. Go to **Workflows** and click **Run** on your workflow
3. On the parameters page, scroll to **Run Settings**
4. Paste the ID into the **Browser Session ID** field
5. Click **Run Workflow**
The workflow picks up where the browser left off: same page, same cookies, same form data.
<img src="/images/cloud/workflow-run-session-id-field.png" alt="Workflow run settings panel with a pbs_ session ID entered in the Browser Session ID field" />
---
## Closing a session
From the session detail page, click **Stop**. A confirmation dialog appears. The browser shuts down immediately and the session moves to `closed` status.
<img src="/images/cloud/session-stop-confirmation.png" alt="Stop browser session confirmation dialog with Cancel and Stop buttons" />
Sessions also close automatically when their timeout expires, **even if a task is still running**. Set timeouts with enough margin for your longest expected task.
<Warning>
Closed sessions cannot be reopened. If you need the same login state later, create a [browser profile](/cloud/browser-management/browser-profiles) before closing.
</Warning>
---
## When to use sessions vs workflows
If your steps run back-to-back with no pauses between them, a [workflow](/cloud/building-workflows/build-a-workflow) is more efficient. Workflow blocks share one browser instance with no inter-step startup cost.
Sessions are the right choice when you need:
- **Pauses between steps**: review results, get approval, or wait for external input before continuing
- **Human-in-the-loop**: interact with the browser yourself between automated steps
- **Ad-hoc sequences**: run different tasks one after another without pre-building a workflow
---
## Sessions vs profiles
| | Browser Session | Browser Profile |
|---|----------------|-----------------|
| **What it is** | Live browser instance | Saved snapshot of browser state |
| **Lifetime** | Minutes to hours | Days to months |
| **State** | Current page, cookies, open connections | Cookies, localStorage, session files |
| **Billing** | Charged while open | No cost when not in use |
| **Best for** | Back-to-back tasks, human-in-the-loop | Repeated logins, scheduled workflows |
<Tip>
Use a session when you need a live browser right now. Use a [profile](/cloud/browser-management/browser-profiles) when you want to save login state and reuse it later.
</Tip>
---
## What's next
<CardGroup cols={2}>
<Card
title="Browser Profiles"
icon="floppy-disk"
href="/cloud/browser-management/browser-profiles"
>
Save login state and reuse it across sessions
</Card>
<Card
title="Browser Sessions (API)"
icon="code"
href="/developers/optimization/browser-sessions"
>
Create and manage sessions programmatically
</Card>
</CardGroup>
@@ -0,0 +1,164 @@
---
title: Workflow Parameters
subtitle: Pass dynamic values into your workflows at runtime
description: Define input and credential parameters in the Skyvern Cloud UI workflow editor to pass dynamic values like URLs, JSON data, and vault credentials into workflows at runtime.
slug: cloud/add-parameters
keywords:
- input parameter
- credential parameter
- runtime value
- Bitwarden
- 1Password
- Azure Key Vault
- JSON
---
Parameters let you create reusable workflows that accept different input values each time they run. Instead of hardcoding a URL or search term into a block, you reference a parameter and fill in the value when you run the workflow.
This page covers parameters in the Cloud UI workflow editor. If you're building automations in code, parameters are just function arguments. See [Browser Automation](/developers/browser-automations/overview) for the code-first approach.
---
## Opening the parameters panel
In the [workflow editor](/cloud/building-workflows/build-a-workflow), click the **Parameters** button in the header bar. A panel appears below the header showing all defined parameters and controls to add new ones.
<img src="/images/cloud/parameters-panel-open.png" alt="Parameters panel" />
---
## Adding a parameter
Click **Add Parameter** in the panel. Two types are available:
| Type | Use for |
|------|---------|
| **Input Parameter** | Values the user provides when running the workflow (text, numbers, JSON, etc.) |
| **Credential Parameter** | Securely inject login credentials from a vault (Bitwarden, 1Password, Azure, AWS, or Skyvern) |
Each parameter requires a unique **key**. This is the name you use to reference it in blocks. Keys cannot contain spaces and cannot use [reserved names](#reserved-variables).
You can also add an optional **description** (shown as help text when running) and a **default value**.
---
## Parameter value types
Input parameters support these value types:
| Type | Input control | Example |
|------|---------------|---------|
| **String** | Text field | `"https://example.com"` |
| **Integer** | Number field | `10` |
| **Float** | Number field | `19.99` |
| **Boolean** | Toggle switch | `true` |
| **JSON** | Code editor | `{"key": "value"}` |
| **File URL** | Text field (paste a URL) | `"https://example.com/data.csv"` |
| **Credential ID** | Dropdown selector (shown at runtime) | Selected from stored credentials |
---
## Referencing parameters in blocks
Use Jinja2 double-brace syntax to reference parameters inside block fields like prompts, URLs, and data schemas.
**Basic reference:**
```
{{ url }}
```
**Nested field access** (for JSON parameters):
```
{{ config.search_term }}
```
**Convert to JSON string:**
```
{{ my_data | tojson }}
```
**Example in a Navigation block prompt:**
```
Navigate to {{ url }} and search for {{ search_term }}
```
Any block field that accepts text supports parameter references.
---
## Credential parameters
Credential parameters securely inject login credentials into blocks without exposing them in prompts or logs.
| Source | What it provides |
|--------|-----------------|
| **Skyvern Credential** | Username and password stored on the Skyvern Credentials page |
| **Bitwarden Login** | Username, password, and optional TOTP from your Bitwarden vault |
| **Bitwarden Credit Card** | Card number, holder name, expiry, and CVV from Bitwarden |
| **Bitwarden Sensitive Information** | Sensitive data fields from Bitwarden |
| **1Password** | Username, password, card data, or TOTP from 1Password |
| **Azure Key Vault** | Secrets stored in Azure Key Vault |
| **AWS Secret** | Secrets stored in AWS Secrets Manager |
| **Azure Secret** | Secrets stored in Azure Secret |
When you add a credential parameter, you configure the source and connection details (collection ID, vault ID, etc.). At runtime, Skyvern fetches the real credentials from the vault and injects them into the workflow. Credential values are masked in logs and outputs.
---
## Output parameters
Every block automatically produces an **output parameter** containing its results. You can reference a previous block's output in any downstream block.
The syntax uses the block's label (lowercased, spaces replaced with underscores) followed by `_output`:
```
{{ extraction_block_output.extracted_information }}
```
```
{{ login_output.success }}
```
This is how you chain data between blocks. Extract data in one block, then use it in the next.
---
## Reserved variables
These variable names are built-in and cannot be used as parameter keys:
| Variable | Available in | Description |
|----------|-------------|-------------|
| `current_value` | Loop blocks | The current item being iterated |
| `current_item` | Loop blocks | Alias for `current_value` |
| `current_index` | Loop and While Loop blocks | Zero-based index of the current iteration |
| `workflow_run_id` | All blocks | Unique ID of the current run |
| `workflow_id` | All blocks | The workflow's ID |
| `workflow_permanent_id` | All blocks | The workflow's permanent ID |
| `workflow_title` | All blocks | The workflow's title |
**Example in a loop:**
```
Process item {{ current_index }}: {{ current_value.name }}
```
---
## What's next
<CardGroup cols={2}>
<Card
title="Block Reference"
icon="cube"
href="/cloud/building-workflows/configure-blocks"
>
Configuration fields for every block type
</Card>
<Card
title="Run Your Workflow"
icon="play"
href="/cloud/building-workflows/run-a-workflow"
>
Execute workflows and fill in parameter values
</Card>
</CardGroup>
@@ -0,0 +1,327 @@
---
title: Build a Workflow
subtitle: Create multi-step automations with the visual workflow editor
description: Create multi-step browser automations in the Skyvern Cloud UI using the visual workflow editor with blocks for navigation, extraction, loops, conditionals, and email.
slug: cloud/build-a-workflow
keywords:
- workflow editor
- drag and drop
- navigation block
- extract block
- loop block
- action block
- parameter
- visual builder
---
Workflows are multi-step automations built visually in the Cloud UI. You drag blocks onto a canvas, wire them together, configure each one, and run the whole sequence with a click. No code required. Workflows can be versioned, shared across your team, scheduled on a cron, and run with different parameters each time.
If you prefer writing automation code in Python or TypeScript, see [Browser Automation](/developers/browser-automations/overview) in the developer docs. Both approaches handle multi-step work across pages. Workflows are the visual path, browser automations are the code path.
<Info>
**Workflows vs. Browser Automation:** Workflows are defined in this visual editor and run from the Cloud UI (or [triggered from code](/cloud/building-workflows/run-from-code)). Browser automations are written in Python/TypeScript using Page, Agent, and Browser. Choose based on whether your team prefers a visual editor or a code editor.
</Info>
This page explains how workflows work, walks you through building one from scratch, and covers the editor's features.
## How workflows work
A workflow is a sequence of **blocks** that run one after another. Each block does one thing: navigate to a page, extract data, send an email, run custom code, loop, or branch. You connect blocks on a visual canvas, pass data between them, and run the whole chain with one click.
```
[Browser Task] → [Extraction] → [Loop] → [Send Email]
↓ ↓ ↓ ↓
opens the page JSON output per-item digest sent
processing
```
### How data flows between blocks
Every block produces an output. Downstream blocks reference it using the pattern `{{ block_label_output }}`.
For example, an Extraction block labeled `scrape_listings` produces output that later blocks access as `{{ scrape_listings_output }}`. The label is lowercased with spaces replaced by underscores, then `_output` is appended. This is how you chain steps together. One block's output becomes the next block's input.
### Block categories
| Category | What it does | Examples |
|----------|-------------|----------|
| **Browser Automation** | Interact with web pages using AI | Browser Task, Browser Action, Extraction, Login, Go to URL, Print Page |
| **Data and Extraction** | Transform data without a browser | Text Prompt, File Parser |
| **Control Flow** | Branch, loop, validate, or pause | Loop, While Loop, Conditional, AI Validation, Code, Wait |
| **Files** | Download and upload files | File Download, Cloud Storage Upload |
| **Communication** | Send data to external services or humans | Send Email, HTTP Request, Human Interaction |
See [Block Reference](/cloud/building-workflows/configure-blocks) for every block type and its configuration fields.
<Tip>
If your block needs a browser, pick a browser automation block. If it just needs to process data, use Text Prompt or Code. If you need to repeat or branch, use control flow.
</Tip>
---
## Tutorial: Build a job listing tracker
Let's build a real workflow. You'll create an automation that finds the top 5 job listings from Hacker News's monthly "Who is Hiring" thread, summarizes each one, and emails you a digest.
This uses 5 blocks across 3 categories: browser automation, data and extraction, and communication.
<Steps>
<Step title="Create a new workflow">
Go to **Workflows** in the left sidebar and click **Create → Blank Workflow**.
<img src="/images/cloud/create-workflow-dropdown.png" alt="Create workflow dropdown showing Blank Workflow and From Template options" />
The editor opens with an empty canvas showing a single start node. Click the workflow title at the top left and rename it to **HN Job Tracker**.
</Step>
<Step title="Add a Browser Task block">
Hover over the **+** button on the edge below the start node and select **Add Block**. A searchable block library opens on the right. Find and select **Browser Task Block**.
The block appears on the canvas with a configuration panel on the right. Fill in:
| Field | Value |
|-------|-------|
| **Label** | `find_hiring_thread` |
| **URL** | `https://news.ycombinator.com` |
| **Prompt** | `Find and open the latest monthly "Ask HN: Who is hiring?" thread. The task is complete when the thread is open and job listing comments are visible.` |
The Browser Task block uses AI to navigate the page and accomplish the goal described in your prompt. Include your success criteria directly in the prompt so the AI knows when it's done.
<img src="/images/cloud/tutorial-browser-task.png" alt="Browser Task block configured with find_hiring_thread label, URL, and prompt" />
<Accordion title="Why Browser Task instead of Go to URL?">
The URL for the latest hiring thread changes every month. The Browser Task block uses AI to find the right link on the page. Use Go to URL when you know the exact destination URL upfront.
</Accordion>
</Step>
<Step title="Add an Extraction block">
Hover over the **+** on the edge after `find_hiring_thread`, select **Add Block**, then choose **Extraction Block**.
Configure:
| Field | Value |
|-------|-------|
| **Label** | `scrape_listings` |
| **Data Extraction Goal** | `Extract the top 5 job listings. For each listing, get the company name, role title, and a brief description of the position.` |
Now enable the **Data Schema** checkbox to reveal the JSON editor, and paste:
```json
{
"type": "object",
"properties": {
"listings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"company": { "type": "string" },
"role": { "type": "string" },
"description": { "type": "string" }
}
}
}
}
}
```
The schema tells Skyvern exactly what structure to return. Without it, the AI picks its own format. You can also click **Generate with AI** next to the schema field to have Skyvern suggest a schema based on your extraction goal.
<img src="/images/cloud/tutorial-extraction.png" alt="Extraction block configured with scrape_listings label, extraction goal, Data Schema checkbox enabled, and JSON schema" />
<Tip>
Label your blocks descriptively. The label determines the output variable name. `scrape_listings` means downstream blocks reference its data as `{{ scrape_listings_output }}`.
</Tip>
</Step>
<Step title="Add a Loop with a Text Prompt inside">
Hover over the **+** after `scrape_listings`, select **Add Block**, then choose **Loop Block**.
Configure the loop:
| Field | Value |
|-------|-------|
| **Label** | `process_each` |
| **Loop Value** | `{{ scrape_listings_output.listings }}` |
This iterates over the 5 listings extracted in the previous step. Now add a block *inside* the loop. Hover over the **+** inside the loop body, select **Add Block**, and choose **Text Prompt Block**.
Configure the Text Prompt:
| Field | Value |
|-------|-------|
| **Label** | `summarize` |
| **Prompt** | `Summarize this job listing in one sentence. Company: {{ current_value.company }}, Role: {{ current_value.role }}, Description: {{ current_value.description }}` |
Enable the **Data Schema** checkbox and paste:
```json
{
"type": "object",
"properties": {
"summary": { "type": "string" }
}
}
```
The Text Prompt block sends text to the LLM without opening a browser. It processes data only. Each iteration produces a one-line summary of that job listing.
<img src="/images/cloud/tutorial-loop-text-prompt.png" alt="Loop block with process_each label containing a summarize Text Prompt block inside" />
<Accordion title="What are current_value and current_index?">
Inside a loop, two reserved variables are available:
- `{{ current_value }}`: the current item from the list being iterated
- `{{ current_index }}`: the item's position, starting from 0
These only exist inside loop blocks. In this example, `{{ current_value.company }}` gives you the company name for the current listing.
</Accordion>
</Step>
<Step title="Add a Send Email block">
Hover over the **+** on the edge *after* the loop (back on the main flow, not inside it), select **Add Block**, then choose **Send Email Block**.
Configure:
| Field | Value |
|-------|-------|
| **Label** | `send_digest` |
| **Recipients** | Your email address |
| **Subject** | `HN Job Digest - Top 5 Listings` |
| **Body** | `Here are today's top job listings from Hacker News:\n\n{{ process_each_output }}` |
The `{{ process_each_output }}` reference pulls in the collected summaries from every loop iteration.
</Step>
<Step title="Save and run">
<Warning>
Workflows are **not** auto-saved. Click the **Save** button (disk icon) in the header bar before navigating away or you'll lose your work.
</Warning>
Click **Save**, then click **Run** in the top right. A parameters page opens where you can review and confirm the workflow's settings. Click **Run Workflow** to start execution.
The [live execution view](/cloud/getting-started/monitor-a-run) opens. Watch as Skyvern navigates Hacker News, extracts listings, summarizes each one, and sends your email.
</Step>
</Steps>
### What you built
```mermaid
flowchart LR
A["find_hiring_thread<br/>Browser Task"] --> B["scrape_listings<br/>Extraction"]
B --> C["process_each<br/>Loop"]
C --> D["summarize<br/>Text Prompt"]
D --> E["send_digest<br/>Send Email"]
```
Five blocks, three categories, zero code. You can now re-run this workflow anytime, tweak the extraction schema to pull different fields, swap the email for an HTTP Request to post to Slack, or add a Conditional block to only email when listings match certain criteria.
---
## Editor reference
### Layout
<img src="/images/cloud/workflow-editor-overview.png" alt="Workflow editor overview" />
| Area | What it shows |
|------|---------------|
| **Header bar** (top) | Workflow title (click to rename), Parameters button, Save button, Template toggle, History button, Run button |
| **Canvas** (center) | Visual graph of blocks connected in sequence. Zoom with the scroll wheel, pan by dragging the background. |
| **Configuration panel** (right) | Opens when you click a block. Shows that block's settings form. |
### Adding blocks
Hover over the **+** button on any edge (the connecting line between blocks) to reveal the menu. Select **Add Block** to open the block library, a searchable list of all available block types. Click a block to insert it at that position.
The menu also offers **Record Browser** (record actions in a live browser to generate blocks) and **Upload SOP** (upload a PDF procedure to auto-generate a workflow).
When you create a blank workflow, hover over the **+** on the start edge to add your first block.
<img src="/images/cloud/add-block-panel.png" alt="Add block panel" />
### Configuring blocks
Click any block on the canvas to open its configuration panel on the right. Each block has a **Label** field (which determines its output variable name) and block-specific settings. Browser-based blocks share additional fields like URL, Engine, and Max Retries.
See [Block Reference](/cloud/building-workflows/configure-blocks) for the full list of fields on each block type.
### Connecting and reordering blocks
Blocks auto-connect when you insert them via the **+** button. They execute top to bottom in the order shown on the canvas.
**Conditional blocks** create branches. Each branch connects to a different sequence of blocks and merges back at a common point.
**Loop blocks** contain child blocks that repeat for each item in the loop's list. **While Loop blocks** contain child blocks that repeat while their condition remains true.
To reorder blocks, delete the block you want to move and re-add it at the desired position using the **+** button.
### Deleting blocks
Click the **three-dot menu** on a block's header and select **Delete Block**. Downstream blocks reconnect to the previous block automatically.
### Saving
<Warning>
Workflows are **not** auto-saved. Click the **Save** button (disk icon) in the header bar to persist your changes. The editor warns you if you try to navigate away with unsaved work.
</Warning>
The **Run** button also saves before starting execution.
### Header bar actions
| Button | Description |
|--------|-------------|
| **Save** (disk icon) | Save the current workflow definition |
| **Template** (bookmark icon) | Toggle whether this workflow is saved as an organization template |
| **History** (clock icon) | View past runs of this workflow |
| **Schedule** (clock icon) | Create or manage recurring schedules for this workflow (see [Create a Schedule](/cloud/building-workflows/scheduling)) |
| **Parameters** | Open the parameters panel (see [Workflow Parameters](/cloud/building-workflows/add-parameters)) |
| **Run** (play icon) | Save and start a new execution (see [Running Workflows](/cloud/building-workflows/run-a-workflow)) |
---
## What's next
<CardGroup cols={3}>
<Card
title="Block Reference"
icon="cube"
href="/cloud/building-workflows/configure-blocks"
>
Configuration fields for every block type
</Card>
<Card
title="Add Parameters"
icon="sliders"
href="/cloud/building-workflows/add-parameters"
>
Pass dynamic values into your workflows
</Card>
<Card
title="Run Your Workflow"
icon="play"
href="/cloud/building-workflows/run-a-workflow"
>
Execute workflows and track results
</Card>
<Card
title="Schedule This Workflow"
icon="calendar"
href="/cloud/building-workflows/scheduling"
>
Set up recurring cron-based execution
</Card>
</CardGroup>
@@ -0,0 +1,459 @@
---
title: Block Types and Configuration
subtitle: Reference for every block available in the workflow editor
description: Reference guide for every workflow block type in the Skyvern Cloud UI, including Browser Task, Extraction, Login, Loop, While Loop, Conditional, Code, HTTP Request, and more.
slug: cloud/configure-blocks
keywords:
- navigation block
- action block
- extract block
- loop block
- while loop block
- code block
- HTTP request block
- text prompt block
- login block
- validation block
- file download block
- conditional block
---
Workflows are built from blocks. Each block performs one specific operation: navigating a page, extracting data, making an API call, or branching logic. This page covers every block type available in the Cloud UI [workflow editor](/cloud/building-workflows/build-a-workflow), grouped by category.
If you're writing automations in code instead, the equivalent operations are Page and Agent methods. See the [Actions Reference](/developers/browser-automations/actions-reference) for the code-first counterparts to these blocks.
<Frame caption="To add a block in your workflow, click the **+** button, click on Add block, then select the block type from the menu.">
<img src="/images/cloud/add-block-ui.png" alt="how to add a block to a workflow in Skyvern" />
</Frame>
## Quick reference
| Category | Blocks |
|----------|--------|
| [Browser Automation](#browser-automation) | Browser Task, Browser Action, Extraction, Login, Go to URL, Print Page |
| [Data and Extraction](#data-and-extraction) | Text Prompt, File Parser |
| [Control Flow](#control-flow) | Loop, While Loop, Conditional, AI Validation, Code, Wait |
| [Files](#files) | File Download, Cloud Storage Upload |
| [Communication](#communication) | Send Email, HTTP Request, Human Interaction |
---
## Common fields
These fields appear on most blocks:
| Field | Description |
|-------|-------------|
| **Label** | Display name on the canvas. Also determines how downstream blocks reference this block's output (`{{ label_output }}`). |
| **Continue on Failure** | Allow the workflow to continue if this block fails |
| **Next Loop on Failure** | Only inside loops. Skip to the next iteration on failure. |
| **Model** | Override the default LLM model for this block (Advanced Settings on most blocks) |
Browser-based blocks (Browser Task, Browser Action, Extraction, Login, File Download) share these additional fields:
| Field | Description |
|-------|-------------|
| **URL** | Starting URL. Leave blank to continue from the previous block's page. |
| **Engine** | AI engine: Skyvern 1.0 or Skyvern 2.0 |
| **Max Steps Override** | Cap the number of AI reasoning steps |
| **Disable Cache** | Skip cached script execution |
| **TOTP Identifier** | Link TOTP credentials for 2FA handling |
| **TOTP Verification URL** | Endpoint for fetching TOTP codes |
| **Error Code Mapping** | Map error conditions to custom error codes (JSON) |
---
## Browser Automation
### Browser Task
The primary block for browser automation. Accepts a natural-language prompt and autonomously navigates the browser to accomplish the goal.
The block has two engine modes, selected via the **Engine** dropdown. The fields shown change depending on which engine you choose.
**Skyvern 2.0** (recommended):
| Field | Type | Description |
|-------|------|-------------|
| **URL** | text | Starting URL (optional) |
| **Prompt** | text | Natural language instructions for the AI |
| **Max Steps** | number | Maximum AI steps |
| **Disable Cache** | boolean | Skip cached script execution |
**Skyvern 1.0:**
| Field | Type | Description |
|-------|------|-------------|
| **URL** | text | Starting URL (optional) |
| **Prompt** | text | Natural language instructions for the AI |
Additional fields in **Advanced Settings** (Skyvern 1.0 only):
| Field | Type | Description |
|-------|------|-------------|
| **Complete if...** | text | Condition that signals the block is done |
| **Include Action History in Verification** | boolean | Include prior actions when verifying completion |
| **Complete on Download** | switch | Mark the block as complete when a file download occurs |
| **File Name** | text | Custom filename for downloaded files |
*Plus [common browser fields](#common-fields).*
<Frame>
<img width="400" src="/images/cloud/br_task_block.png" alt="Browser Task block configuration with URL and prompt fields" />
</Frame>
<Tip>
Browser Task is the recommended block for most browser automation. Use it for anything from form filling to multi-page navigation. Include your success criteria directly in the prompt so the AI knows when it's done.
</Tip>
### Browser Action
Execute a single browser action. Best for precise, one-step operations like clicking a specific button or entering text in a field.
| Field | Type | Description |
|-------|------|-------------|
| **URL** | text | Starting URL (optional) |
| **Action Instruction** | text | Specify the single action to perform |
Additional fields in **Advanced Settings:**
| Field | Type | Description |
|-------|------|-------------|
| **Complete on Download** | switch | Mark the block as complete when a file download occurs |
| **File Name** | text | Custom filename for downloaded files |
*Plus [common browser fields](#common-fields).*
### Extraction
Extract structured data from the current page using AI.
| Field | Type | Description |
|-------|------|-------------|
| **Data Extraction Goal** | text | What data to extract |
| **Data Schema** | JSON | [JSON Schema](https://json-schema.org/) defining the output format. Enable the checkbox to reveal the editor. Click **Generate with AI** to auto-suggest a schema from your extraction goal. |
*Plus [common browser fields](#common-fields).*
<Frame>
<img width="400" src="/images/cloud/extract_block.png" alt="Extraction block configuration with Data Extraction Goal and Data Schema fields" />
</Frame>
### Login
Authenticate to a website using stored credentials. Pre-filled with a default login goal that handles common login flows including 2FA.
| Field | Type | Description |
|-------|------|-------------|
| **URL** | text | Login page URL |
| **Login Goal** | text | Login instructions (pre-filled with a comprehensive default) |
| **Credential** | selector | Select stored credentials for authentication |
Additional fields in **Advanced Settings:**
| Field | Type | Description |
|-------|------|-------------|
| **Complete if...** | text | How to know login succeeded |
*Plus [common browser fields](#common-fields).*
<Frame>
<img width="400" src="/images/cloud/login_block.png" alt="Login block configuration with URL, Login Goal, and Credential fields" />
</Frame>
### Go to URL
Navigate the browser directly to a specific URL without AI interaction.
| Field | Type | Description |
|-------|------|-------------|
| **URL** | text | **(Required)** The URL to navigate to. Supports [parameter references](/cloud/building-workflows/add-parameters#referencing-parameters-in-blocks). |
<Frame>
<img width="400" src="/images/cloud/url_block.png" alt="Go to URL block configuration with URL field" />
</Frame>
### Print Page
Print the current browser page to a PDF file. The PDF is saved as a downloadable artifact.
| Field | Type | Description |
|-------|------|-------------|
| **Page Format** | select | Paper size: A4, Letter, Legal, or Tabloid |
| **Print Background** | boolean | Include CSS background colors and images in the PDF |
| **Headers & Footers** | boolean | Add date, title, URL, and page numbers to the PDF |
Additional fields in **Advanced Settings:**
| Field | Type | Description |
|-------|------|-------------|
| **Custom Filename** | text | Custom name for the generated PDF |
| **Landscape** | boolean | Use landscape orientation |
<Frame>
<img width="400" src="/images/cloud/print_block.png" alt="Print Page block configuration with page format, print background, and headers & footers options" />
</Frame>
---
## Data and Extraction
### Text Prompt
Send text to the LLM for processing without browser interaction. Useful for summarizing, transforming, or analyzing data between browser steps.
| Field | Type | Description |
|-------|------|-------------|
| **Prompt** | text | The text prompt to send to the LLM |
| **Model** | selector | Which LLM model to use |
| **Data Schema** | JSON | Expected output structure. Enable the checkbox to reveal the editor. Click **Generate with AI** to auto-suggest a schema. |
<Frame>
<img width="400" src="/images/cloud/text_block.png" alt="Text Prompt block configuration with Prompt, Model, and Data Schema fields" />
</Frame>
### File Parser
Parse PDFs, CSVs, Excel files, and images to extract structured data.
| Field | Type | Description |
|-------|------|-------------|
| **File URL** | text | URL or parameter reference to the file |
| **Data Schema** | JSON | Schema for the extracted output. Enable the checkbox to reveal the editor. |
| **Model** | selector | Which LLM model to use |
<Frame>
<img width="400" src="/images/cloud/file_parse_block.png" alt="File Parser block configuration with File URL, Data Schema, and Model fields" />
</Frame>
---
## Control Flow
### Loop
Repeat a sequence of blocks for each item in a list. Child blocks are placed inside the loop on the canvas.
| Field | Type | Description |
|-------|------|-------------|
| **Loop Value** | text | The list to iterate over. Use a parameter reference (e.g., `{{ my_list }}`) or a natural language description (e.g., "Extract links of the top 5 posts") which triggers automatic extraction. |
| **Continue if Empty** | boolean | Mark the loop as complete if the list is empty |
Inside loop blocks, use these [reserved variables](/cloud/building-workflows/add-parameters#reserved-variables):
- `{{ current_value }}`: the current item
- `{{ current_index }}`: the iteration number (0-based)
<Frame>
<img width="400" src="/images/cloud/block-loop-config.png" alt="Loop block configuration" />
</Frame>
Use Loop when the item list is already known before the loop starts, such as rows extracted from a table, files uploaded by a user, or URLs passed as workflow parameters.
### While Loop
Repeat a sequence of blocks while a condition remains true. Child blocks are placed inside the loop on the canvas.
| Field | Type | Description |
|-------|------|-------------|
| **Condition** | expression | Jinja2 template or natural-language prompt evaluated before each iteration |
Inside while-loop blocks, use these [reserved variables](/cloud/building-workflows/add-parameters#reserved-variables):
- `{{ current_index }}`: the iteration number (0-based)
Use While Loop for flows where the number of iterations is discovered during the run, such as pagination, polling, or retrying until a recoverable page state clears. For pagination, a common pattern is to extract a `has_next_page` boolean inside the loop, click Next, and let the next condition check decide whether to continue.
### Conditional
Branch the workflow based on conditions. The UI shows branches as tabs (A, B, C, etc.). Each branch has an expression that determines when it executes. Expressions can be Jinja2 templates or natural language prompts.
| Field | Type | Description |
|-------|------|-------------|
| **Branches** | tabs | One or more conditions. Each branch has an **Expression** field. Click **+** to add branches. |
| **Else branch** | auto | Automatically added. Executes when no other condition matches. |
**Example Jinja2 expression:**
```
{{ extraction_output.price > 100 }}
```
<Frame>
<img width="400" src="/images/cloud/conditional_block.png" alt="Conditional block configuration with branch expressions" />
</Frame>
### AI Validation
Assert conditions using AI and halt the workflow on failure. Useful for checking that a previous block produced expected results before continuing.
| Field | Type | Description |
|-------|------|-------------|
| **Complete if...** | text | Condition that means validation passed |
| **Terminate if...** | text | Condition that means validation failed |
Additional fields in **Advanced Settings:**
| Field | Type | Description |
|-------|------|-------------|
| **Error Code Mapping** | JSON | Custom error codes for failure reasons |
| **Input Parameters** | select | Parameters to evaluate |
<Frame>
<img width="400" src="/images/cloud/ai_val_block.png" alt="AI Validation block configuration with Complete if and Terminate if fields" />
</Frame>
### Code
Execute custom Python code. Input parameters are available as global variables. Top-level variables in your code become the block's output.
| Field | Type | Description |
|-------|------|-------------|
| **Code** | code editor | Python code to execute |
| **Input Parameters** | select | Parameters available as globals in the code |
<Frame>
<img width="400" src="/images/cloud/code_block.png" alt="Code block configuration with Python code editor and Input Parameters field" />
</Frame>
### Wait
Pause workflow execution for a specified duration.
| Field | Type | Description |
|-------|------|-------------|
| **Wait in Seconds** | number | Seconds to wait (0–300) |
<Frame>
<img width="400" src="/images/cloud/wait_block.png" alt="Wait block configuration with Wait in Seconds field" />
</Frame>
---
## Files
### File Download
Navigate the browser to download a file.
| Field | Type | Description |
|-------|------|-------------|
| **URL** | text | Starting URL (optional) |
| **Download Goal** | text | Instructions for finding and downloading the file |
| **Download Timeout (sec)** | number | Seconds to wait for the download to complete |
Additional fields in **Advanced Settings:**
| Field | Type | Description |
|-------|------|-------------|
| **File Name** | text | Custom filename for the download |
*Plus [common browser fields](#common-fields).*
<Frame>
<img width="400" src="/images/cloud/download_block.png" alt="File Download block configuration with URL, Download Goal, and Download Timeout fields" />
</Frame>
### Cloud Storage Upload
Upload downloaded files to S3 or Azure Blob Storage.
| Field | Type | Description |
|-------|------|-------------|
| **Storage Type** | select | `Amazon S3` or `Azure Blob Storage` |
| **Folder Path** | text | Upload path/prefix (optional) |
<Accordion title="S3 fields">
| Field | Description |
|-------|-------------|
| **S3 Bucket** | Bucket name |
| **AWS Access Key ID** | AWS credential |
| **AWS Secret Access Key** | AWS credential |
| **Region Name** | AWS region |
</Accordion>
<Accordion title="Azure fields">
| Field | Description |
|-------|-------------|
| **Storage Account Name** | Storage account name |
| **Storage Account Key** | Storage account key |
| **Blob Container Name** | Container name |
</Accordion>
<Frame>
<img width="400" src="/images/cloud/cloud_block.png" alt="Cloud Storage Upload block configuration with Storage Type and Folder Path fields" />
</Frame>
---
## Communication
### Send Email
Send an email notification, optionally with file attachments from previous blocks.
| Field | Type | Description |
|-------|------|-------------|
| **Recipients** | text | Comma-separated email addresses |
| **Subject** | text | Email subject line |
| **Body** | text | Email body. Supports [parameter references](/cloud/building-workflows/add-parameters#referencing-parameters-in-blocks). |
| **File Attachments** | text | Path to files to attach |
<Frame>
<img width="400" src="/images/cloud/email_block.png" alt="Send Email block configuration with Recipients, Subject, Body, and File Attachments fields" />
</Frame>
### HTTP Request
Make an API call to an external service. Click **Import cURL** in the block header to populate fields from a cURL command.
| Field | Type | Description |
|-------|------|-------------|
| **Method** | select | GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS |
| **URL** | text | Request URL. Supports parameter references. |
| **Headers** | JSON | HTTP headers. Use **Quick Headers** to add common headers. |
| **Body** | JSON | Request body (POST/PUT/PATCH only) |
| **Files** | JSON | File uploads (POST/PUT/PATCH only) |
Additional fields in **Advanced Settings:**
| Field | Type | Description |
|-------|------|-------------|
| **Timeout** | number | Request timeout in seconds (1–300, default: 30) |
| **Follow Redirects** | boolean | Automatically follow HTTP redirects (default: true) |
| **Continue on Failure** | boolean | Continue workflow if the request fails |
| **Save Response as File** | boolean | Save the response body as a downloadable file |
| **Download Filename** | text | Filename for the saved response (shown when Save Response as File is enabled) |
<Frame>
<img width="400" src="/images/cloud/http_block.png" alt="HTTP Request block configuration with Method, URL, Headers, and Body fields" />
</Frame>
### Human Interaction
Pause the workflow and request human input. Optionally sends an email notification to reviewers.
| Field | Type | Description |
|-------|------|-------------|
| **Instructions For Human** | text | Instructions displayed to the reviewer |
| **Timeout (minutes)** | number | Minutes to wait before auto-continuing (default: 120 minutes / 2 hours) |
**Email notification fields:**
| Field | Type | Description |
|-------|------|-------------|
| **Recipients** | text | Email addresses to notify (comma-separated) |
| **Subject** | text | Notification email subject |
| **Body** | text | Notification email body |
Additional fields in **Advanced Settings:**
| Field | Type | Description |
|-------|------|-------------|
| **Positive Button Label** | text | Label for the approval action (default: "Approve") |
| **Negative Button Label** | text | Label for the rejection action (default: "Reject") |
<Frame>
<img width="400" src="/images/cloud/human_block.png" alt="Human Interaction block configuration with Instructions For Human and Timeout fields" />
</Frame>
@@ -0,0 +1,117 @@
---
title: Managing Workflows
subtitle: Create, organize, clone, import, and export reusable automations
description: Organize, clone, import, export, and delete workflows in the Skyvern Cloud UI, including folder management and template sharing across your organization.
slug: cloud/manage-workflows
keywords:
- clone
- import
- export
- delete
- folder
- template
- organize
---
Workflows are multi-step automations built visually in the Cloud UI. Once you've [built a workflow](/cloud/building-workflows/build-a-workflow), the **Workflows** page is where you organize, share, and manage them. Each workflow is a reusable sequence of blocks that you can run with different inputs each time.
If you're building automations in code instead, see the [Browser Automation](/developers/browser-automations/overview) developer docs.
Click **Workflows** in the left sidebar to open it.
<img src="/images/cloud/workflows-page-overview.png" alt="Workflows page overview" />
---
## The workflows table
The table lists all workflows in your organization with the following columns:
| Column | Description |
|--------|-------------|
| **ID** | Unique workflow identifier |
| **Title** | Display name (click to open in the editor) |
| **Folder** | Folder assignment, if any |
| **Created At** | When the workflow was created |
| **Actions** | Inline buttons and three-dot menu |
Each row also has inline action buttons: folder assignment, parameter toggle, open in editor (pencil icon), run (play icon), and a three-dot menu for additional actions.
---
## Organizing with folders
The top of the page shows your recent folders as cards. Use folders to group related workflows.
- Click **+ New folder** to create one
- Click a folder card to filter the table to that folder's workflows
- Assign a workflow to a folder using the folder icon in the table row
- Click **View all** to see all folders when you have more than five
<img src="/images/cloud/workflow-folders.png" alt="Workflow folders" />
---
## Searching and filtering
Use the search bar above the table to filter workflows by title or parameter. The results highlight matching text and auto-expand parameter rows when a parameter matches.
The items-per-page selector at the bottom lets you choose 5, 10, 20, or 50 rows per page.
---
## Workflow actions
Click the **three-dot menu** on any workflow row to access these actions:
| Action | What it does |
|--------|-------------|
| **Clone Workflow** | Creates a copy named "Copy of ..." with the original title |
| **Save as Template** | Makes this workflow available in the organization template gallery. A bookmark icon appears next to the title. |
| **Remove from Templates** | Removes the workflow from the template gallery (appears instead of "Save as Template" for templates) |
| **Export as... > YAML** | Downloads the workflow definition as a `.yaml` file |
| **Export as... > JSON** | Downloads the workflow definition as a `.json` file |
| **Delete Workflow** | Opens a confirmation dialog, then permanently deletes the workflow |
<img src="/images/cloud/workflow-actions-menu.png" alt="Workflow actions menu" />
<Warning>
Deleting a workflow is permanent. Clone it first if you want to keep a backup.
</Warning>
---
## Importing workflows
Click the **Import** button to upload workflow files.
| Format | Behavior |
|--------|----------|
| `.yaml` / `.yml` | Parsed and created as a new workflow |
| `.json` | Converted to YAML internally, then created |
| `.pdf` | Sent to the AI to generate a workflow from a Standard Operating Procedure document |
<Tip>
Upload a PDF of your Standard Operating Procedure and Skyvern generates a workflow from it automatically.
</Tip>
---
## What's next
<CardGroup cols={2}>
<Card
title="Open the Editor"
icon="pen-to-square"
href="/cloud/building-workflows/build-a-workflow"
>
Build automations visually with the workflow editor
</Card>
<Card
title="Add Parameters"
icon="sliders"
href="/cloud/building-workflows/add-parameters"
>
Make workflows reusable with dynamic input values
</Card>
</CardGroup>
@@ -0,0 +1,137 @@
---
title: Running Workflows
subtitle: Execute workflows, fill parameters, and track status
description: Execute workflows from the Skyvern Cloud UI editor or workflows list, fill in runtime parameters, configure run settings like proxy and webhook, and monitor live execution.
slug: cloud/run-a-workflow
keywords:
- execute
- fill parameters
- run settings
- proxy
- webhook
- cancel
- retry
- live execution
---
Once you've built and saved a workflow in the Cloud UI, you can run it from the editor or the workflows list. Each run creates an independent execution with its own status, logs, and output.
You can also trigger workflows programmatically from your code. See [Run from Code](/cloud/building-workflows/run-from-code) for the SDK and API approach.
## Starting a run
Two ways to start:
1. **From the editor**: Click the **Run** button (play icon) in the header bar. The editor saves your workflow first.
<img src="/images/cloud/run-wf-1.png" alt="Workflow editor with the Run button highlighted in the header bar" />
2. **From the workflows list**: Click the **play icon** on the workflow's row.
<img src="/images/cloud/run-wf-2.png" alt="Workflows list page with play icon to start a run from the list" />
Both take you to the parameters page where you fill in runtime values before the run starts.
## Filling in parameters
The parameters page shows all [workflow parameters](/cloud/building-workflows/add-parameters) defined in the editor. Fill in a value for each one, or leave them at their defaults. Parameters without defaults must be filled in before running.
<img src="/images/cloud/run-wf-3.png" alt="Parameters page showing input fields and settings before starting a workflow run" />
## Run settings
Below the parameters, you can configure settings for this specific run:
| Setting | Description |
|---------|-------------|
| **Proxy Location** | Route browser traffic through a proxy in a specific country. Default: US Residential. |
| **Webhook Callback URL** | URL that receives a POST request when the run completes |
| **Max Screenshot Scrolls** | Override screenshot scroll depth for this run |
| **Extra HTTP Headers** | Custom headers included in all browser requests (JSON) |
| **CDP Address** | Connect to your own browser for local development |
<Frame>
<img src="/images/cloud/run-wf-6.png" alt="Run settings showing webhook callback URL, proxy location, and AI fallback options" />
</Frame>
<br/>
<Frame>
<img src="/images/cloud/run-wf-7.png" alt="Advanced run settings showing browser session ID, browser address, extra HTTP headers, and max screenshot scrolls" />
</Frame>
---
## Monitoring a run
After clicking **Run**, you're taken to the live execution view, the same interface described in [Watching Live Execution](/cloud/getting-started/monitor-a-run).
For workflows, the left panel also shows a **block timeline**: a list of all blocks in the workflow. Completed blocks show a checkmark. The currently executing block is highlighted.
<img src="/images/cloud/workflow-run-timeline.png" alt="Workflow run block timeline" />
---
## Run statuses
| Status | Description |
|--------|-------------|
| `created` | Run initialized |
| `queued` | Waiting for an available browser |
| `running` | Blocks are executing |
| `completed` | All blocks finished successfully |
| `failed` | A block failed and the workflow stopped |
| `canceled` | You canceled the run |
| `timed_out` | The run exceeded its time limit |
| `terminated` | The run was terminated by the system |
---
## Viewing results
After a run completes, open it from **Runs** in the sidebar. The run detail page shows:
- **Block-by-block results**: Each block's output, status, and execution time
- **Recording**: Full video replay of the browser session
- **Parameters**: The values you submitted for this run
<img src="/images/cloud/run-wf-8.png" alt="Completed workflow run showing extracted data, output tabs, and block timeline" />
See [Reviewing results](/cloud/getting-started/monitor-a-run#reviewing-results) for details on the Actions, Recording, Parameters, and Diagnostics tabs.
---
## Canceling a run
Click the **Cancel** button during execution. A confirmation dialog appears. The run moves to `canceled` status and any configured webhook fires.
---
## Run history
Access past runs from two places:
1. **Runs** in the left sidebar: shows all runs across all workflows
<img src="/images/cloud/run-wf-4.png" alt="Run History page in the sidebar showing all past runs with status and duration" />
2. Go to the **History** button (clock icon) in the workflow editor: shows runs for this specific workflow
<img src="/images/cloud/run-wf-5.png" alt="Past Runs view for a specific workflow showing run statuses and timestamps" />
---
## What's next
<CardGroup cols={2}>
<Card
title="Build a Workflow"
icon="pen-to-square"
href="/cloud/building-workflows/build-a-workflow"
>
Create and edit workflows in the visual editor
</Card>
<Card
title="Block Reference"
icon="cube"
href="/cloud/building-workflows/configure-blocks"
>
Configuration fields for every block type
</Card>
</CardGroup>
@@ -0,0 +1,397 @@
---
title: Run from Code
subtitle: Execute and schedule workflows via the API or SDK
description: Run workflows programmatically, pass parameters, poll for results, and create recurring schedules using the Python SDK, TypeScript SDK, or REST API.
slug: cloud/building-workflows/run-from-code
keywords:
- run_workflow
- get_run
- get_workflows
- schedule
- cron
- polling
- webhook
- SDK
- API
---
If you've built a workflow in the Cloud UI and want to trigger it from your codebase, this page shows how. You can run workflows on demand, poll for results, and set up recurring schedules using the Python SDK, TypeScript SDK, or REST API.
This is for workflows defined in the visual editor. If you're writing your entire automation in code (no workflow editor involved), see [Browser Automation](/developers/browser-automations/overview) instead.
---
## Run a workflow
Pass values for the workflow's input parameters. The call returns immediately with a `run_id` -- the workflow runs asynchronously in the background.
<CodeGroup>
```python Python
import os
import asyncio
from skyvern import Skyvern
async def main():
client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
run = await client.run_workflow(
workflow_id="wpid_123456789",
parameters={
"resume": "https://example.com/resume.pdf",
"job_url": "https://jobs.lever.co/company/position"
}
)
print(f"Run ID: {run.run_id}")
asyncio.run(main())
```
```typescript TypeScript
import { SkyvernClient } from "@skyvern/client";
async function main() {
const client = new SkyvernClient({
apiKey: process.env.SKYVERN_API_KEY,
});
const run = await client.runWorkflow({
body: {
workflow_id: "wpid_123456789",
parameters: {
resume: "https://example.com/resume.pdf",
job_url: "https://jobs.lever.co/company/position",
},
},
});
console.log(`Run ID: ${run.run_id}`);
}
main();
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "wpid_123456789",
"parameters": {
"resume": "https://example.com/resume.pdf",
"job_url": "https://jobs.lever.co/company/position"
}
}'
```
</CodeGroup>
**Example response:**
```json
{
"run_id": "wr_486305187432193510",
"status": "created"
}
```
### Run parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `workflow_id` | string | Yes | The `workflow_permanent_id` returned when creating the workflow |
| `parameters` | object | No | Values for the workflow's input parameters. Keys must match the `key` field in the workflow's parameter definitions |
| `title` | string | No | Display name for this specific run |
| `proxy_location` | string or object | No | Override the workflow's default proxy location |
| `webhook_url` | string | No | URL to receive a POST request when the workflow completes |
| `browser_session_id` | string | No | Reuse a persistent browser session (prefix `pbs_`) |
| `browser_profile_id` | string | No | Reuse a browser profile with saved cookies and storage (prefix `bp_`) |
---
## Get results
Workflows run asynchronously, so you need to check back for results. You have two options: poll the API, or receive a webhook when the workflow completes.
### Option 1: Polling
Poll `get_run` until the status reaches a terminal state.
<CodeGroup>
```python Python
run_id = run.run_id
while True:
result = await client.get_run(run_id)
if result.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
break
await asyncio.sleep(5)
print(f"Status: {result.status}")
print(f"Output: {result.output}")
```
```typescript TypeScript
const runId = run.run_id;
while (true) {
const result = await client.getRun(runId);
if (["completed", "failed", "terminated", "timed_out", "canceled"].includes(result.status)) {
console.log(`Status: ${result.status}`);
console.log(`Output: ${JSON.stringify(result.output)}`);
break;
}
await new Promise((resolve) => setTimeout(resolve, 5000));
}
```
```bash cURL
#!/bin/bash
RUN_ID="wr_486305187432193510"
while true; do
RESPONSE=$(curl -s -X GET "https://api.skyvern.com/v1/runs/$RUN_ID" \
-H "x-api-key: $SKYVERN_API_KEY")
STATUS=$(echo "$RESPONSE" | jq -r '.status')
echo "Status: $STATUS"
if [[ "$STATUS" == "completed" || "$STATUS" == "failed" || "$STATUS" == "terminated" || "$STATUS" == "timed_out" || "$STATUS" == "canceled" ]]; then
echo "$RESPONSE" | jq '.output'
break
fi
sleep 5
done
```
</CodeGroup>
### Option 2: Webhooks
Pass a `webhook_url` when running the workflow. Skyvern sends a POST request to your URL when the workflow reaches a terminal state.
<CodeGroup>
```python Python
run = await client.run_workflow(
workflow_id="wpid_123456789",
parameters={
"resume": "https://example.com/resume.pdf",
"job_url": "https://jobs.lever.co/company/position"
},
webhook_url="https://your-server.com/webhook"
)
```
```typescript TypeScript
const run = await client.runWorkflow({
body: {
workflow_id: "wpid_123456789",
parameters: {
resume: "https://example.com/resume.pdf",
job_url: "https://jobs.lever.co/company/position",
},
webhook_url: "https://your-server.com/webhook",
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "wpid_123456789",
"parameters": {
"resume": "https://example.com/resume.pdf",
"job_url": "https://jobs.lever.co/company/position"
},
"webhook_url": "https://your-server.com/webhook"
}'
```
</CodeGroup>
The webhook payload contains the same data as the polling response. See [Webhooks](/developers/going-to-production/webhooks) for authentication and retry options.
### Response fields
```json
{
"run_id": "wr_486305187432193510",
"run_type": "workflow_run",
"status": "completed",
"output": {
"parse_resume_output": {
"name": "John Smith",
"email": "john@example.com",
"work_experience": [...]
},
"apply_to_job_output": {
"task_id": "tsk_123456",
"status": "completed",
"extracted_information": null
}
},
"screenshot_urls": [
"https://skyvern-artifacts.s3.amazonaws.com/.../screenshot_final.png"
],
"recording_url": "https://skyvern-artifacts.s3.amazonaws.com/.../recording.webm",
"failure_reason": null,
"created_at": "2026-01-20T12:00:00.000000",
"modified_at": "2026-01-20T12:05:00.000000"
}
```
| Field | Type | Description |
|-------|------|-------------|
| `run_id` | string | Unique identifier for this run (format: `wr_*`) |
| `run_type` | string | Always `"workflow_run"` for workflow runs |
| `status` | string | Current status: `created`, `queued`, `running`, `completed`, `failed`, `terminated`, `timed_out`, `canceled` |
| `output` | object | Output from each block, keyed by `{label}_output` |
| `screenshot_urls` | array | Final screenshots from the last blocks |
| `recording_url` | string | Video recording of the browser session |
| `failure_reason` | string \| null | Error description if the run failed |
| `downloaded_files` | array | Files downloaded during the run |
| `app_url` | string \| null | Link to view this run in the Skyvern UI |
| `created_at` | datetime | When the run started |
| `modified_at` | datetime | When the run was last updated |
| `started_at` | datetime \| null | When execution started |
| `finished_at` | datetime \| null | When execution finished |
---
## Schedule a workflow
Schedules let you run any workflow automatically on a recurring basis. Define a cron expression and timezone, and Skyvern triggers the workflow at each interval.
### Create a schedule
<CodeGroup>
```python Python
import os
import asyncio
from skyvern import Skyvern
async def main():
client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
result = await client.agent.create_workflow_schedule(
workflow_permanent_id="wpid_123456789",
cron_expression="0 9 * * 1-5",
timezone="America/New_York",
name="Weekday morning report",
description="Runs the data extraction workflow every weekday at 9 AM ET",
parameters={
"url": "https://example.com/dashboard",
"output_format": "csv"
}
)
print(f"Schedule ID: {result.schedule.workflow_schedule_id}")
asyncio.run(main())
```
```bash cURL
curl -X POST "https://api.skyvern.com/api/v1/workflows/wpid_123456789/schedules" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"cron_expression": "0 9 * * 1-5",
"timezone": "America/New_York",
"name": "Weekday morning report",
"description": "Runs the data extraction workflow every weekday at 9 AM ET",
"parameters": {
"url": "https://example.com/dashboard",
"output_format": "csv"
}
}'
```
</CodeGroup>
**Schedule parameters:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cron_expression` | string | Yes | 5-field cron expression (minimum 5-minute interval) |
| `timezone` | string | Yes | IANA timezone identifier (e.g., `America/New_York`) |
| `name` | string | No | Human-readable name for the schedule |
| `description` | string | No | Description of what this schedule does |
| `parameters` | object | No | Workflow parameters to pass on each run |
| `enabled` | boolean | No | Whether the schedule is active. Defaults to `true` |
### Enable and disable a schedule
<CodeGroup>
```python Python
# Disable
await client.agent.disable_workflow_schedule(
workflow_permanent_id="wpid_123456789",
workflow_schedule_id="wfs_abc123"
)
# Re-enable
await client.agent.enable_workflow_schedule(
workflow_permanent_id="wpid_123456789",
workflow_schedule_id="wfs_abc123"
)
```
```bash cURL
# Disable
curl -X POST "https://api.skyvern.com/api/v1/workflows/wpid_123456789/schedules/wfs_abc123/disable" \
-H "x-api-key: $SKYVERN_API_KEY"
# Re-enable
curl -X POST "https://api.skyvern.com/api/v1/workflows/wpid_123456789/schedules/wfs_abc123/enable" \
-H "x-api-key: $SKYVERN_API_KEY"
```
</CodeGroup>
### Delete a schedule
Permanently remove a schedule. This cannot be undone. Runs that were already triggered by this schedule are not affected.
<CodeGroup>
```python Python
await client.agent.delete_workflow_schedule_route(
workflow_permanent_id="wpid_123456789",
workflow_schedule_id="wfs_abc123"
)
```
```bash cURL
curl -X DELETE "https://api.skyvern.com/api/v1/workflows/wpid_123456789/schedules/wfs_abc123" \
-H "x-api-key: $SKYVERN_API_KEY"
```
</CodeGroup>
---
## List workflows
Retrieve all workflows in your organization.
<CodeGroup>
```python Python
workflows = await client.get_workflows()
for workflow in workflows:
print(f"{workflow.workflow_permanent_id}: {workflow.title}")
```
```typescript TypeScript
const workflows = await client.getWorkflows();
for (const workflow of workflows) {
console.log(`${workflow.workflow_permanent_id}: ${workflow.title}`);
}
```
```bash cURL
curl -X GET "https://api.skyvern.com/v1/workflows" \
-H "x-api-key: $SKYVERN_API_KEY"
```
</CodeGroup>
@@ -0,0 +1,146 @@
---
title: Schedule a Workflow
subtitle: Set up recurring cron-based execution from the UI
description: Set up recurring cron-based workflow schedules in the Skyvern Cloud UI, including creating, editing, pausing, and deleting schedules with timezone support.
slug: cloud/scheduling
keywords:
- schedule
- cron
- recurring
- timezone
- pause
- resume
- enable
- disable
---
You can schedule any workflow built in the Cloud UI to run automatically on a recurring basis. Schedules are configured with a cron expression and timezone, and Skyvern triggers the workflow at each interval.
This page covers scheduling through the Cloud UI. You can also create schedules programmatically via the SDK or API. See [Run from Code](/cloud/building-workflows/run-from-code) for the code approach.
Schedules are created as **active** by default: they start triggering runs immediately after creation.
When creating a schedule you'll fill in these fields:
- **Workflow** (required): The workflow to run. When creating from the workflow editor this is pre-selected.
- **Cron Expression** (required): A standard 5-field cron expression that defines how often the workflow runs (e.g., `0 9 * * 1-5` for every weekday at 9 AM). The UI validates the expression in real time and shows a human-readable translation. Quick presets are available for common patterns like hourly, daily, and weekly.
- **Timezone** (required): The IANA timezone the cron expression is evaluated in (e.g., `America/New_York`). Defaults to your browser's local timezone. The dropdown is searchable by city name.
- **Name**: A human-readable label to identify this schedule in the table and run history.
- **Description**: Optional notes about what this schedule does or why it exists.
<Warning>
The minimum interval between runs is **5 minutes**. Expressions that resolve to shorter intervals are rejected.
</Warning>
---
## Creating a schedule
<Tabs>
<Tab title="From the Schedules page">
<Steps>
<Step title="Open the Schedules page">
Click [**Schedules**](https://app.skyvern.com/schedules/) (calendar icon) in the left sidebar.
</Step>
<Step title="Click Create Schedule">
Click <kbd>Create Schedule</kbd> in the top right corner.
<img src="/images/cloud/create-schedule-button.png" alt="Schedules page with Create Schedule button in the top right corner" />
</Step>
<Step title="Select a workflow and configure the schedule">
Choose the workflow you want to schedule from the dropdown. Only saved workflows appear in this list. Then fill in the cron expression, timezone, and optionally a name and description. Check the **Next Scheduled Runs** preview to verify the upcoming execution times match your expectations.
<Frame>
<img src="/images/cloud/create-sched-form.png" alt="Schedule creation form with workflow dropdown, cron expression, timezone, name, and description fields" width="300" />
</Frame>
</Step>
<Step title="Create">
Click **Create Schedule**. The schedule starts in an **Active** state and triggers at the next scheduled time.
</Step>
</Steps>
</Tab>
<Tab title="From the workflow editor">
<Steps>
<Step title="Open the workflow">
Navigate to [**Workflows**](https://app.skyvern.com/workflows/) in the sidebar and click the workflow you want to schedule.
</Step>
<Step title="Click the Schedule button">
In the editor header bar, click the <kbd>Schedule</kbd> button (clock icon).
<img src="/images/cloud/wf-page-sched.png" alt="Workflow editor page with Schedule button (clock icon) in the header bar" />
</Step>
<Step title="Click Add and configure the schedule">
A panel opens showing any existing schedules for this workflow. Click <kbd>Add</kbd> to create a new one. Fill in the cron expression, timezone, and optionally a name and description. The workflow is already selected.
<Frame>
<img src="/images/cloud/create-sched-form.png" alt="Schedule creation form with cron expression, timezone, name, and description fields" width="300" />
</Frame>
</Step>
<Step title="Create">
Click **Create Schedule**. The schedule appears in the panel and starts immediately.
</Step>
</Steps>
</Tab>
</Tabs>
---
## The Schedules page
Click **Schedules** in the left sidebar to see every schedule across all workflows.
Each row shows:
| Column | What it shows |
|--------|--------------|
| **Workflow** | The workflow this schedule triggers |
| **Name** | Schedule name |
| **Schedule** | Human-readable cron description (e.g., "Every weekday at 9:00 AM") |
| **Next Run** | Next execution time in your local timezone |
| **Status** | **Active** (green) or **Paused** (gray) |
Use the search bar to filter by schedule name or workflow title. The status filter narrows to Active or Paused schedules.
---
## Editing a schedule
Click a schedule row to open its detail page.
<img src="/images/cloud/sched-page.png" alt="Schedule detail page showing configuration, details, and upcoming runs sections" />
On this page, you can:
- **Edit the schedule configuration**: Click the **Edit** button to change the frequency, timezone, cron expression, name, and description. Changes take effect immediately and the **Upcoming Runs** preview updates to reflect the new configuration.
- **View schedule details**: See when the schedule was created and last modified.
- **Preview upcoming runs**: Check the next 5 scheduled execution times in the **Upcoming Runs** section.
- **Pause or resume**: Toggle the **Status** switch to pause the schedule. Paused schedules keep their configuration and can be resumed at any time: no runs are triggered while paused.
- **Delete the schedule**: Use the delete button (trash icon) in the header. Deletion is permanent. Runs already triggered by the schedule are not affected.
<Info>
To change which workflow a schedule runs, delete the schedule and create a new one for the target workflow.
</Info>
---
## What's next
<CardGroup cols={3}>
<Card
title="Scheduling API"
icon="code"
href="/cloud/building-workflows/run-from-code#create-a-schedule"
>
Create and manage schedules programmatically
</Card>
<Card
title="Run History"
icon="clock-rotate-left"
href="/cloud/viewing-results/run-history"
>
View and filter results from scheduled runs
</Card>
<Card
title="Cost Control"
icon="gauge"
href="/developers/optimization/cost-control"
>
Manage costs for recurring automations
</Card>
</CardGroup>
@@ -0,0 +1,10 @@
---
title: AI Agents Quickstart
subtitle: Give your AI coding assistant full browser automation in one command
description: Set up Skyvern's MCP server so Claude, Cursor, Windsurf, or any AI coding assistant can automate browsers with a single command.
slug: cloud/getting-started/ai-agents-quickstart
---
import AIAgentsQuickstartContent from "/snippets/ai-agents-quickstart-content.mdx";
<AIAgentsQuickstartContent />
@@ -0,0 +1,247 @@
---
title: Core Concepts
subtitle: The building blocks of every automation in the Skyvern dashboard
description: Understand tasks, workflows, blocks, runs, browser sessions, browser profiles, and credentials in the Skyvern Cloud UI — what each is, where to find it, and how it fits together.
slug: cloud/getting-started/core-concepts
keywords:
- task
- workflow
- block
- browser session
- browser profile
- credential
- run
- schedule
- engine
---
Every automation you build in Skyvern Cloud is composed of the same nine building blocks. This page is a quick tour of each one — what it is, where you find it in the dashboard, and when to reach for it.
If you've already poked around the dashboard, this map will tie what you've seen to the underlying concepts.
---
## Tasks
A **Task** is a single automation job. You describe what you want, Skyvern opens a browser and does it.
You create tasks from the **Discover** page. Type your prompt and target URL into the input bar, pick an engine, and hit send.
<img src="/images/cloud/discover-page-overview.png" alt="Discover page where you create one-off tasks" />
Tasks are the right starting point for one-off automations, ad-hoc data extraction, or quickly testing whether an idea is feasible before turning it into a workflow.
When you outgrow a single task — you need parameters, branching, loops, or to run the same flow on a schedule — graduate to a Workflow.
<Card title="Run a task →" icon="play" href="/cloud/getting-started/run-a-task">
Walkthrough of every option on the Discover page.
</Card>
---
## Workflows
A **Workflow** is a reusable automation built by chaining blocks together on a visual canvas. Workflows are versioned, parameterized, and shareable across your team.
You build them on the **Workflows** page. Click any workflow to open the editor, where blocks appear as connected nodes you can drag and configure.
<img src="/images/cloud/workflow-editor-overview.png" alt="Workflow editor with blocks chained together" />
Use a workflow when:
- The same flow needs to run repeatedly with different inputs
- You need to loop over a list, branch on a condition, or pass data between steps
- You want to schedule the automation to run on a cadence
- You want a teammate to be able to re-run it without re-deriving the logic
<Card title="Build a workflow →" icon="diagram-project" href="/cloud/building-workflows/build-a-workflow">
Tutorial covering blocks, parameters, branching, and execution.
</Card>
---
## Blocks
**Blocks** are the units a workflow is built from. Each block performs one thing — navigate, log in, extract data, branch on a condition, send an email — and passes its output to the next block.
In the workflow editor, click the **+** button on any node to insert a new block. The picker groups every available block by category.
<img src="/images/cloud/add-block-panel.png" alt="Block picker with categories and block types" />
There are 20+ block types organized into:
- **Browser automation** — Browser Task, Browser Action, Login, Extraction, Go to URL, Print Page
- **Data and extraction** — Text Prompt, File Parser
- **Control flow** — Loop, Conditional, AI Validation, Code, Wait
- **Files** — File Download, Cloud Storage Upload
- **Communication** — Send Email, HTTP Request, Human Interaction
Each block has its own configuration panel. The full reference, with every field for every block, lives at [Workflow Blocks](/cloud/building-workflows/configure-blocks).
---
## Runs
Every time a task or workflow executes, Skyvern creates a **Run** — a record of what happened, with a video, screenshots, action log, and any extracted data.
The **Runs** page is your history. Filter by status, search by run ID, click any row to drill in.
<img src="/images/cloud/run-history-overview.png" alt="Runs page showing execution history with statuses" />
Inside a run detail page you'll find:
- **Live viewer / recording** — full video of the browser as it executed
- **Actions** — every step the agent took, with the LLM's reasoning
- **Output** — the structured data extracted (matches the schema you defined)
- **Code** — auto-generated Python/TypeScript/cURL to reproduce this run via API
- **Downloaded files** — anything Skyvern saved, with signed URLs and checksums
A run can be `queued`, `running`, `completed`, `failed`, `terminated`, `timed_out`, or `canceled`. You're billed per **step** — one screenshot + LLM decision + browser action.
<Card title="Read run details →" icon="list-check" href="/cloud/viewing-results/run-details">
How to interpret the actions tab, recordings, and output.
</Card>
---
## Browser sessions
A **browser session** is a live browser instance you keep open across multiple runs. Sessions preserve everything that lives in the browser — cookies, login state, cached pages, the current tab — so a follow-up task picks up exactly where the previous one left off.
You manage sessions on the **Browsers** page. Create a session, run tasks against it, then close it when you're done.
<img src="/images/cloud/browsers-page-overview.png" alt="Browsers page with active session and details" />
Sessions are perfect when you want to:
- Log in once, then run a sequence of tasks behind that login
- Hand off a partially-completed flow between an agent and a human (Take Control)
- Keep a long-running automation warm without re-authenticating each step
Sessions live for 5 minutes to 24 hours (default 60 minutes). When the timer ends or you close it manually, the browser is destroyed and its state goes with it.
<Card title="Browser sessions →" icon="window" href="/cloud/browser-management/browser-sessions">
Create, attach, and reuse sessions across runs.
</Card>
---
## Browser profiles
A **browser profile** is the persistent counterpart to a session. Where a session is a live browser that times out, a profile is a saved snapshot — cookies, auth tokens, local storage — that you can reload weeks later to skip the login flow entirely.
Profiles are listed on the **Browsers** page under the Profiles tab. You create one from any completed run, then attach it to future runs to start in an already-authenticated state.
| | Browser session | Browser profile |
|---|---|---|
| **Live or saved?** | Live, in-memory browser | Saved snapshot of state |
| **Lifetime** | 5 min – 24 hr | Indefinite |
| **Best for** | Chaining tasks in real time | Skipping login on repeat runs |
<Card title="Browser profiles →" icon="floppy-disk" href="/cloud/browser-management/browser-profiles">
Save and reuse authenticated state across days or weeks.
</Card>
---
## Credentials
A **credential** is a stored login, credit card, or 2FA secret that Skyvern injects directly into the browser at runtime. Credentials are encrypted at rest and **never sent to the LLM** — the agent decides where the password field is, and the value is filled in via the browser layer.
The **Credentials** page is where you manage them.
<img src="/images/cloud/credentials-overview.png" alt="Credentials page with password and credit card credentials" />
Three credential types are supported:
- **Password** — username + password, optionally with a TOTP secret or email/SMS 2FA
- **Credit card** — card number, expiry, CVC, billing address
- **Secret** — any single value you want to keep out of the LLM context
You can also sync credentials from **Bitwarden**, **1Password**, or **Azure Key Vault** instead of storing them in Skyvern.
<Card title="Credentials overview →" icon="lock" href="/cloud/managing-credentials/credentials-overview">
Security model, supported types, and external vault integration.
</Card>
---
## Schedules
A **schedule** runs a workflow automatically on a recurring cadence. You set a cron expression and timezone, and Skyvern fires the workflow at every interval — no manual trigger needed.
Schedules are configured per workflow. Open any workflow's actions menu and choose **Schedule**.
<Frame>
<img src="/images/cloud/create-sched-form.png" alt="Schedule form with cron expression and timezone" width="300" />
</Frame>
Use schedules for daily reports, hourly monitoring, periodic data syncs, or anything that should "just keep running" without you remembering to click Run.
<Card title="Scheduling →" icon="calendar" href="/cloud/building-workflows/scheduling">
Cron syntax, timezones, and managing scheduled runs.
</Card>
---
## Engines
An **engine** is the AI model Skyvern uses to drive the browser. Different engines have different strengths — speed, accuracy on complex pages, cost — and you can pick one per task or per block.
The engine picker appears on the Discover page (for tasks) and on every browser-driven block in the workflow editor.
| Engine | When to use |
|--------|-------------|
| **Skyvern 2.0** | Default. Best balance of accuracy and speed for most automations. |
| **Skyvern 1.0** | Lighter and faster for simple, single-page interactions. |
| **OpenAI CUA** | OpenAI's Computer Use Agent. Good for visual reasoning. |
| **Anthropic CUA** | Anthropic's Claude Computer Use. Strong at multi-step planning. |
| **UI-TARS** | Lightweight CUA model option. |
If you're not sure, leave it on the default. Switch engines if you hit accuracy issues on a specific site.
---
## How they fit together
```mermaid
flowchart LR
A[Task] -->|Single job, one prompt| R1[Run]
W[Workflow] -->|Reusable, multi-step| R2[Run]
W -->|Composed of| B[Blocks]
S[Schedule] -->|Triggers| W
R1 & R2 -->|Optionally use| BS[Browser Session]
BS -->|Snapshot to| BP[Browser Profile]
BP -->|Restored by| R1
BP -->|Restored by| R2
R1 & R2 -->|Inject at runtime| C[Credentials]
R1 & R2 -->|Driven by| E[Engine]
```
A typical day in the dashboard:
1. **Prototype** with a Task on the Discover page. Iterate on the prompt until it works.
2. **Productionize** by turning the prompt into a Workflow with Blocks, Parameters, and a Schedule.
3. **Persist state** by saving a Browser Profile after the first authenticated run, so future runs skip login.
4. **Audit** every execution on the Runs page — recording, actions, output, downloaded files.
---
## Next steps
<CardGroup cols={2}>
<Card
title="Run Your First Task"
icon="play"
href="/cloud/getting-started/run-your-first-task"
>
Hands-on tutorial — go from prompt to extracted data in a few minutes.
</Card>
<Card
title="Build a Workflow"
icon="diagram-project"
href="/cloud/building-workflows/build-a-workflow"
>
Wire blocks together into a reusable, parameterized automation.
</Card>
</CardGroup>
@@ -0,0 +1,17 @@
---
title: What is Skyvern?
subtitle: AI-powered browser automation for any website
description: Learn what Skyvern is and how it uses AI and computer vision to automate browser interactions on any website through the Cloud UI.
slug: cloud/getting-started/introduction
keywords:
- browser automation
- AI agent
- computer vision
- LLM
- natural language
- visual reasoning
---
import IntroductionContent from "/snippets/introduction-content.mdx";
<IntroductionContent />
+25
View File
@@ -0,0 +1,25 @@
---
title: MCP Server
subtitle: Connect AI assistants to browser automation via Model Context Protocol
description: Install and configure Skyvern's MCP server so Claude Desktop, Claude Code, Cursor, Windsurf, Codex, Hermes, OpenClaw, and other AI tools can run browser automations from the Skyvern Cloud dashboard over OAuth or API key.
slug: cloud/getting-started/mcp
keywords:
- MCP
- Model Context Protocol
- OAuth
- Claude Desktop
- Claude Code
- Cursor
- Windsurf
- Codex
- Hermes
- OpenClaw
- MCPorter
- AI assistant
- tools
- streamable-http
---
import McpContent from "/snippets/mcp-content.mdx";
<McpContent />
@@ -0,0 +1,100 @@
---
title: Watching Live Execution
subtitle: Monitor, interact with, and control running tasks
description: Monitor running tasks in real time in the Skyvern Cloud UI, view the live browser stream and agent reasoning logs, and take manual control of the browser mid-task.
slug: cloud/monitor-a-run
keywords:
- live viewer
- real-time
- agent reasoning
- take control
- manual control
- step timeline
---
When you run a task from the [Discover page](/cloud/getting-started/run-a-task), you're taken to the live execution screen where you can watch the browser in real time.
<img src="/images/cloud/live-execution-overview.png" alt="Live execution screen" />
---
## The execution screen
The execution view has three panels:
| Panel | What it shows |
|-------|---------------|
| **Left: Task configuration** | The block being executed, its URL, and prompt. A status badge shows the current state. |
| **Center: Live browser** | Real-time view of the browser. You see pages load, forms fill, and buttons click. |
| **Right: Agent logs** | Real-time LLM reasoning and action decisions. Shows why the AI made each choice. |
---
## When the live view is available
The live browser stream is active while the task is still in progress:
| Status | Live view |
|--------|-----------|
| `created` | Waiting to start |
| `queued` | Waiting for a browser |
| `running` | **Active**: the browser is navigating |
| `completed` | Stream closed. View the recording instead. |
| `failed` | Stream closed. View the recording instead. |
| `terminated` | Stream closed. View the recording instead. |
| `timed_out` | Stream closed. View the recording instead. |
| `canceled` | Stream closed. View the recording instead. |
Once a task reaches a final state, the live stream closes. Open the run from **Runs** in the sidebar to access the full recording, screenshots, and action history.
---
## Taking control of the browser
While a task is running, you can take over the browser and interact with the page directly, just like you would in your own Chrome window.
### How it works
1. Click the **Take Control** button in the live browser panel.
2. The AI agent pauses and you get full mouse and keyboard control of the browser.
3. Interact with the page: type into fields, click buttons, solve CAPTCHAs, dismiss popups.
4. Click **Release Control** to hand the browser back to the AI. It picks up from the current page state and continues the task.
### When to use it
- **CAPTCHAs**: solve a CAPTCHA the AI can't get past, then release control
- **Unusual login flows**: complete a multi-factor or SSO login that the agent doesn't handle
- **Unexpected popups or modals**: dismiss cookie banners, age gates, or promotional overlays
- **Mid-task corrections**: navigate to the right page or fix a form field before letting the agent continue
<Warning>
Taking control pauses the AI agent. The task timer keeps running, so release control promptly to avoid timeouts.
</Warning>
<Tip>
You can take and release control multiple times during a single run. Each time, the agent resumes from whatever state you left the browser in.
</Tip>
---
## Stopping a running task
You can cancel a task at any time while it's running or queued. Click the **Cancel** button in the task header. A confirmation dialog appears before the task is stopped. The task transitions to `canceled` and any configured webhook fires with the canceled status.
<Note>
Credits for actions already taken are still consumed. Canceling stops future actions but does not refund past ones.
</Note>
---
## Reviewing results
Once a task finishes, open it from **Runs** to see the full results. The run detail page has five tabs:
- **Overview**: The AI's reasoning timeline alongside browser screenshots. Each Thought, Block, and Action card shows what the agent saw and why it acted.
- **Output**: The complete JSON output and any downloaded files.
- **Parameters**: The configuration you submitted: URL, prompt, engine, proxy location, webhook URL, data schema, and other settings.
- **Recording**: Full video replay of the browser session. Every task is recorded automatically.
- **Code**: Auto-generated Python code to reproduce this task via the API or SDK (when code generation is enabled).
For a full walkthrough of each tab, see [Run Details](/cloud/viewing-results/run-details).
+94
View File
@@ -0,0 +1,94 @@
---
title: UI Overview
slug: cloud/overview
subtitle: Navigate the Skyvern Cloud dashboard
description: Tour the Skyvern Cloud dashboard
keywords:
- dashboard
- navigation
- sidebar
- settings
- runs page
- workflows page
- run
---
Skyvern Cloud ([app.skyvern.com](https://app.skyvern.com)) lets you automate any website from your browser. Describe what you want in plain English, watch an AI-powered browser do it live, and get structured results back. No code required.
<Tip>
New to Skyvern? The [homepage](/) covers how Skyvern works under the hood, built-in capabilities, and the eight core concepts behind every automation.
</Tip>
<Note>
Looking to integrate Skyvern into your own app? See the [Quickstart](/developers/getting-started/quickstart) instead.
</Note>
## The dashboard
Sign in and you'll land on the **Discover** page, the starting point for running automations.
<img src="/images/cloud/skyvern-cloud-discover.png" alt="Skyvern Cloud dashboard showing the Discover page" />
The left sidebar is your navigation hub. Here's what each section does:
### Build
Where you create and monitor automations.
| Page | Purpose |
|------|---------|
| **Discover** | Run one-off tasks. Type your instructions and target URL into a single prompt, pick an engine, and hit send. |
| **Workflows** | Build multi-step automations with the visual workflow editor. Add loops, conditionals, and data passing between steps. |
| **Runs** | Execution history for every task and workflow. Filter by status, drill into any run to see actions, recordings, and extracted data. |
| **Browsers** | Active [browser sessions](/cloud/browser-management/browser-sessions). Keep a browser open across multiple tasks to preserve login state, cookies, and page context. Load a [browser profile](/cloud/browser-management/browser-profiles) to restore previously saved state. |
### Agents
Ready-made automation templates. Each agent is preconfigured with a prompt, target URL, and settings. Pick one to see it work or use it as a starting point for your own task.
### General
| Page | Purpose |
|------|---------|
| **Billing** | Usage, remaining credits, and plan management. |
| **Credentials** | Store website logins, credit card details, and secret values securely. Skyvern uses these to authenticate automatically, fill payment forms, and inject secrets into workflows. |
| **Settings** | API key, account preferences, and organization management. |
## How it works
Every automation in Skyvern Cloud follows the same pattern:
<Steps>
<Step title="Describe your task">
Type what you want into the prompt bar. Include the target URL and your instructions in one go. Something like "Get the top post from https://news.ycombinator.com" or "Fill out the contact form at https://example.com/contact with my details."
</Step>
<Step title="Watch it happen">
A cloud browser opens and you see it navigate in real time. Pages load, elements highlight, actions fire. An agent log streams the AI's reasoning (what it sees on the page, what it plans to do, and why) so you can follow along. If the AI gets stuck, hit **Take Control** to jump in and help.
</Step>
<Step title="Get your results">
Extracted data appears as structured JSON on the run detail page. Every run also includes an output view, full recording, the parameters you submitted, and auto-generated code to reproduce the task via API.
</Step>
</Steps>
That's it. The next guide walks you through this flow with a real example.
---
## Next steps
<CardGroup cols={2}>
<Card
title="Run Your First Task"
icon="play"
href="/cloud/getting-started/run-your-first-task"
>
Follow along with a real example to see Skyvern Cloud in action
</Card>
<Card
title="Core Concepts"
icon="book"
href="/developers/getting-started/core-concepts"
>
Understand tasks, workflows, and other foundational concepts
</Card>
</CardGroup>
+195
View File
@@ -0,0 +1,195 @@
---
title: The Discover Page
subtitle: Run ad-hoc browser automations with natural language
description: Use the Discover page in the Skyvern Cloud UI to run ad-hoc browser automation tasks with natural language prompts, choose an engine, and configure advanced settings like proxies and webhooks.
slug: cloud/run-a-task
keywords:
- discover page
- prompt
- engine
- proxy
- webhook
- data extraction
- advanced settings
- 2FA
---
The **Discover** page is where you run one-off browser automations. Type what you want done in plain language, and Skyvern opens a browser and does it for you.
<img src="/images/cloud/discover-page-overview.png" alt="Discover page overview" />
---
## The prompt box
Type a natural language instruction describing what you want automated. Be specific about the goal and any data you want extracted.
**Examples:**
- "Go to amazon.com and find the price of the MacBook Air M4"
- "Fill out the contact form at example.com/contact with name John Doe and email john@example.com"
- "Get an insurance quote from geico.com for a 2020 Toyota Camry"
<img src="/images/cloud/prompt-box-filled.png" alt="Prompt box with a sample prompt" />
Click the **send button** or press **Enter** to start.
Below the prompt box, **quick-action buttons** offer pre-built examples like "Add a product to cart" or "Get an insurance quote." Click one to run it immediately or use it as a starting point.
---
## Choosing an engine
The dropdown next to the send button controls which engine runs the task.
| Engine | Best for |
|--------|----------|
| **Skyvern 2.0 with Code** | Complex, multi-step tasks. Generates reusable scripts. **(Default)** |
| **Skyvern 2.0** | Complex tasks without script generation |
| **Skyvern 1.0** | Simple, single-objective tasks. Faster and cheaper. |
<Tip>
Start with the default. Switch to Skyvern 1.0 when you have a straightforward, single-page task and want faster execution.
</Tip>
---
## Advanced settings
Click the **gear icon** next to the prompt box to expand the settings panel.
<img src="/images/cloud/advanced-settings-panel.png" alt="Advanced settings panel" />
| Setting | What it does |
|---------|-------------|
| **Proxy Location** | Route the browser through a residential proxy in a specific country. Default is `RESIDENTIAL` (US). Set to `NONE` to disable. Available: US, UK, Germany, France, Spain, Ireland, India, Japan, Australia, Canada, Brazil, Mexico, Argentina, New Zealand, South Africa, Italy, Netherlands, Philippines, Turkey. |
| **Webhook URL** | URL that receives a POST request when the task finishes. The payload includes status, extracted data, screenshots, and recording URL. |
| **Browser Session ID** | Run inside an existing persistent browser session (`pbs_xxx`). Preserves cookies and login state across multiple tasks. |
| **CDP Address** | Connect to your own browser via Chrome DevTools Protocol (e.g., `http://127.0.0.1:9222`). For local development. |
| **2FA Identifier** | Links your TOTP credentials to this task. Skyvern uses it to retrieve the correct code when a 2FA prompt appears. |
| **Extra HTTP Headers** | Custom headers sent with every browser request, as JSON (e.g., `{"Authorization": "Bearer token"}`). |
| **Publish Workflow** | Save a reusable workflow alongside the task run. Re-run the same automation later from the Workflows page. |
| **Max Steps Override** | Cap the number of AI reasoning steps. Each step = one screenshot-analyze-act cycle. Useful for controlling cost during development. |
| **Max Screenshot Scrolls** | Number of scrolls for post-action screenshots. Increase for pages with lazy-loaded content. `0` = viewport only. |
---
## Data extraction schema
The **Data Schema** field in advanced settings lets you define the structure of extracted output as [JSON Schema](https://json-schema.org/).
Without a schema, the AI returns data in whatever format it chooses. With a schema, output conforms to your structure, making it predictable for downstream use.
<img src="/images/cloud/data-schema-field.png" alt="Data schema field with JSON" />
```json
{
"type": "object",
"properties": {
"product_name": {
"type": "string",
"description": "The name of the product"
},
"price": {
"type": "number",
"description": "The price in USD"
},
"in_stock": {
"type": "boolean",
"description": "Whether the product is in stock"
}
}
}
```
Use the `description` field on each property to guide the AI on what to extract.
<Accordion title="Example: Extracting a list of items">
```json
{
"type": "object",
"properties": {
"quotes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"premium_amount": {
"type": "string",
"description": "Total premium in USD (e.g., '$321.57')"
},
"coverage_type": {
"type": "string",
"description": "Type of coverage (e.g., 'Full Coverage')"
},
"deductible": {
"type": "string",
"description": "Deductible amount"
}
}
}
}
}
}
```
</Accordion>
---
## Workflow templates
Below the prompt box, the Discover page shows a gallery of **workflow templates**: pre-built automations for common use cases.
<img src="/images/cloud/workflow-templates.png" alt="Workflow template gallery" />
Click any template to launch it with pre-filled configuration, or use it as a starting point and customize.
---
## Tips for better results
**Write specific prompts.** Include the exact goal, target fields, and what "done" looks like.
| Instead of | Write |
|-----------|-------|
| "Get some data from this site" | "Extract the product name, price, and availability from the first 5 results on amazon.com/s?k=wireless+mouse" |
| "Fill out the form" | "Fill the contact form at example.com/contact with name 'Jane Doe', email 'jane@example.com', and message 'Demo request'" |
**Control cost with Max Steps.** Set **Max Steps Override** to a reasonable limit (e.g., 10–20 for simple tasks) during development. Each step consumes one credit. Remove the cap once you've confirmed the task works.
**Debug failures in order.** If a task fails or produces wrong results:
1. Check the **Failure Reason** at the top of the run detail page
2. Read the **Thought cards** in the Overview timeline to find where the AI went off track
3. Watch the **Recording** to see what actually happened on screen
4. Review **Parameters** to confirm the inputs were correct
---
## What happens next
1. Your prompt is sent to Skyvern
2. A cloud browser opens and navigates to the target URL (or finds one from your prompt)
3. The AI analyzes the page, plans actions, and executes them step by step
4. You're taken to the [live execution view](/cloud/getting-started/monitor-a-run) where you can watch it happen in real time
5. When complete, results appear on the run detail page under **Runs**
---
## Next steps
<CardGroup cols={2}>
<Card
title="Watching Live Execution"
icon="eye"
href="/cloud/getting-started/monitor-a-run"
>
Monitor runs, take control of the browser, and review results
</Card>
<Card
title="Build a Workflow"
icon="diagram-project"
href="/cloud/building-workflows/build-a-workflow"
>
Turn a successful task into a reusable multi-step workflow
</Card>
</CardGroup>
@@ -0,0 +1,357 @@
---
title: Run from Code
subtitle: Execute tasks and retrieve results via the API or SDK
description: Run browser automation tasks programmatically using the Python SDK, TypeScript SDK, or REST API. Poll for results, use webhooks, or wait for completion.
slug: cloud/getting-started/run-from-code
keywords:
- run_task
- get_run
- polling
- wait_for_completion
- webhook
- SDK
- API
---
Run tasks programmatically using the Python SDK, TypeScript SDK, or REST API.
---
## Run a task
A task has one required parameter and one commonly used optional parameter:
- **`prompt`** (required): Natural language instructions describing what the AI should do
- **`url`** (optional): The starting page for the automation
When you call `run_task`, Skyvern spins up a cloud browser, navigates to the URL, and executes your prompt. A typical task takes 30-90 seconds depending on complexity.
<CodeGroup>
```python Python
import os
import asyncio
from skyvern import Skyvern
async def main():
client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
result = await client.run_task(
prompt="Get the title of the top post",
url="https://news.ycombinator.com",
)
print(f"Run ID: {result.run_id}")
print(f"Status: {result.status}")
asyncio.run(main())
```
```typescript TypeScript
import { SkyvernClient } from "@skyvern/client";
async function main() {
const client = new SkyvernClient({
apiKey: process.env.SKYVERN_API_KEY,
});
const result = await client.runTask({
body: {
prompt: "Get the title of the top post",
url: "https://news.ycombinator.com",
},
});
console.log(`Run ID: ${result.run_id}`);
console.log(`Status: ${result.status}`);
}
main();
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Get the title of the top post",
"url": "https://news.ycombinator.com"
}'
```
</CodeGroup>
**Example response:**
```json
{
"run_id": "tsk_v2_486305187432193504",
"status": "queued",
"output": null,
"downloaded_files": null,
"recording_url": null,
"screenshot_urls": null,
"failure_reason": null,
"created_at": "2026-01-20T11:52:29.276851",
"modified_at": "2026-01-20T11:52:29.484284",
"app_url": "https://app.skyvern.com/runs/wr_486305187432193510",
"run_type": "task_v2"
}
```
The response includes a `run_id`. Use this ID to check status, fetch results, and retrieve artifacts.
<Warning>
`run_task` returns immediately -- the task is queued, not finished. Always poll or use webhooks to get results.
</Warning>
---
## Get results
The `run_task` call queues the task and returns immediately.
Use the `run_id` to fetch results once the task reaches a terminal state.
| Status | Description |
|--------|-------------|
| `created` | Task initialized, not yet queued |
| `queued` | Waiting for an available browser |
| `running` | AI is navigating and executing |
| `completed` | Task finished successfully -- check `output` for results |
| `failed` | Task encountered an error -- check `failure_reason` and retry or adjust your prompt |
| `terminated` | Task was manually stopped |
| `timed_out` | Task exceeded time limit -- increase `max_steps` or simplify the task |
| `canceled` | Task was canceled before starting |
You have three options for retrieving results:
### Option 1: Polling
Poll `get_run` until status is terminal (`completed`, `failed`, `terminated`, `timed_out`, or `canceled`).
<CodeGroup>
```python Python
run_id = result.run_id
while True:
run = await client.get_run(run_id)
if run.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
break
await asyncio.sleep(5)
print(f"Output: {run.output}")
```
```typescript TypeScript
const runId = result.run_id;
while (true) {
const run = await client.getRun(runId);
if (["completed", "failed", "terminated", "timed_out", "canceled"].includes(run.status)) {
console.log(`Output: ${JSON.stringify(run.output)}`);
break;
}
await new Promise((resolve) => setTimeout(resolve, 5000));
}
```
```bash cURL
#!/bin/bash
RUN_ID="YOUR_RUN_ID"
while true; do
RESPONSE=$(curl -s -X GET "https://api.skyvern.com/v1/runs/$RUN_ID" \
-H "x-api-key: $SKYVERN_API_KEY")
STATUS=$(echo "$RESPONSE" | jq -r '.status')
echo "Status: $STATUS"
if [[ "$STATUS" == "completed" || "$STATUS" == "failed" || "$STATUS" == "terminated" || "$STATUS" == "timed_out" || "$STATUS" == "canceled" ]]; then
echo "$RESPONSE" | jq '.output'
break
fi
sleep 5
done
```
</CodeGroup>
<Warning>
Your polling loop must check **all** terminal states: `completed`, `failed`, `terminated`, `timed_out`, `canceled`. Missing one causes infinite loops.
</Warning>
### Option 2: Webhooks
Pass a `webhook_url` when creating the task. Skyvern sends a POST request to your URL when the task completes.
<CodeGroup>
```python Python
result = await client.run_task(
prompt="Get the title of the top post",
url="https://news.ycombinator.com",
webhook_url="https://your-server.com/webhook",
)
```
```typescript TypeScript
const result = await client.runTask({
body: {
prompt: "Get the title of the top post",
url: "https://news.ycombinator.com",
webhook_url: "https://your-server.com/webhook",
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Get the title of the top post",
"url": "https://news.ycombinator.com",
"webhook_url": "https://your-server.com/webhook"
}'
```
</CodeGroup>
Skyvern sends a POST request with the full run data when the task completes or fails.
### Option 3: Wait for completion (Python only)
Block until the task finishes instead of polling manually.
```python Python
result = await client.run_task(
prompt="Get the title of the top post",
url="https://news.ycombinator.com",
wait_for_completion=True,
)
print(result.output)
```
---
## Understand the response
The response from polling (`get_run`) and webhooks have slightly different structures. Both contain the core task data, but webhooks include additional metadata.
<CodeGroup>
```json Polling Response
{
"run_id": "tsk_v2_486305187432193504",
"status": "completed",
"output": {
"top_post_title": "Linux kernel framework for PCIe device emulation, in userspace"
},
"downloaded_files": [],
"recording_url": "https://skyvern-artifacts.s3.amazonaws.com/v1/production/.../recording.webm?...",
"screenshot_urls": ["https://skyvern-artifacts.s3.amazonaws.com/.../screenshot_final.png?..."],
"failure_reason": null,
"errors": [],
"step_count": 2,
"run_type": "task_v2",
"app_url": "https://app.skyvern.com/runs/wr_486305187432193510",
"browser_session_id": null,
"browser_profile_id": null,
"created_at": "2026-01-20T11:52:29.276851",
"modified_at": "2026-01-20T11:54:08.822807",
"queued_at": "2026-01-20T11:52:29.483922",
"started_at": "2026-01-20T11:52:31.835337",
"finished_at": "2026-01-20T11:54:08.821985",
"run_request": {
"prompt": "Get the title of the top post",
"url": "https://news.ycombinator.com/",
"engine": "skyvern-2.0"
}
}
```
```json Webhook Payload
{
"task_id": "tsk_v2_486306851394503256",
"run_id": "tsk_v2_486306851394503256",
"status": "completed",
"output": {
"top_post_title": "Linux kernel framework for PCIe device emulation, in userspace"
},
"summary": "I have successfully navigated to Hacker News and extracted the title of the top post.",
"prompt": "Get the title of the top post",
"url": "https://news.ycombinator.com/",
"downloaded_files": [],
"recording_url": "https://skyvern-artifacts.s3.amazonaws.com/v1/production/.../recording.webm?...",
"screenshot_urls": ["https://skyvern-artifacts.s3.amazonaws.com/.../screenshot_final.png?..."],
"failure_reason": null,
"errors": [],
"step_count": 2,
"run_type": "task_v2",
"app_url": "https://app.skyvern.com/runs/wr_486306851394503262",
"organization_id": "o_485917350850524254",
"workflow_run_id": "wr_486306851394503262",
"proxy_location": "RESIDENTIAL",
"webhook_callback_url": "https://your-server.com/webhook",
"created_at": "2026-01-20T11:58:57.414123",
"modified_at": "2026-01-20T12:00:31.513449",
"queued_at": "2026-01-20T11:58:57.607233",
"started_at": "2026-01-20T11:58:59.395028",
"finished_at": "2026-01-20T12:00:31.512692"
}
```
</CodeGroup>
**Common fields (both polling and webhook):**
| Field | Type | Description |
|-------|------|-------------|
| `run_id` | string | Unique identifier for this run |
| `status` | string | Current status: `queued`, `running`, `completed`, `failed`, `terminated`, `timed_out`, `canceled` |
| `output` | object \| null | Extracted data from the task |
| `downloaded_files` | array | Files downloaded during execution |
| `recording_url` | string \| null | Video recording of the browser session |
| `screenshot_urls` | array \| null | Screenshots captured (latest first) |
| `failure_reason` | string \| null | Error message if the run failed |
| `errors` | array | List of errors encountered |
| `step_count` | integer \| null | Number of steps executed |
| `run_type` | string | Type of run: `task_v2`, `openai_cua`, `anthropic_cua` |
| `app_url` | string | Link to view this run in Skyvern Cloud |
| `created_at` | datetime | When the run was created |
| `modified_at` | datetime | When the run was last updated |
| `queued_at` | datetime \| null | When the run entered the queue |
| `started_at` | datetime \| null | When execution began |
| `finished_at` | datetime \| null | When execution completed |
**Polling-only fields:**
| Field | Type | Description |
|-------|------|-------------|
| `run_request` | object | Original request parameters (prompt, url, engine, etc.) |
| `browser_session_id` | string \| null | ID of the browser session used |
| `browser_profile_id` | string \| null | ID of the browser profile used |
| `max_screenshot_scrolls` | integer \| null | Number of scrolls for screenshots |
| `script_run` | object \| null | Script run result if AI fallback triggered |
**Webhook-only fields:**
| Field | Type | Description |
|-------|------|-------------|
| `task_id` | string | Same as `run_id` |
| `summary` | string | AI-generated description of what was done |
| `prompt` | string | The prompt from the original request |
| `url` | string | The URL from the original request |
| `organization_id` | string | Your organization ID |
| `workflow_run_id` | string | Associated workflow run ID |
| `proxy_location` | string | Proxy location used (e.g., `RESIDENTIAL`) |
| `webhook_callback_url` | string | The webhook URL that received this payload |
### Artifacts
Every run captures recordings, screenshots, and logs. See [Using Artifacts](/developers/debugging/using-artifacts) for retrieval and the full artifact type reference.
---
<Note>
For multi-step automations that chain multiple actions, see [Browser Automation](/developers/browser-automations/overview).
</Note>
@@ -0,0 +1,141 @@
---
title: Your First Task
slug: cloud/run-your-first-task
subtitle: Run a browser automation from start to finish
description: Follow a step-by-step tutorial to run your first browser automation task in the Skyvern Cloud UI, from writing a prompt to viewing extracted results.
keywords:
- first task
- tutorial
- discover page
- prompt
- extracted data
- live viewer
---
Let's run a real automation. You'll tell Skyvern to visit a website, extract data, and return it as JSON. Then watch the entire thing happen live.
## Step 1: Write your prompt
Open [app.skyvern.com](https://app.skyvern.com) and you'll land on the **Discover** page.
<img src="/images/cloud/skyvern-cloud-discover.png" alt="Discover page with a prompt entered" />
The Discover page has a single input field. Type your instructions and include the target URL in the same prompt. For this example, enter:
```
Get the title of the #1 post on the front page for https://news.ycombinator.com
```
That's it. Skyvern parses the URL and figures out how to navigate the page and extract the data.
Below the input, you'll see quick-action chips like "Add a product to cart" and "What's the top post on hackernews". Click any of these to try a pre-filled example instead.
<Tip>
The more specific your prompt, the better. "Get the title of the #1 post" works much better than "get some data." Include the exact fields you want, what success looks like, and any constraints.
</Tip>
## Step 2: Pick an engine and run
Next to your prompt, you'll see an engine selector. Click it to switch engines:
| Engine | When to use it |
|--------|---------------|
| **Skyvern 1.0** | Tasks with a simple, single goal: filling a form, searching for information on Google, reading content from a page |
| **Skyvern 2.0** | Complex, multi-step tasks. Scores state-of-the-art 85.85% on the WebVoyager benchmark |
| **Skyvern 2.0 with Code** | The default engine. Same capabilities as Skyvern 2.0, plus auto-generates reusable code and a workflow from the run |
For this example, keep the default **Skyvern 2.0 with Code** selected.
Click the **send button** (arrow icon to the right of the input). Skyvern generates a workflow from your prompt and opens it in the workflow editor. Click **Run** in the top right, confirm the parameters, then click **Run workflow** to start execution.
<Accordion title="Optional: Advanced settings">
Click the **gear icon** next to send to configure additional options before running:
| Setting | What it does |
|---------|-------------|
| **Webhook Callback URL** | Endpoint to receive the extracted data when the run completes |
| **Proxy Location** | Route Skyvern through one of the available proxies |
| **Browser Session ID** | Reuse a persistent browser session to keep login state |
| **CDP Address** | Connect to your own browser via Chrome DevTools Protocol |
| **2FA Identifier** | Identifier for a 2FA code to handle two-factor auth automatically |
| **Extra HTTP Headers** | Custom HTTP request headers (dict format) |
| **Generate Script** | Auto-generate reusable scripts from a successful run |
| **Publish Workflow** | Create a workflow alongside this task run |
| **Max Steps Override** | Cap the number of steps the AI can take |
| **Data Schema** | Define structured JSON output format |
| **Max Screenshot Scrolls** | Limit scrolls for post-action screenshots (default: 3) |
These are all optional. The defaults work for most tasks.
</Accordion>
## Step 3: Watch the live browser
This is where it gets interesting. Once the task starts, you'll see the run detail page with a live view of the browser:
<img src="/images/cloud/discover-prompt-in-process.png" alt="Run detail page showing a live browser navigating Hacker News" />
On the left, a **live browser view**. You'll see pages load, elements highlight, and actions fire.
On the right, the **agent log**. A running stream of the AI's Thoughts, Decisions, and block executions. If something goes wrong, this is where you'll figure out why.
## Step 4: Review the results
When the task finishes, the status badge flips to **completed** and the extracted data appears at the top of the page.
<img src="/images/cloud/discover-workflow-completed.png" alt="Completed run showing extracted data and result tabs" />
### Extracted data
The **Extracted Information** block shows your results as structured JSON:
```json
[
{
"top_post_title": "Don't rent the cloud, own instead"
}
]
```
Your result will differ, since the #1 post changes constantly. The structure is what matters.
The agent log on the right confirms what happened. You'll see a final Thought summarizing the result.
### Tabs
Below the extracted data, five tabs give you different views of the run:
- **Overview**: The AI's reasoning timeline alongside browser screenshots. Each Thought, Block, and Action card shows what the agent saw and why it acted.
- **Output**: The complete JSON output and any downloaded files.
- **Parameters**: The exact configuration that was submitted (URL, prompt, engine, schema). Useful for reproducing or tweaking the run.
- **Recording**: Full video replay of the browser session, start to finish.
- **Code**: Auto-generated Python code to reproduce this task via the API or SDK.
## Try something bigger
Now that you've seen the basic flow, here are a few ideas to try next:
- **Fill a form**: Point Skyvern at a contact form and tell it what to enter in each field
- **Compare prices**: Extract product names and prices from an e-commerce page using a data schema
- **Navigate a flow**: Use Skyvern 2.0 to walk through a multi-page checkout or signup process
- **Use an Agent template**: Check the **Agents** section in the sidebar for pre-built automations you can run instantly
---
## Next steps
<CardGroup cols={2}>
<Card
title="Run a Task via API"
icon="code"
href="/running-automations/run-a-task"
>
Trigger automations programmatically with the Skyvern API
</Card>
<Card
title="Core Concepts"
icon="book"
href="/developers/getting-started/core-concepts"
>
Understand tasks, workflows, and other building blocks
</Card>
</CardGroup>
@@ -0,0 +1,138 @@
---
title: Credentials Overview
subtitle: Securely store login details, payment info, and secrets for your automations
description: Securely store passwords, credit cards, and secrets in the Skyvern Cloud UI Credentials page, with encrypted-at-rest vault storage and just-in-time injection during browser automation.
slug: cloud/managing-credentials/credentials-overview
keywords:
- vault
- encrypted
- password
- credit card
- secret
- Bitwarden
- 1Password
- Azure Key Vault
---
The **Credentials** page stores sensitive values (passwords, payment cards, and secrets) so your workflows can use them without embedding secrets in prompts or parameters. Skyvern stores credentials by default with no external service required.
<img src="/images/cloud/credentials-overview.png" alt="Credentials page overview" />
## How Skyvern keeps credentials secure
Sensitive credential data never reaches the LLM, logs, or API responses.
<Steps>
<Step title="Encrypted at rest">
When you save a credential, the sensitive data (passwords, card numbers, CVVs, and TOTP secrets) is sent to a secure vault that provides encryption at rest. Skyvern supports multiple vault backends: Bitwarden, 1Password, Azure Key Vault, and custom webhook providers. Skyvern's own database stores only non-sensitive metadata: credential name, username, card last four digits, card brand, TOTP method, and similar identifiers. Passwords, full card numbers, CVVs, and TOTP secrets are stored exclusively in the vault.
</Step>
<Step title="Placeholders during execution">
When a workflow runs, the LLM receives only placeholder IDs like `placeholder_Xk9m_password`. The AI decides *where* to type on the page, but never sees the real values. No third party, including the LLM provider, ever accesses your actual credentials.
</Step>
<Step title="Just-in-time injection">
At the browser level, the automation layer resolves placeholders to real values and types them directly into the page. After execution, credential values that appear in HTTP Request block responses, block context snapshots, and conditional evaluation outputs are automatically masked before storage.
</Step>
</Steps>
---
## Quick start
<Steps>
<Step title="Navigate to the Credentials page">
Click **Credentials** in the left sidebar under **General**.
<img src="/images/cloud/credentials-sidebar-nav.png" alt="Credentials option in the left sidebar under General" />
</Step>
<Step title="Click + Add">
Choose the credential type: **Password**, **Credit Card**, or **Secret**.
<img src="/images/cloud/credentials-add-dropdown.png" alt="Add dropdown showing Password, Credit Card, and Secret options" />
</Step>
<Step title="Fill in the details and save">
Enter the required fields and click **Save**. The credential is immediately available for use in workflows.
</Step>
</Steps>
---
## What you can store
<CardGroup cols={3}>
<Card
title="Password Credentials"
icon="key"
href="/cloud/managing-credentials/password-credentials"
>
Username, password, and optional 2FA configuration for automated logins
</Card>
<Card
title="Credit Card Credentials"
icon="credit-card"
href="/cloud/managing-credentials/credit-card-credentials"
>
Payment card details for purchase and checkout workflows
</Card>
<Card
title="Secret Credentials"
icon="file-shield"
href="#secret-credentials"
>
A single sensitive string such as an API key, bearer token, or any value you don't want hardcoded
</Card>
</CardGroup>
Password and Credit Card credentials have their own pages. Secrets are simpler and documented here.
### Secret credentials
Secrets store a single sensitive value (an API key, bearer token, or similar). Create one from **+ Add → Secret**, give it a name and value, then reference it in HTTP Request, Code, or Workflow Trigger blocks using the credential parameter's key:
```
{{ parameter_key.secret_value }}
```
Replace `parameter_key` with the **key** assigned to the credential parameter in the workflow editor (e.g., `credentials`, `credentials_1`).
---
## Using credentials in workflows
The most common pattern is a **Login block**. A Login block is a workflow step that signs into a website using stored credentials. Select a credential from the dropdown, and Skyvern fills in the username, password, and 2FA code (if configured) automatically. See [Block Reference](/cloud/building-workflows/configure-blocks) for details.
For workflows that need different credentials at runtime, add a **Credential parameter** (type: `credential_id`). When someone runs the workflow, they pick which credential to use from a dropdown. See [Workflow Parameters](/cloud/building-workflows/add-parameters) for setup.
---
## Deleting credentials
Click the **trash icon** on any credential row. Deletion is permanent and cannot be undone. If a workflow references a deleted credential, the run will fail during initialization until you assign a replacement.
<CardGroup cols={2}>
<Card
title="Password Credentials"
icon="key"
href="/cloud/managing-credentials/password-credentials"
>
Store logins with optional 2FA
</Card>
<Card
title="Credit Card Credentials"
icon="credit-card"
href="/cloud/managing-credentials/credit-card-credentials"
>
Store payment details for checkout workflows
</Card>
<Card
title="2FA / TOTP Setup"
icon="shield-halved"
href="/cloud/managing-credentials/totp-setup"
>
Configure and manage two-factor authentication
</Card>
<Card
title="External Providers"
icon="vault"
href="/cloud/managing-credentials/external-providers"
>
Connect Bitwarden, 1Password, Azure Key Vault, or a custom API
</Card>
</CardGroup>
@@ -0,0 +1,84 @@
---
title: Credit Card Credentials
subtitle: Store payment details for purchase and checkout workflows
description: Store credit card details securely in the Skyvern Cloud UI for automated checkout and purchase workflows, with encrypted storage and browser-level injection.
slug: cloud/managing-credentials/credit-card-credentials
keywords:
- credit card
- payment
- checkout
- card number
- expiry
- CVV
---
Credit card credentials store payment details so the AI can fill checkout forms without you embedding card numbers in prompts or parameters. Like all credentials, card numbers never reach the LLM. They are injected directly at the browser level.
## Creating a credit card credential
<Steps>
<Step title="Open the Add dialog">
Click **+ Add → Credit Card** from the Credentials page.
</Step>
<Step title="Fill in the card details">
Provide all required fields:
| Field | Description |
|-------|------------|
| **Name** | A label like "Corporate Visa" to identify it later |
| **Cardholder Name** | Name printed on the card |
| **Number** | Full card number (spaces added automatically as you type) |
| **Brand** | Card network: Visa, Mastercard, American Express, Discover, JCB, Diners Club, Maestro, UnionPay, RuPay, or Other |
| **Expiration** | Month and year in `MM/YY` format (slash inserted automatically) |
| **CVV** | 3 or 4 digit security code |
</Step>
<Step title="Save">
Click **Save**. After saving, the card number is masked and only the last four digits are ever shown again.
</Step>
</Steps>
<img src="/images/cloud/credentials-add-credit-card.png" alt="Add Credit Card credential modal" />
<img src="/images/cloud/credentials-credit-card-detail.png" alt="Saved credit card credential showing masked card number" />
## Using credit cards in workflows
Credit cards work with [**Browser Task** and **Browser Action**](/cloud/building-workflows/configure-blocks) blocks that interact with checkout pages. The AI automatically recognizes standard checkout forms and fills card number, name, expiration, and CVV fields with the stored details. No field mapping is required.
For workflows that need different cards at runtime, add a **Credential parameter** (type: `credential_id`) in the [workflow editor](/cloud/building-workflows/add-parameters). When someone runs the workflow, they select which card to use from a dropdown. This lets the same checkout workflow work with different payment methods.
<Note>
If you use 1Password as a credential provider, credit cards require a custom text field named **"Expire Date"**, **"Expiry Date"**, or **"Expiration Date"** in `MM/YYYY` or `MM/YY` format. 1Password does not expose the native expiration field through its API, so Skyvern reads this custom text field instead. See [External Providers](/cloud/managing-credentials/external-providers#1password) for full setup details.
</Note>
## Editing and deleting
<Note>
To edit a credential, click the **pencil icon** on its row. For security, saved card details are never retrieved, so you must re-enter all fields when updating.
</Note>
Click the **trash icon** on any credential row to delete it. Deletion is permanent and cannot be undone.
<CardGroup cols={3}>
<Card
title="Password Credentials"
icon="key"
href="/cloud/managing-credentials/password-credentials"
>
Store login details with optional 2FA
</Card>
<Card
title="External Providers"
icon="vault"
href="/cloud/managing-credentials/external-providers"
>
Connect Bitwarden, 1Password, Azure Key Vault, or a custom API
</Card>
<Card
title="Credentials Overview"
icon="lock"
href="/cloud/managing-credentials/credentials-overview"
>
Security model, quick start, and all credential types
</Card>
</CardGroup>
@@ -0,0 +1,392 @@
---
title: External Credential Providers
subtitle: Connect Bitwarden, 1Password, Azure Key Vault, or your own vault API
description: Connect external credential vaults like Bitwarden, 1Password, Azure Key Vault, or a custom webhook API to the Skyvern Cloud UI so workflows can pull secrets at runtime.
slug: cloud/managing-credentials/external-providers
keywords:
- Bitwarden
- 1Password
- Azure Key Vault
- custom webhook
- vault API
- external provider
- runtime secrets
---
Instead of copying secrets into Skyvern, you can point Skyvern at your existing vault and it pulls credentials at runtime. If your organization already manages secrets in a dedicated vault, connect it as a credential source and reference items directly from workflow parameters.
<Note>
External providers are configured per-organization. Once connected, any workflow in the organization can reference credentials from that provider.
</Note>
## Choosing a provider
| Source | Credential types | Setup | Best for |
|--------|-----------------|-------|----------|
| **Skyvern** (default) | Password, Credit Card, Secret | None (built in) | Most users, fastest setup |
| **Bitwarden** | Password, Credit Card, Identity | Credential parameter config | Teams already using Bitwarden (enterprise) |
| **1Password** | Password, Credit Card | Settings page setup | Teams with 1Password service accounts |
| **Azure Key Vault** | Password (with optional TOTP) | Settings page setup | Enterprise Azure environments |
| **Webhook (Custom API)** | Password, Credit Card | Settings page setup | Organizations with custom vaults |
You can mix sources within the same workflow. For example, one Login block can use Skyvern-stored credentials while another uses Azure Key Vault.
---
## Bitwarden
<Note>
Bitwarden integration is available on the **enterprise plan**. Contact [sales@skyvern.com](mailto:sales@skyvern.com) for access.
</Note>
Works with hosted Bitwarden and the self-hosted [Vaultwarden](https://github.com/dani-garcia/vaultwarden) fork. Supports passwords, credit cards, and identity data (SSN, address, phone numbers).
<Warning>
Make sure your Bitwarden account is on `bitwarden.com`, not `bitwarden.eu`. The EU instance uses a different API that Skyvern does not currently support.
</Warning>
### Cloud setup
<Steps>
<Step title="Create a Bitwarden Organization">
Log into Bitwarden, navigate to **Admin Console**, and ensure you have an organization created.
</Step>
<Step title="Create a collection to share with Skyvern">
In your organization, click **New → Create a collection**. Name it something identifiable (e.g., "Skyvern Credentials"). Skip this step if you already have a collection ready.
</Step>
<Step title="Configure access with the Skyvern team">
Go to the **Access** tab on your collection. This step requires coordination with the Skyvern enterprise team, who will configure access on their end. Contact [sales@skyvern.com](mailto:sales@skyvern.com) to get started.
</Step>
<Step title="Grab your Collection ID">
Click into the collection and find the collection UUID in the URL bar.
</Step>
<Step title="Add to a workflow">
In the Skyvern workflow editor, click **Parameters → Add Parameter → Credential Parameter** and select the **Bitwarden** tab. Enter your **Collection ID** and optionally an **Item ID** to target a specific vault item.
</Step>
</Steps>
### Configuration options
| Field | Description |
|-------|------------|
| **Collection ID** | The UUID of your Bitwarden collection (found in the URL when viewing the collection) |
| **Item ID** | Target a specific vault item. Leave blank to use URL matching instead. |
| **URL Parameter Key** | Match credentials by the target URL. Useful when the same workflow runs against different sites. |
### Identity data
For identity fields (SSN, address, phone numbers), specify an **Identity Key** and a comma-separated list of **Identity Fields** (e.g., `ssn, address, phone`) in the Credential Parameter configuration panel.
<Accordion title="Self-hosted Bitwarden (Vaultwarden)">
Skyvern integrates with self-hosted Bitwarden-compatible services like Vaultwarden using the Bitwarden CLI server as a bridge:
```text
Skyvern → bw serve (CLI Server) → Vaultwarden
```
**Environment variables:**
```bash
# Skyvern Bitwarden Configuration
SKYVERN_AUTH_BITWARDEN_ORGANIZATION_ID=your-org-id-here
SKYVERN_AUTH_BITWARDEN_MASTER_PASSWORD=your-master-password-here
SKYVERN_AUTH_BITWARDEN_CLIENT_ID=user.your-client-id-here
SKYVERN_AUTH_BITWARDEN_CLIENT_SECRET=your-client-secret-here
# Vaultwarden Configuration
BW_HOST=https://your-vaultwarden-server.com
BW_CLIENTID=${SKYVERN_AUTH_BITWARDEN_CLIENT_ID}
BW_CLIENTSECRET=${SKYVERN_AUTH_BITWARDEN_CLIENT_SECRET}
BW_PASSWORD=${SKYVERN_AUTH_BITWARDEN_MASTER_PASSWORD}
# CLI Server Configuration
BITWARDEN_SERVER=http://localhost
BITWARDEN_SERVER_PORT=8002
```
Start the CLI server with Docker Compose:
```bash
docker-compose up -d bitwarden-cli
```
Verify it's running:
```bash
curl http://localhost:8002/status
```
</Accordion>
---
## 1Password
Connects via a [service account token](https://developer.1password.com/docs/service-accounts/get-started/). A service account is an API-only identity that accesses vault items without a human login. Supports passwords and credit cards.
### One-time setup
<Steps>
<Step title="Create a service account">
In your 1Password admin console, go to **Developer > Service Accounts** and create a new service account. Grant it access to the vault that contains the credentials Skyvern needs.
</Step>
<Step title="Open Settings">
In Skyvern, go to **Settings** and find the **1Password** card.
</Step>
<Step title="Enter your service account token">
Paste the service account token from the previous step.
</Step>
<Step title="Save and verify">
Click **Update**. The status indicator turns **Active** once the token is validated.
</Step>
</Steps>
<Tip>
If the status does not turn Active, verify that your service account token has access to the target vault and has not expired.
</Tip>
### Using in a workflow
In the workflow editor, add a **Credential Parameter** and select **1Password** as the source. Provide the **Vault ID** and **Item ID**. You can find both IDs in the URL when viewing an item in the 1Password web app.
<Warning>
Credit cards from 1Password need a custom text field named **"Expire Date"**, **"Expiry Date"**, or **"Expiration Date"** in `MM/YYYY` or `MM/YY` format. 1Password does not expose the native expiration field through its API, so Skyvern reads this custom text field instead.
</Warning>
---
## Azure Key Vault
Pulls credentials stored as Azure secrets. Supports passwords with optional TOTP.
### One-time setup
<Steps>
<Step title="Open Settings">
Go to **Settings** and find the **Azure** card.
</Step>
<Step title="Enter your Azure credentials">
Provide your **Tenant ID**, **Client ID**, and **Client Secret**.
</Step>
<Step title="Save">
Click **Update**. Skyvern will use these credentials to access your vault.
</Step>
</Steps>
### Using in a workflow
In the workflow editor, add a **Credential Parameter** and select **Azure Key Vault** as the source. Provide the vault name and the **secret names** that store the username, password, and optionally a TOTP secret. Enter the secret names, not the values themselves.
For example, if your vault stores secrets named `salesforce-username`, `salesforce-password`, and `salesforce-totp`, enter those three names in the corresponding fields.
---
## Webhook (Custom API)
Connect your own HTTP API as a credential backend. Skyvern calls your API to create, retrieve, and delete credentials, so sensitive data stays in your infrastructure.
### API contract
Your service must implement three endpoints. All requests include an `Authorization: Bearer {API_TOKEN}` header.
**Create credential**
```http
POST {API_BASE_URL}
Authorization: Bearer {API_TOKEN}
Content-Type: application/json
```
The request body depends on the credential type. Your API must handle all three:
<Accordion title="Password request body">
```json
{
"name": "Salesforce Login",
"type": "password",
"username": "user@example.com",
"password": "secure_password",
"totp": "JBSWY3DPEHPK3PXP",
"totp_type": "authenticator"
}
```
The `totp` and `totp_type` fields are optional. `totp_type` can be `"authenticator"`, `"email"`, `"text_message"`, or `"none"`.
</Accordion>
<Accordion title="Credit card request body">
```json
{
"name": "Corporate Visa",
"type": "credit_card",
"card_holder_name": "Jane Doe",
"card_number": "4111111111111111",
"card_exp_month": "12",
"card_exp_year": "2025",
"card_cvv": "123",
"card_brand": "visa"
}
```
</Accordion>
<Accordion title="Secret request body">
```json
{
"name": "Stripe API Key",
"type": "secret",
"secret_value": "sk_live_abc123",
"secret_label": "api-key"
}
```
The `secret_label` field is optional.
</Accordion>
Response (all types):
```json
{
"id": "cred_123456"
}
```
**Get credential**
```http
GET {API_BASE_URL}/{credential_id}
Authorization: Bearer {API_TOKEN}
```
Return the same fields that were sent during creation (minus `name`). Include `type` so Skyvern knows how to parse the response.
**Delete credential**
```http
DELETE {API_BASE_URL}/{credential_id}
Authorization: Bearer {API_TOKEN}
```
Response: HTTP 200
### Setup
<Steps>
<Step title="Open Settings">
Go to **Settings** and find the **Custom Credential Service** card.
</Step>
<Step title="Enter your API details">
Provide the **API Base URL** and **API Token** for your credential service.
</Step>
<Step title="Save">
Click **Update Configuration**. The status indicator turns **Active** once the configuration is saved.
</Step>
</Steps>
<Accordion title="Example: minimal FastAPI implementation">
```python
from fastapi import FastAPI, HTTPException, Depends, Header
from pydantic import BaseModel
from typing import Optional
import uuid
app = FastAPI()
credentials_store = {}
class CreateCredentialRequest(BaseModel):
name: str
type: str # "password", "credit_card", or "secret"
# Password fields
username: Optional[str] = None
password: Optional[str] = None
totp: Optional[str] = None
totp_type: Optional[str] = None
# Credit card fields
card_holder_name: Optional[str] = None
card_number: Optional[str] = None
card_exp_month: Optional[str] = None
card_exp_year: Optional[str] = None
card_cvv: Optional[str] = None
card_brand: Optional[str] = None
# Secret fields
secret_value: Optional[str] = None
secret_label: Optional[str] = None
class CredentialResponse(BaseModel):
id: str
def verify_token(authorization: str = Header(...)):
if not authorization.startswith("Bearer "):
raise HTTPException(401, "Invalid authorization header")
token = authorization.split("Bearer ")[1]
if token != "your_expected_api_token":
raise HTTPException(401, "Invalid API token")
@app.post("/api/v1/credentials", response_model=CredentialResponse)
async def create_credential(
request: CreateCredentialRequest,
_: None = Depends(verify_token)
):
credential_id = f"cred_{uuid.uuid4().hex[:12]}"
credentials_store[credential_id] = request.model_dump()
return CredentialResponse(id=credential_id)
@app.get("/api/v1/credentials/{credential_id}")
async def get_credential(
credential_id: str,
_: None = Depends(verify_token)
):
if credential_id not in credentials_store:
raise HTTPException(404, "Credential not found")
return credentials_store[credential_id]
@app.delete("/api/v1/credentials/{credential_id}")
async def delete_credential(
credential_id: str,
_: None = Depends(verify_token)
):
if credential_id not in credentials_store:
raise HTTPException(404, "Credential not found")
del credentials_store[credential_id]
return {"status": "deleted"}
```
</Accordion>
<Accordion title="Self-hosted configuration (environment variables)">
For self-hosted Skyvern deployments, set these environment variables instead of using the Settings UI:
```bash
CREDENTIAL_VAULT_TYPE=custom
CUSTOM_CREDENTIAL_API_BASE_URL=https://credentials.company.com/api/v1/credentials
CUSTOM_CREDENTIAL_API_TOKEN=your_api_token_here
```
Restart Skyvern after setting these variables.
</Accordion>
### Troubleshooting
| Problem | What to check |
|---------|--------------|
| Status stays Inactive | Verify the API base URL is a valid URL and the API token is not empty. The configuration is validated on save but does not make a live request to your server. |
| Credentials not created | Review your API logs for auth errors. Ensure the response includes an `id` field. Skyvern expects HTTP 200 for all operations. |
| Credentials not retrieved | Ensure the GET response includes all required fields for the credential type (`username` and `password` for passwords, all card fields for credit cards, `secret_value` for secrets). |
| Env config not working | Restart Skyvern after setting variables. Verify `CREDENTIAL_VAULT_TYPE=custom` is set and both URL and token are provided. The default vault type is `bitwarden`, so this variable must be explicitly set. |
---
<CardGroup cols={3}>
<Card
title="Credentials Overview"
icon="lock"
href="/cloud/managing-credentials/credentials-overview"
>
Built-in credential storage, security model, and quick start
</Card>
<Card
title="Password Credentials"
icon="key"
href="/cloud/managing-credentials/password-credentials"
>
Store login details with optional 2FA
</Card>
<Card
title="Workflow Parameters"
icon="sliders"
href="/cloud/building-workflows/add-parameters"
>
Configure credential parameters in the workflow editor
</Card>
</CardGroup>
@@ -0,0 +1,90 @@
---
title: Password Credentials
subtitle: Store login details and use them in automated sign-in flows
description: Create and manage password credentials in the Skyvern Cloud UI with optional two-factor authentication via TOTP, email, or SMS for automated login workflows.
slug: cloud/managing-credentials/password-credentials
keywords:
- username
- password
- login
- TOTP
- 2FA
- automated sign-in
---
Password credentials store a username, password, and optional 2FA configuration. Reference them from [Login blocks](/cloud/building-workflows/configure-blocks) in your workflows, and Skyvern handles the entire sign-in flow, including entering 2FA codes.
## Creating a password credential
<Steps>
<Step title="Open the Add dialog">
Click **+ Add → Password** from the Credentials page.
</Step>
<Step title="Fill in your login details">
Enter a **Name** (a label like "Salesforce Production"), **Username or Email**, and **Password**. The password field has an eye icon to toggle visibility.
</Step>
<Step title="Configure 2FA (optional)">
Expand the **Two-Factor Authentication** accordion to set up automated 2FA handling. See [below](#adding-two-factor-authentication) for details.
</Step>
<Step title="Save">
Click **Save**. The credential is immediately available for use in workflows.
</Step>
</Steps>
<img src="/images/cloud/credentials-add-password.png" alt="Add password credential modal" />
## Adding two-factor authentication
If the site requires 2FA, expand the **Two-Factor Authentication** accordion below the password fields. Three options, depending on how the site delivers codes:
<img src="/images/cloud/credentials-2fa-setup.png" alt="2FA setup options showing Authenticator App, Email, and Text Message" />
| Method | How it works |
|--------|-------------|
| **Authenticator App** | Paste the TOTP secret key and Skyvern generates codes locally on demand. Fully automated with no delay. Preferred when the site supports it. |
| **Email** | Provide the email address that receives codes. Skyvern waits for you to push the code via the [2FA tab](/cloud/managing-credentials/totp-setup) or API. Identifier auto-fills from the Username field. |
| **Text Message** | Provide the phone number that receives codes. Same push-based flow as Email. |
<Tip>
Authenticator App is always the best option when available. Email and Text require either manual code entry or setting up automatic forwarding.
</Tip>
<Accordion title="Finding your TOTP secret key">
The secret key is the base32-encoded string behind the QR code you'd scan in an authenticator app. Most password managers let you view it:
- **Bitwarden**: Edit the login → TOTP field → copy the key
- **1Password**: Edit the login → One-Time Password → copy the secret
- **LastPass**: Edit the login → Advanced Settings → copy the TOTP secret
- **Site settings**: Many sites show a "Can't scan?" link during 2FA setup that reveals the text key
If you only have a QR code, decode it to extract the `secret=` parameter from the `otpauth://totp/...?secret=BASE32KEY` URI.
</Accordion>
## Using credentials in a workflow
In the Login block configuration, select a stored credential from the dropdown. Skyvern fills in the username and password automatically, and handles 2FA if configured.
## Managing credentials
Stored credentials show the name, credential ID, username (plain text), password (always masked), and 2FA method if configured.
<Note>
To edit a credential, click the **pencil icon** on its row. For security, saved passwords and secrets are never retrieved, so you must re-enter all sensitive fields when updating.
</Note>
<CardGroup cols={2}>
<Card
title="2FA / TOTP Setup"
icon="shield-halved"
href="/cloud/managing-credentials/totp-setup"
>
Push verification codes and manage 2FA for Email and Text methods
</Card>
<Card
title="Block Reference"
icon="cube"
href="/cloud/building-workflows/configure-blocks"
>
Configure Login blocks and other blocks that use credentials
</Card>
</CardGroup>
@@ -0,0 +1,266 @@
---
title: 2FA / TOTP Setup
subtitle: Configure two-factor authentication for automated logins
description: Configure TOTP authenticator app, email, or SMS two-factor authentication for automated logins in the Skyvern Cloud UI, including secret key setup and manual code delivery.
slug: cloud/managing-credentials/totp-setup
keywords:
- TOTP
- 2FA
- authenticator app
- secret key
- email code
- SMS code
- verification
---
Skyvern supports three 2FA methods for automated logins. **Authenticator App (TOTP)** is fully automatic: Skyvern generates codes locally. **Email** and **Text Message** require you to push codes via the UI or API. All three are configured on the [password credential](/cloud/managing-credentials/password-credentials) itself.
## Authenticator App (TOTP)
The preferred method. Skyvern generates valid 6-digit codes on demand during login flows with no delay and no manual steps.
### How it works
1. The Login block enters the username and password
2. The site prompts for a 2FA code
3. Skyvern generates a fresh TOTP code from the stored secret key
4. The code is entered automatically and login completes
### Setting it up
<Steps>
<Step title="Create a password credential">
Go to the Credentials page and create a new password credential.
<img src="/images/cloud/totp-setup-1.png" alt="Credentials page showing password credentials with the Add button highlighted" />
</Step>
<Step title="Expand Two-Factor Authentication">
Below the password fields, click the **Two-Factor Authentication** accordion.
</Step>
<Step title="Select Authenticator App">
Choose **Authenticator App** from the three options.
</Step>
<Step title="Paste your TOTP secret key">
Enter the secret key into the **Authenticator Key** field and click **Save**.
<img src="/images/cloud/totp-setup-2.png" alt="Add Credential dialog with Authenticator App selected and the Authenticator Key field" />
</Step>
</Steps>
<Accordion title="Finding your TOTP secret key">
The secret key is the base32-encoded string behind the QR code you'd normally scan in an authenticator app. You can find it in a few places:
- **Bitwarden**: Edit the login → TOTP field → copy the key
- **1Password**: Edit the login → One-Time Password → copy the secret
- **LastPass**: Edit the login → Advanced Settings → copy the TOTP secret
- **Site settings**: Many sites show a "Can't scan?" link during 2FA setup that reveals the text key
If you only have a QR code, decode it to extract the `secret=` parameter from the `otpauth://totp/...?secret=BASE32KEY` URI.
</Accordion>
---
## Email and Text Message codes
When a site sends 2FA codes via email or SMS, someone (or something) needs to deliver the code to Skyvern before the login can complete.
### How it works
1. The Login block enters the username and password
2. The site sends a 2FA code to the configured email or phone number
3. You push the code to Skyvern via the **2FA tab** or the API
4. Skyvern enters the code and completes the login
### Setting it up
<Steps>
<Step title="Create a password credential">
Go to the Credentials page and create a new password credential.
<img src="/images/cloud/totp-setup-1.png" alt="Credentials page showing password credentials with the Add button highlighted" />
</Step>
<Step title="Expand Two-Factor Authentication">
Below the password fields, click the **Two-Factor Authentication** accordion.
</Step>
<Step title="Select Email or Text Message">
Choose the method that matches how the site delivers codes.
</Step>
<Step title="Enter the identifier">
Provide the **email address** or **phone number** that receives the codes. For Email, this auto-fills from the Username field.
<img src="/images/cloud/totp-setup-3.png" alt="Add Credential dialog with Email selected and the TOTP Identifier field" />
</Step>
</Steps>
---
## Pushing codes to Skyvern
Once a workflow is running and waiting for a 2FA code, you need to deliver it. There are two ways.
### Via the UI
Open the **2FA** tab on the Credentials page. The **Push a 2FA Code** form has two fields:
| Field | What to enter |
|-------|--------------|
| **Identifier** | The email address or phone number that received the code |
| **Verification content** | The full email/SMS body, or just the code itself. Skyvern extracts the digits automatically. |
<img src="/images/cloud/credentials-2fa-push-form.png" alt="2FA tab showing the Push a 2FA Code form and code history table" />
<Tip>
If multiple workflows are running simultaneously, click **Add optional metadata** to link the code to a specific run using the workflow run ID, workflow ID, or task ID.
</Tip>
### Via the API
For production, automate code delivery. Set up a forwarding rule that sends 2FA emails or texts to a script, and the script pushes the code to Skyvern:
<CodeGroup>
```bash cURL
curl -X POST "https://api.skyvern.com/v1/credentials/totp" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"totp_identifier": "user@example.com",
"content": "Your verification code is 847291",
"source": "email_forwarder"
}'
```
```python Python
from skyvern import Skyvern
skyvern = Skyvern(api_key="YOUR_API_KEY")
await skyvern.send_totp_code(
totp_identifier="user@example.com",
content="Your verification code is 847291",
source="email_forwarder",
)
```
```typescript TypeScript
import { SkyvernClient } from "@skyvern/client";
const skyvern = new SkyvernClient({ apiKey: "YOUR_API_KEY" });
await skyvern.sendTotpCode({
totp_identifier: "user@example.com",
content: "Your verification code is 847291",
source: "email_forwarder",
});
```
</CodeGroup>
**Response:**
```json
{
"totp_code_id": "tc_abc123",
"totp_identifier": "user@example.com",
"code": "847291",
"source": "email_forwarder",
"created_at": "2025-01-15T10:30:00Z"
}
```
The `source` field is a free-text label for your own tracking (e.g., `"email_forwarder"`, `"twilio_webhook"`).
To link a code to a specific run, pass `workflow_run_id`, `workflow_id`, or `task_id`. This is the API equivalent of the **Add optional metadata** option in the UI.
<Tip>
This turns email-based 2FA into something nearly as automated as an authenticator app. The main difference is latency while the email arrives and gets forwarded.
</Tip>
---
## Server-fetched codes (totp_url)
Instead of pushing codes to Skyvern, you can have Skyvern pull them from your server. Pass `totp_url` when running a [task](/cloud/getting-started/run-from-code) or [workflow](/cloud/building-workflows/build-a-workflow), and Skyvern will call your endpoint when it needs a verification code.
Your endpoint must accept a POST request with `task_id`, `workflow_run_id`, and `workflow_permanent_id` in the body, and return:
```json
{
"verification_code": "123456"
}
```
Validate the `x-skyvern-signature` header to confirm the request came from Skyvern:
```python
import hashlib, hmac
def validate_skyvern_request(request) -> bool:
signature = request.headers["x-skyvern-signature"]
payload = request.body() # bytes
expected = hmac.new(
SKYVERN_API_KEY.encode("utf-8"),
msg=payload,
digestmod=hashlib.sha256,
).hexdigest()
return signature == expected
```
---
## Magic links (one-time login links)
Some sites use one-time login links instead of numeric codes. Skyvern supports these by splitting the flow into two steps:
1. **Trigger the magic link**: Run a task that initiates the login. The site emails a one-time link.
2. **Use the link**: Monitor the inbox (e.g., via Zapier), extract the URL, then start a new task with that URL as the starting point.
```python
# Step 1: Trigger the magic link email
await client.run_task(
prompt="Click 'Sign in with email link' and enter user@example.com",
url="https://app.example.com/login",
wait_for_completion=True,
)
# Step 2: Your email monitor extracts the magic link URL, then:
await client.run_task(
prompt="Complete the onboarding form after login",
url=magic_link_url, # The one-time URL from the email
wait_for_completion=True,
)
```
The magic link URL becomes the `url` parameter for the second task. Skyvern opens it directly, which logs the user in, and then continues with the rest of the automation.
---
## Viewing past codes
The table below the push form shows all 2FA codes your organization has received: identifier, extracted code, source type, associated workflow run, and timestamps. Filter by identifier, OTP type (numeric code vs. magic link), and number of results per page.
Use this for auditing and debugging: confirming that a code was received and delivered to the right run.
### Listing codes via API
```bash
curl -X GET "https://api.skyvern.com/v1/credentials/totp?totp_identifier=user@example.com&limit=10" \
-H "x-api-key: $SKYVERN_API_KEY"
```
| Parameter | Description |
|-----------|-------------|
| `totp_identifier` | Filter by identifier (email, phone, etc.) |
| `workflow_run_id` | Restrict to a specific workflow run |
| `otp_type` | Filter by `totp` or `magic_link` |
| `limit` | Number of records (default 50, max 200) |
Returns a list ordered newest first. Only codes created within the last 10 minutes (configurable via `TOTP_LIFESPAN_MINUTES`) are returned.
<CardGroup cols={2}>
<Card
title="Password Credentials"
icon="key"
href="/cloud/managing-credentials/password-credentials"
>
Create credentials with 2FA methods attached
</Card>
<Card
title="Credentials Overview"
icon="lock"
href="/cloud/managing-credentials/credentials-overview"
>
Security model, quick start, and all credential types
</Card>
</CardGroup>
@@ -0,0 +1,104 @@
---
title: Downloading Artifacts
subtitle: Access recordings, screenshots, and output files from your runs
description: Download recordings, screenshots, extracted data, and generated code from completed runs in the Skyvern Cloud UI or programmatically via the API.
slug: cloud/viewing-results/downloading-artifacts
keywords:
- download
- recording
- screenshot
- HAR file
- Playwright trace
- generated code
- extracted data
---
Every run generates artifacts: video recordings, screenshots at each decision point, extracted data as JSON, and any downloaded files. Most are visible in the [Run Details](/cloud/viewing-results/run-details) page, but you can also save them locally or pull them into another system.
## From the UI
| Artifact | How to download |
|----------|----------------|
| **Recordings** | Recording tab → right-click the video → **Save video as...** |
| **Screenshots** | Overview tab → click a timeline item → right-click the image → **Save image as...** |
| **Extracted data** | Output tab → select the JSON text and copy |
| **Downloaded files** | Output tab → **Workflow Run Downloaded Files** → click any link |
| **Generated code** | Code tab → **Copy** button in the top right |
## From the API
Use the API when you need artifacts programmatically: for a pipeline, an archive, or integration with another tool.
### List artifacts for a run
```bash
curl -X GET "https://api.skyvern.com/v1/runs/{run_id}/artifacts" \
-H "x-api-key: YOUR_API_KEY"
```
Filter by type using the `artifact_type` parameter (repeatable):
```bash
curl -X GET "https://api.skyvern.com/v1/runs/{run_id}/artifacts?artifact_type=screenshot_llm&artifact_type=recording" \
-H "x-api-key: YOUR_API_KEY"
```
### Download an artifact
Each artifact in the response includes a `signed_url`, a temporary, pre-authenticated download link:
```json
{
"artifact_id": "art_abc123",
"artifact_type": "screenshot_llm",
"signed_url": "https://storage.example.com/screenshot.png?token=...",
"created_at": "2025-01-15T10:30:00Z"
}
```
```bash
curl -o screenshot.png "SIGNED_URL_HERE"
```
<Warning>
Signed URLs expire after a short period. Always generate a fresh URL via the API rather than storing old ones.
</Warning>
### Artifact types
| Value | What it is |
|-------|-----------|
| `recording` | Full browser session video |
| `screenshot_llm` | Screenshots with numbered element annotations (what the AI analyzed) |
| `screenshot_action` | Screenshots taken after each browser action |
| `screenshot_final` | Final page state when the run ended |
| `llm_prompt` | Complete prompt sent to the LLM (goal, element tree, system instructions) |
| `llm_request` | Raw API request payload sent to the model provider |
| `llm_response` | Raw model response |
| `llm_response_parsed` | Parsed action list (what the AI decided to do) |
| `visible_elements_tree` | DOM tree of interactive elements the AI could see (JSON) |
| `html_scrape` | Full page HTML at the time of the step |
| `skyvern_log` | Formatted execution logs |
| `har` | HTTP Archive file (every network request the browser made) |
| `trace` | Browser trace file for performance analysis |
<Tip>
The annotated screenshots (`screenshot_llm`) and parsed action lists (`llm_response_parsed`) are the most useful for debugging. Annotated screenshots show which elements the AI identified, and the action list shows what it decided to do with them.
</Tip>
<CardGroup cols={2}>
<Card
title="Run Details"
icon="magnifying-glass"
href="/cloud/viewing-results/run-details"
>
Understand what each tab shows and how to debug failures
</Card>
<Card
title="Using Artifacts (API)"
icon="code"
href="/developers/debugging/using-artifacts"
>
Full API reference for artifact retrieval
</Card>
</CardGroup>
+127
View File
@@ -0,0 +1,127 @@
---
title: Run Details
subtitle: Inspect actions, outputs, recordings, and parameters for any run
description: Inspect the details of any task or workflow run in the Skyvern Cloud UI, including AI reasoning timelines, extracted data, recordings, screenshots, and parameters.
slug: cloud/viewing-results/run-details
keywords:
- step timeline
- AI reasoning
- extracted data
- recording
- screenshot
- parameters
- action log
---
Every run has a detail page showing what the AI saw, what it decided, what it extracted, and whether anything went wrong. Click any run in [Run History](/cloud/viewing-results/run-history) to get here.
<img src="/images/cloud/task-run-details.png" alt="Run details page showing a completed workflow run" />
## The header
The top of the page shows the workflow title, a color-coded status badge, and the run ID. Three buttons on the right:
- **API & Webhooks**: the exact API request that would reproduce this run, including endpoint, headers, and payload
- **Edit**: jump to the workflow editor
- **Rerun**: start a new run pre-filled with the same parameters (appears after the run finishes)
While a run is in progress, a **Cancel** button appears instead of Rerun.
<img src="/images/cloud/workflow-run-timeline.png" alt="A running workflow with live browser view and timeline" />
## Extracted information
On success, the **Extracted Information** section appears above the tabs, showing the structured data you asked for, displayed as JSON.
<img src="/images/cloud/task-run-results.png" alt="Workflow Run Outputs showing extracted JSON data" />
The output includes a `summary` (natural language description of what was accomplished), `extracted_information` (structured data matching your schema), and a `failure_reason` field that's `null` on success. On failure, a **Failure Reason** section appears instead with error details in a red box.
## The five tabs
### Overview
The left panel shows the browser state (live stream while running, screenshots after completion). The right panel shows the AI's reasoning timeline.
<img src="/images/cloud/task-run-actions-tab.png" alt="Overview tab showing browser screenshot and AI reasoning timeline" />
The timeline is a chronological feed of three card types:
| Card | What it shows |
|------|--------------|
| **Thought** | The AI's internal reasoning: what it sees, what it plans to do, and why. Tagged with "Decision." |
| **Block** | When a workflow block starts or finishes (e.g., "Extraction"). Green checkmark = success. |
| **Action** | Individual browser operations (e.g., "#1 Extract Data") with a description of what was done. |
Click any timeline item to see its corresponding screenshot in the left panel. The **Actions** and **Steps** counters at the top give you a quick sense of how much work the run involved.
<Tip>
When a run produces wrong results, start with the Thought cards. Read the AI's reasoning to find where it went off track, such as a misidentified element, or a premature "goal met" conclusion.
</Tip>
### Output
All output data in one place. **Workflow Run Outputs** shows the complete JSON with line numbers and syntax highlighting. **Workflow Run Downloaded Files** lists any files the workflow downloaded; click to download directly.
### Parameters
The configuration that produced this run: workflow input parameters (key-value pairs), webhook URL, proxy location, and HTTP headers. Use this to verify a run received the right inputs or to recreate a past result.
When you select a block in the Overview timeline, this tab also shows that block's configuration: prompt, URL, schema, and other settings.
### Recording
Full video replay of the browser session. Every run is recorded automatically. Scrub through to see exactly what appeared on screen at any point.
<Note>
If the run was canceled before the browser started, you'll see a "No recording available" message.
</Note>
### Code
Python code generated from the run. This tab appears when code generation is enabled (the default engine). Copy the code to run outside Skyvern, or click **Copy & Explain** for an AI-generated explanation.
<img src="/images/cloud/workflow-run-code-tab.png" alt="Code tab showing generated Python code with syntax highlighting" />
If the workflow uses cached code, a **Cache Key selector** lets you switch between versions.
## Debugging failed runs
Work through these in order:
1. **Read the Failure Reason** at the top. It usually tells you what happened: timeout, navigation error, or missing element.
2. **Walk the Thought cards** in the Overview timeline. Find the point where the AI made an incorrect assumption about page state.
3. **Check the Parameters tab** to confirm inputs were correct. A wrong URL or missing parameter is a common cause.
4. **Watch the Recording** to see what actually happened. Popups, CAPTCHAs, and unexpected page layouts are often obvious on video.
## Run statuses
| Status | Meaning |
|--------|---------|
| `created` | Initialized, waiting to be queued |
| `queued` | Waiting for an available browser slot |
| `running` | Actively executing; browser stream is live |
| `completed` | Finished successfully |
| `failed` | Stopped due to an error |
| `terminated` | Stopped by the system (e.g., resource limits) |
| `canceled` | Stopped by you via the Cancel button |
| `timed_out` | Exceeded the configured time limit |
While a run is in progress, the status badge updates automatically, the Overview tab shows a live browser stream, and the timeline grows as new items complete.
<CardGroup cols={2}>
<Card
title="Downloading Artifacts"
icon="download"
href="/cloud/viewing-results/downloading-artifacts"
>
Access recordings, screenshots, and output files
</Card>
<Card
title="Watching Live Execution"
icon="eye"
href="/cloud/getting-started/monitor-a-run"
>
Monitor and take control of running tasks
</Card>
</CardGroup>
@@ -0,0 +1,82 @@
---
title: Run History
subtitle: Find, filter, and inspect past task and workflow executions
description: Search, filter, and inspect past task and workflow runs in the Skyvern Cloud UI Runs page, including filtering by status, trigger type, and run parameters.
slug: cloud/viewing-results/run-history
keywords:
- filter
- search
- status
- trigger type
- pagination
- past runs
---
The **Runs** page shows every task and workflow execution, sorted newest-first. Use it to check on past runs, find failures, or verify that a scheduled workflow completed.
<img src="/images/cloud/run-history-overview.png" alt="Run History page overview" />
## Finding a specific run
**Search** narrows the list by run ID or workflow parameter value. Type part of an ID (e.g., `wr_49338`) or a parameter you passed (like a URL), and matching results appear as you type.
<img src="/images/cloud/run-history-search.png" alt="Searching for a run by ID" />
**Filter by Status** opens a multi-select dropdown. Check one or more statuses to narrow results; `failed` and `timed_out` together show everything that went wrong. Filters and search can be combined: search for a parameter value while filtering to only failed runs.
Available statuses: **Created**, **Queued**, **Running**, **Completed**, **Failed**, **Terminated**, **Canceled**, **Timed Out**.
## Reading the table
Each row is one run. The columns:
| Column | What it shows |
|--------|--------------|
| **Run ID** | Workflow run (`wr_...`) or task (`tsk_...`) identifier. Hover for the full ID. |
| **Detail** | Workflow title or task description. A lightning bolt icon means code generation was used. |
| **Status** | Color-coded badge: green (completed), yellow (running/queued/created), red (failed/timed_out), orange (terminated/canceled). |
| **Trigger** | How the run was started: **Manual**, **API**, or **Scheduled** (calendar icon). |
| **Created At** | Start time in your local timezone. Hover for UTC. |
Workflow runs have a **settings icon** in the last column. Click it to expand the row and see the parameters passed to that run. If your search matches something inside the parameters, the row auto-expands so you can see the match in context.
## Trigger type
Every run has a trigger type that indicates how it was started:
| Trigger type | Description |
|-------------|-------------|
| **Manual** | Started by clicking **Run** in the Cloud UI |
| **API** | Started via the REST API or SDK |
| **Scheduled** | Started automatically by a [schedule](/cloud/building-workflows/scheduling) |
Scheduled runs display a **calendar icon badge** next to the run ID. Click the run to see the schedule name and cron expression in the run details.
### Filtering by trigger type
Use the **Trigger Type** dropdown filter to show only runs of a specific type. For example, select **Scheduled** to see all runs triggered by cron schedules. This filter can be combined with the status filter and search.
---
## Opening a run
Click any row to jump to its [detail page](/cloud/viewing-results/run-details). Hold **Ctrl** (or **Cmd** on Mac) to open in a new tab.
Pagination controls at the bottom let you adjust the page size (5, 10, 20, or 50 items) and navigate between pages. Settings are stored in the URL, so you can bookmark a filtered view or share it with a teammate.
<CardGroup cols={2}>
<Card
title="Run Details"
icon="magnifying-glass"
href="/cloud/viewing-results/run-details"
>
Inspect actions, outputs, recordings, and parameters for any run
</Card>
<Card
title="Downloading Artifacts"
icon="download"
href="/cloud/viewing-results/downloading-artifacts"
>
Save recordings, screenshots, and output files
</Card>
</CardGroup>
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
+96
View File
@@ -0,0 +1,96 @@
---
title: Overview
subtitle: End-to-end workflow examples for common automation scenarios
description: Production-ready cookbook examples for Skyvern browser automation including bulk invoice downloading, job application filling, and healthcare portal data extraction.
slug: cookbooks/overview
keywords:
- cookbook
- example
- tutorial
- end-to-end
- production-ready
- use case
---
Cookbooks are complete, production-ready workflow examples that demonstrate how to use Skyvern Browser Automation agent in real-world use-cases.
Each cookbook walks through the workflow step-by-step, explaining design decisions and showing you how to adapt it for your use case.
---
## Available cookbooks
<CardGroup cols={1}>
<Card
title="Bulk Invoice Downloader"
icon="file-invoice-dollar"
href="/cookbooks/bulk-invoice-downloader"
>
Download invoices from vendor portals, parse PDFs to extract amounts, and email a summary with attachments.
</Card>
<Card
title="Job Applications Pipeline"
icon="briefcase"
href="/cookbooks/job-application-filler"
>
Search for jobs on any portal, extract listings, generate tailored answers with AI, and submit applications automatically.
</Card>
<Card
title="Healthcare Portal Data Extraction"
icon="hospital-user"
href="/cookbooks/healthcare-portal-data"
>
Extract patient demographics and billing data from EHR portals like OpenEMR using residential proxies and browser profiles.
</Card>
</CardGroup>
---
## Getting your API key
All cookbooks require a Skyvern API key. Here's how to get one:
<Steps>
<Step title="Create an account">
Sign up at [app.skyvern.com](https://app.skyvern.com) or log in to your existing account.
</Step>
<Step title="Go to Settings">
Click **Settings** in the left sidebar, then copy your **API Keys**.
<Frame>
<img src="/images/get-api-key.png" alt="API Keys settings page" />
</Frame>
</Step>
<Step title="Set your environment variable">
Set the `SKYVERN_API_KEY` environment variable in your shell.
```bash
export SKYVERN_API_KEY="your-api-key"
```
Or add it to your `.env` file:
```bash
SKYVERN_API_KEY=your-api-key
```
</Step>
</Steps>
---
## Other Resources
If you're new to Skyvern workflows, start with these foundational guides:
<CardGroup cols={2}>
<Card
title="Build a Workflow"
icon="hammer"
href="/cloud/building-workflows/build-a-workflow"
>
Learn workflow basics: parameters, blocks, and data passing
</Card>
<Card
title="Workflow Blocks Reference"
icon="cube"
href="/cloud/building-workflows/configure-blocks"
>
Complete reference for all block types
</Card>
</CardGroup>
@@ -0,0 +1,860 @@
---
title: Actions Reference
subtitle: Every page action and agent method
description: Reference for all page actions (act, extract, validate, prompt, click, fill, select_option) and agent methods (login, run_task, download_files, run_workflow) with parameters and return types.
slug: developers/browser-automations/actions-reference
keywords:
- act
- extract
- validate
- prompt
- click
- fill
- select_option
- agent.login
- agent.run_task
- agent.download_files
- agent.run_workflow
- fill_form
- locator
- frame_switch
---
Browser automations are built in code using three layers: Page (AI-enhanced Playwright), Agent (multi-step AI goals), and Browser (cloud Chromium instance). This page lists every operation available on a Page or through an Agent. For the full SDK documentation with all parameter options, see the [SDK Reference](/sdk-reference/browser-automation/act).
If you're building automations visually instead, see [Block Types and Configuration](/cloud/building-workflows/configure-blocks) for the equivalent operations in the Cloud UI workflow editor.
---
## Quick reference
### Page actions
| Action | Purpose | Returns |
|--------|---------|---------|
| [`act`](#act) | Perform any action from a natural-language prompt | `None` |
| [`extract`](#extract) | Pull structured data from the page | `dict`, `list`, `str`, or `None` |
| [`validate`](#validate) | Assert a condition about the page | `bool` |
| [`prompt`](#prompt) | Ask the LLM a question about the page | `dict`, `list`, `str`, or `None` |
| [`click`](#click) | Click an element (selector, AI, or both) | `str \| None` |
| [`fill`](#fill) | Fill an input field (selector, AI, or both) | `str` |
| [`select_option`](#select_option) | Select a dropdown option (selector, AI, or both) | `str \| None` |
| [`type`](#type) | Type text character-by-character (Python only) | `str` |
| [`hover`](#hover) | Move mouse over an element (Python only) | `str` |
| [`scroll`](#scroll) | Scroll the page by pixel offset (Python only) | `None` |
| [`upload_file`](#upload_file) | Upload files to a file input (Python only) | `str` |
| [`locator`](#locator) | Locate an element with AI, returns a chainable Locator (Python only) | `Locator` |
### Agent methods
| Method | Purpose | Returns |
|--------|---------|---------|
| [`agent.login`](#agentlogin) | Authenticate with stored credentials | [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse) |
| [`agent.run_task`](#agentrun_task) | Run a multi-step AI task on the current page | [`TaskRunResponse`](/sdk-reference/tasks/run-task#returns-taskrunresponse) |
| [`agent.download_files`](#agentdownload_files) | Navigate and download files | [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse) |
| [`agent.run_workflow`](#agentrun_workflow) | Run a Cloud UI workflow on the current page | [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse) |
### Form automation (Python only)
| Method | Purpose | Returns |
|--------|---------|---------|
| [`fill_form`](#fill_form) | AI-powered single-page form fill | `None` |
| [`fill_multipage_form`](#fill_multipage_form) | Form fill across multiple pages | `int` (pages filled) |
| [`fill_from_mapping`](#fill_from_mapping) | Fill fields by index-to-value mapping | `None` |
| [`extract_form_fields`](#extract_form_fields) | Extract all form field metadata | `list[dict]` |
| [`validate_mapping`](#validate_mapping) | Check if a field mapping is valid | `bool` |
| [`fill_autocomplete`](#fill_autocomplete) | Fill input with typeahead handling | `str` |
### iframe management (Python only)
| Method | Purpose | Returns |
|--------|---------|---------|
| [`frame_switch`](#frame_switch) | Switch context to an iframe | `dict` |
| [`frame_main`](#frame_main) | Switch back to the main frame | `dict` |
| [`frame_list`](#frame_list) | List all frames on the page | `list[dict]` |
---
## Page actions
### act
Perform any action described in natural language.
<CodeGroup>
```python
await page.act("Click the login button")
await page.act("Scroll down to the pricing section")
```
```typescript
await page.act("Click the login button")
await page.act("Scroll down to the pricing section")
```
</CodeGroup>
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | `str` | Yes | What action to perform |
| `skip_refresh` | `bool` | No | Skip page refresh before acting |
| `use_economy_tree` | `bool` | No | Use a smaller DOM tree for faster processing |
**Returns:** `None`
**SDK reference:** [act](/sdk-reference/browser-automation/act)
---
### extract
Pull structured data from the visible page.
<CodeGroup>
```python
data = await page.extract(
"Extract all product names and prices",
schema={
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {"type": "string"},
"price": {"type": "number"},
},
},
},
)
```
```typescript
const data = await page.extract({
prompt: "Extract all product names and prices",
schema: {
type: "array",
items: {
type: "object",
properties: {
name: { type: "string" },
price: { type: "number" },
},
},
},
})
```
</CodeGroup>
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | `str` | Yes | What to extract |
| `schema` | `dict \| list \| str` | No | JSON Schema for typed output |
| `error_code_mapping` | `dict` | No | Map custom error codes |
**Returns:** `dict`, `list`, `str`, or `None`
**SDK reference:** [extract](/sdk-reference/browser-automation/extract)
---
### validate
Assert a condition about the current page state.
<CodeGroup>
```python
is_logged_in = await page.validate("The user is logged in")
```
```typescript
const isLoggedIn = await page.validate("The user is logged in")
```
</CodeGroup>
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | `str` | Yes | Condition to check |
| `model` | `dict` | No | Override LLM model config |
**Returns:** `bool`
**SDK reference:** [validate](/sdk-reference/browser-automation/validate)
---
### prompt
Ask the LLM a question about the current page.
<CodeGroup>
```python
result = await page.prompt(
"How many items are in the navigation menu?",
schema={"count": {"type": "integer"}}
)
```
```typescript
const result = await page.prompt(
"How many items are in the navigation menu?",
{ schema: { count: { type: "integer" } } }
)
```
</CodeGroup>
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | `str` | Yes | Question to ask |
| `schema` | `dict` | No | JSON Schema for structured response |
| `model` | `dict` | No | Override LLM model config |
**Returns:** `dict`, `list`, `str`, or `None`. Without a `schema`, returns a `dict` of the form `{"llm_response": "..."}` (TypeScript: `{ llmResponse: "..." }`). With a `schema`, returns data shaped to your schema.
**SDK reference:** [prompt](/sdk-reference/browser-automation/prompt)
---
### click
Click an element using a selector, AI prompt, or both.
<CodeGroup>
```python
await page.click("#submit-button") # selector
await page.click(prompt="Click the 'Submit' button") # AI
await page.click("#submit-button", prompt="Click the 'Submit' button") # both
```
```typescript
await page.click("#submit-button") // selector
await page.click({ prompt: "Click the 'Submit' button" }) // AI
await page.click("#submit-button", { prompt: "Click the 'Submit' button" }) // both
```
</CodeGroup>
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `selector` | `str` | No | CSS selector |
| `prompt` | `str` | No | AI prompt (fallback or primary) |
| `ai` | `str` | No | AI mode: `"fallback"` (default) or `None` |
**Returns:** `str \| None` (resolved selector)
**SDK reference:** [click](/sdk-reference/browser-automation/click)
---
### fill
Fill an input field using a selector, AI prompt, or both.
<CodeGroup>
```python
await page.fill("#email", value="user@example.com") # selector
await page.fill(prompt="Fill 'user@example.com' in the email field") # AI
await page.fill("#email", value="user@example.com", prompt="Fill email") # both
```
```typescript
await page.fill("#email", "user@example.com") // selector
await page.fill({ prompt: "Fill 'user@example.com' in the email field" }) // AI
await page.fill("#email", "user@example.com", { prompt: "Fill email" }) // both
```
</CodeGroup>
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `selector` | `str` | No | CSS selector |
| `value` | `str` | No | Value to fill |
| `prompt` | `str` | No | AI prompt (fallback or primary) |
| `ai` | `str` | No | AI mode: `"fallback"` (default) or `None` |
| `totp_identifier` | `str` | No | TOTP identifier for 2FA fields |
| `totp_url` | `str` | No | TOTP URL |
**Returns:** `str` (resolved selector)
**SDK reference:** [fill](/sdk-reference/browser-automation/fill)
---
### select_option
Select a dropdown option using a selector, AI prompt, or both.
<CodeGroup>
```python
await page.select_option("#country", value="us") # selector
await page.select_option(prompt="Select 'United States' from the country dropdown") # AI
await page.select_option("#country", value="us", prompt="Select United States") # both
```
```typescript
await page.selectOption("#country", { value: "us" }) // selector
await page.selectOption({ prompt: "Select 'United States' from the country dropdown" }) // AI
await page.selectOption("#country", { value: "us", prompt: "Select United States" }) // both
```
</CodeGroup>
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `selector` | `str` | No | CSS selector |
| `value` | `str \| list[str]` | No | Option value(s) to select |
| `prompt` | `str` | No | AI prompt (fallback or primary) |
| `ai` | `str` | No | AI mode: `"fallback"` (default) or `None` |
**Returns:** `str | None` (resolved selector)
**SDK reference:** [select_option](/sdk-reference/browser-automation/select-option)
---
### type
Type text character-by-character. Unlike `fill`, this triggers keystroke events for each character, so use it for fields that react to individual key presses (search autocomplete, OTP inputs). Python only.
```python
# Character-by-character input via selector
await page.type("#search", value="wireless headphones")
# AI-powered type
await page.type(prompt="Type 'hello' into the search box")
# Selector with AI fallback
await page.type("#search", value="query text", prompt="Type into the search field")
# TOTP input from a stored secret
await page.type("#otp", totp_identifier="my-app")
# TOTP generated on the fly from an otpauth URI
await page.type("#otp", totp_url="otpauth://totp/Example:alice?secret=JBSWY3DPEHPK3PXP")
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `selector` | `str` | No | CSS or XPath selector for the input field |
| `value` | `str` | No | Text to type character-by-character |
| `prompt` | `str` | No | Natural-language description of the target field |
| `ai` | `str` | No | AI mode: `"fallback"` (default) tries the selector first, then AI |
| `totp_identifier` | `str` | No | Identifier for a stored TOTP secret |
| `totp_url` | `str` | No | `otpauth://` URI to generate a one-time password on the fly |
**Returns:** `str` (resolved selector)
**SDK reference:** [type](/sdk-reference/browser-automation/type)
---
### hover
Move the mouse over an element. Python only.
```python
# Simple hover
await page.hover("#menu-item")
# Hover with a hold duration (useful for tooltip reveals)
await page.hover("#tooltip-trigger", hold_seconds=1.5)
# Hover with intention logging for debugging
await page.hover("#menu-item", intention="Reveal the main menu dropdown")
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `selector` | `str` | Yes | CSS or XPath selector for the target element |
| `timeout` | `float` | No | Max wait time in milliseconds for the element. Defaults to `BROWSER_ACTION_TIMEOUT_MS` |
| `hold_seconds` | `float` | No | How long to hold the hover, in seconds. Default `0.0` |
| `intention` | `str` | No | Description of the hover intent, used for logging |
**Returns:** `str` (resolved selector)
**SDK reference:** [hover](/sdk-reference/browser-automation/hover)
---
### scroll
Scroll the page by a pixel offset along the x and y axes. Python only.
```python
await page.scroll(0, 500) # Scroll down 500px
await page.scroll(0, -300) # Scroll up 300px
await page.scroll(200, 0) # Scroll right 200px
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `scroll_x` | `int` | Yes | Horizontal scroll offset in pixels. Positive values scroll right |
| `scroll_y` | `int` | Yes | Vertical scroll offset in pixels. Positive values scroll down |
**Returns:** `None`
**SDK reference:** [scroll](/sdk-reference/browser-automation/scroll)
---
### upload_file
Upload one or more files to a file input. Pass a selector for direct Playwright behavior, a prompt for AI-powered file input detection, or both. Python only.
```python
# Direct selector
await page.upload_file("#file-input", files="/path/to/file.pdf")
# Multiple files
await page.upload_file("#file-input", files=["/path/to/file1.pdf", "/path/to/file2.pdf"])
# AI-powered file input detection (no selector needed)
await page.upload_file(prompt="Upload the resume to the file input")
# Selector with AI fallback: try the selector first, use AI if it fails
await page.upload_file(
"#file-input",
files="/path/to/file.pdf",
prompt="Upload the resume to the file input",
)
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `selector` | `str` | No | CSS or XPath selector for the file input |
| `files` | `str \| list[str]` | No | File path or list of file paths to upload |
| `prompt` | `str` | No | Natural-language description of the file input to target |
| `ai` | `str` | No | AI mode: `"fallback"` (default) tries the selector first, then AI |
**Returns:** `str` (resolved selector)
**SDK reference:** [upload_file](/sdk-reference/browser-automation/upload-file)
---
### locator
Locate an element using a CSS/XPath selector, an AI prompt, or both. When called with a `prompt`, returns an `AILocator`, a lazy Playwright `Locator` that resolves the element via AI on first use. Python only.
```python
# AI-powered: pass a natural-language prompt
locator = page.locator(prompt="the submit button")
await locator.click()
# Full Playwright chaining works
text = await page.locator(prompt="the error message").text_content()
# Standard Playwright selector (no AI, identical to vanilla Playwright)
locator = page.locator("#submit-btn")
await locator.click()
# Selector with AI fallback: try the selector first, use AI if it fails
locator = page.locator("#submit-btn", prompt="the submit button")
await locator.click()
```
<Note>
When called with only a `selector` (no `prompt`), `page.locator(selector)` behaves exactly like the standard Playwright `page.locator(selector)`. No AI is involved.
</Note>
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `selector` | `str` | No | CSS or XPath selector passed to Playwright's built-in `locator()` |
| `prompt` | `str` | No | Natural-language description of the element. When provided, returns an `AILocator` that resolves via AI |
| `ai` | `str` | No | AI mode: `"fallback"` (default) tries the selector first, then AI |
| `**kwargs` | | No | Additional keyword arguments forwarded to Playwright's `locator()` |
**Returns:** `Locator` (standard Playwright `Locator` when only a selector is given, or `AILocator` when a prompt is provided)
#### AILocator methods
When `prompt` is provided, the returned `AILocator` supports all standard Playwright `Locator` methods:
- **Actions:** `click()`, `fill()`, `type()`, `select_option()`, `check()`, `uncheck()`, `clear()`, `hover()`, `focus()`, `press()`
- **Queries:** `text_content()`, `inner_text()`, `inner_html()`, `get_attribute()`, `input_value()`, `count()`
- **State:** `is_visible()`, `is_hidden()`, `is_enabled()`, `is_disabled()`, `is_editable()`, `is_checked()`
- **Chaining:** `first()`, `last()`, `nth()`, `filter()`, `locator()`, `get_by_text()`, `get_by_role()`, `get_by_label()`, `get_by_placeholder()`
- **Utilities:** `wait_for()`, `screenshot()`, `playwright_locator` (access raw `Locator`)
**SDK reference:** [locator](/sdk-reference/browser-automation/locator)
---
## Agent methods
All agent methods return either a [`TaskRunResponse`](/sdk-reference/tasks/run-task#returns-taskrunresponse) (for `agent.run_task`) or a [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse) (for `agent.login`, `agent.download_files`, `agent.run_workflow`). Follow the links for the full field list.
### agent.login
Authenticate with stored credentials. Handles multi-page login flows, CAPTCHAs, and 2FA.
<CodeGroup>
```python
await page.agent.login(
credential_type="skyvern",
credential_id="cred_123"
)
```
```typescript
await page.agent.login("skyvern", {
credentialId: "cred_123"
})
```
</CodeGroup>
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `credential_type` | `CredentialType` | Yes | `skyvern`, `bitwarden`, `onepassword`, or `azure_vault` |
| `credential_id` | `str` | No | Credential ID (required for `skyvern` type) |
| `url` | `str` | No | Login page URL |
| `prompt` | `str` | No | Additional login instructions |
| `timeout` | `float` | No | Max wait time in seconds (default: 1800) |
**Returns:** [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse)
**SDK reference:** [agent.login](/sdk-reference/browser-automation/agent-login)
---
### agent.run_task
Run a multi-step AI task on the current page.
<CodeGroup>
```python
result = await page.agent.run_task(
"Go to the billing page and download the latest invoice",
data_extraction_schema={
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"amount": {"type": "string"},
},
},
)
print(result.output)
```
```typescript
const result = await page.agent.runTask(
"Go to the billing page and download the latest invoice",
{
dataExtractionSchema: {
type: "object",
properties: {
invoice_number: { type: "string" },
amount: { type: "string" },
},
},
},
)
console.log(result.output)
```
</CodeGroup>
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | `str` | Yes | Multi-step goal description |
| `data_extraction_schema` | `dict \| str` | No | JSON Schema for structured output. See [Extract Structured Data](/developers/browser-automations/extract-structured-data). |
| `max_steps` | `int` | No | Cap AI steps. The run terminates with `timed_out` if hit. Controls cost; each step is one AI decision + action cycle. |
| `engine` | `RunEngine` | No | AI engine. Defaults to `skyvern-1.0` in the SDK for backward compatibility. Pass `skyvern-2.0` for the latest model (also the Cloud UI default). Other options: `openai-cua`, `anthropic-cua`, `ui-tars`. |
| `model` | `dict` / `Record<string, unknown>` | No | Override LLM model configuration |
| `url` | `str` / `string` | No | URL to navigate to (defaults to current page URL) |
| `webhook_url` | `str` / `string` | No | Callback URL. Skyvern POSTs the full run result on completion or failure. See [Webhooks](/developers/going-to-production/webhooks). |
| `totp_identifier` | `str` / `string` | No | Identifier for push-based TOTP. See [Handle 2FA](/developers/credentials/handle-2fa). |
| `totp_url` | `str` / `string` | No | Endpoint Skyvern calls to pull TOTP codes. See [Handle 2FA](/developers/credentials/handle-2fa). |
| `title` | `str` / `string` | No | Display name for this run |
| `error_code_mapping` | `dict` / `Record<string, string>` | No | Map custom error codes to conditions. Keys are your error codes, values describe when to trigger them. If matched, `output` contains `{"error": "your_code"}`. |
| `user_agent` | `str` / `string` | No | Custom User-Agent header for the browser |
| `timeout` | `float` | No | Max wait in seconds (default: 1800) |
**Returns:** [`TaskRunResponse`](/sdk-reference/tasks/run-task#returns-taskrunresponse)
**SDK reference:** [agent.run_task](/sdk-reference/browser-automation/agent-run-task)
---
### agent.download_files
Navigate and download files from the current page.
<CodeGroup>
```python
result = await page.agent.download_files(
"Download the latest invoice PDF",
download_suffix=".pdf",
download_timeout=30,
)
```
```typescript
const result = await page.agent.downloadFiles(
"Download the latest invoice PDF",
{
downloadSuffix: ".pdf",
downloadTimeout: 30,
},
)
```
</CodeGroup>
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | `str` | Yes | What to download |
| `download_suffix` | `str` | No | Filename hint prepended to the saved file (e.g., `"invoice"` → `invoice.pdf`). Not a validator; mismatched extensions don't fail the run. |
| `download_timeout` | `float` | No | Soft hint (seconds) for how long to wait for a download. The overall `timeout` is what actually fails the run. |
| `max_steps_per_run` | `int` | No | Cap AI steps |
| `timeout` | `float` | No | Max wait in seconds (default: 1800) |
**Returns:** [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse)
**SDK reference:** [agent.download_files](/sdk-reference/browser-automation/agent-download-files)
---
### agent.run_workflow
Run a Cloud UI workflow on the current page.
<CodeGroup>
```python
result = await page.agent.run_workflow(
"wpid_monthly_report",
parameters={"month": "2025-03"}
)
```
```typescript
const result = await page.agent.runWorkflow(
"wpid_monthly_report",
{ parameters: { month: "2025-03" } }
)
```
</CodeGroup>
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `workflow_id` | `str` | Yes | Workflow permanent ID |
| `parameters` | `dict` | No | Workflow input parameters |
| `template` | `bool` | No | Run a template workflow |
| `title` | `str` / `string` | No | Display name for this run |
| `webhook_url` | `str` / `string` | No | Callback URL for run completion. See [Webhooks](/developers/going-to-production/webhooks). |
| `totp_url` | `str` / `string` | No | Endpoint for pulling TOTP codes |
| `totp_identifier` | `str` / `string` | No | Identifier for push-based TOTP |
| `timeout` | `float` | No | Max wait in seconds (default: 1800) |
**Returns:** [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse)
**SDK reference:** [agent.run_workflow](/sdk-reference/browser-automation/agent-run-workflow)
---
## Form automation (Python only)
### fill_form
Fill a single-page form using AI. Pass a `data` dict describing the values to fill.
```python
# Simple form fill
await page.fill_form(
data={"name": "John Doe", "email": "john@example.com", "role": "Engineer"},
)
# With a custom prompt to guide the AI
await page.fill_form(
data={"name": "John Doe", "email": "john@example.com"},
prompt="Fill out the registration form with the provided user details",
)
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | `dict[str, Any]` | Yes | Key-value pairs of form data to fill |
| `prompt` | `str` | No | Instruction for the AI. Defaults to `"Fill out the form"` |
**Returns:** `None`
**SDK reference:** [fill_form](/sdk-reference/browser-automation/fill-form)
---
### fill_multipage_form
Fill a form that spans multiple pages, handling page transitions automatically.
```python
pages_filled = await page.fill_multipage_form(
data={"name": "John Doe", "email": "john@example.com", "address": "123 Main St"},
max_pages=5,
)
print(f"Filled {pages_filled} pages")
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | `dict[str, Any]` | Yes | Key-value pairs of form data to fill across all pages |
| `prompt` | `str` | No | Instruction for the AI. Defaults to `"Fill out the form"` |
| `next_button` | `str` | No | Selector or description of the button to advance to the next page |
| `max_pages` | `int` | No | Maximum number of pages to fill. Defaults to `10` |
| `timeout_seconds` | `float` | No | Timeout in seconds for the entire operation. Defaults to `300` |
**Returns:** `int` (the number of pages filled)
**SDK reference:** [fill_multipage_form](/sdk-reference/browser-automation/fill-multipage-form)
---
### fill_from_mapping
Fill form fields using an explicit index-based mapping produced by `extract_form_fields`. Use this when you need precise control over which field gets which value.
```python
fields = await page.extract_form_fields()
await page.fill_from_mapping(
form_fields=fields,
mapping={0: "John", 1: "Doe", 2: "john@example.com"}, # keys are field indices
data={"name": "John Doe"}, # optional context
)
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `form_fields` | `list[dict[str, Any]]` | Yes | Field metadata returned by `extract_form_fields` |
| `mapping` | `dict[int, str \| list \| bool \| None]` | Yes | Map of field index to the value to fill |
| `data` | `dict[str, Any] \| None` | No | Optional source data for context. Defaults to `None` |
**Returns:** `None`
**SDK reference:** [fill_from_mapping](/sdk-reference/browser-automation/fill-from-mapping)
---
### extract_form_fields
Extract all form fields with metadata from the current page. Use the output to drive `fill_from_mapping` or `validate_mapping`.
```python
fields = await page.extract_form_fields()
# Returns a list of dicts with field name, type, options, and other metadata:
# [{"name": "First Name", "type": "text", "index": 0, ...}, ...]
```
**Returns:** `list[dict[str, Any]]` where each dict contains field name, type, options, and other metadata.
**SDK reference:** [extract_form_fields](/sdk-reference/browser-automation/extract-form-fields)
---
### validate_mapping
Check if a field mapping is correct for the current form.
```python
fields = await page.extract_form_fields()
is_valid = await page.validate_mapping(
form_fields=fields,
mapping={0: "John", 1: "Doe"},
prompt="Validate the name fields are filled correctly",
)
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `form_fields` | `list[dict[str, Any]]` | Yes | Field metadata returned by `extract_form_fields` |
| `mapping` | `dict[int, str \| list \| bool \| None]` | Yes | Map of field index to the value to validate |
| `prompt` | `str` | Yes | Instruction describing what to validate |
**Returns:** `bool` (`True` if the mapping is valid, `False` otherwise)
**SDK reference:** [validate_mapping](/sdk-reference/browser-automation/validate-mapping)
---
### fill_autocomplete
Fill an input that has autocomplete/typeahead behavior. Types the value, waits for suggestions, then clicks the matching option.
```python
# Direct selector
await page.fill_autocomplete(
selector="#city",
value="San Francisco",
option_selector=".autocomplete-option",
wait_seconds=1.5,
)
# AI-powered
await page.fill_autocomplete(prompt="Fill 'San Francisco' in the city autocomplete")
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `selector` | `str` | No | CSS selector for the input field |
| `value` | `str` | No | The text value to type into the field |
| `prompt` | `str` | No | Natural-language description of the field and value |
| `ai` | `str` | No | AI mode: `"fallback"` (default) tries the selector first, then AI |
| `option_selector` | `str` | No | CSS selector for the autocomplete dropdown options |
| `wait_seconds` | `float` | No | Seconds to wait for the dropdown to appear. Default `1.5` |
| `**kwargs` | | No | Standard Playwright fill options (e.g., `timeout`, `force`) |
**Returns:** `str` (resolved selector)
**SDK reference:** [fill_autocomplete](/sdk-reference/browser-automation/fill-autocomplete)
---
## iframe management (Python only)
### frame_switch
Switch the working context to an iframe. Exactly one of `selector`, `name`, or `index` must be provided.
```python
# By CSS selector
await page.frame_switch(selector="#payment-iframe")
# By frame name
await page.frame_switch(name="checkout")
# By zero-based index
await page.frame_switch(index=0)
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `selector` | `str` | No | CSS selector for the iframe element |
| `name` | `str` | No | The `name` attribute of the iframe |
| `index` | `int` | No | Zero-based index of the iframe on the page |
<Note>
Exactly one of `selector`, `name`, or `index` must be provided.
</Note>
**Returns:** `dict[str, Any]` (frame metadata for the switched-to iframe)
**SDK reference:** [frame_switch](/sdk-reference/browser-automation/frame-switch)
---
### frame_main
Switch back to the main page frame after working inside an iframe.
```python
page.frame_main()
```
**Returns:** `dict[str, str]`
**SDK reference:** [frame_main](/sdk-reference/browser-automation/frame-main)
---
### frame_list
List all frames on the current page with metadata.
```python
frames = await page.frame_list()
# [{"name": "checkout", "url": "...", "index": 0}, ...]
```
**Returns:** `list[dict[str, Any]]` (metadata for each frame on the page)
**SDK reference:** [frame_list](/sdk-reference/browser-automation/frame-list)
@@ -0,0 +1,717 @@
---
title: Extract Structured Data
subtitle: Get consistent, typed output from your automations
description: Define JSON Schema extraction schemas for Skyvern tasks to get consistent, typed output. Build schemas for single objects or arrays of items with the interactive schema builder.
slug: developers/browser-automations/extract-structured-data
keywords:
- JSON Schema
- extraction schema
- typed output
- schema builder
- array
- object
- string
- number
- boolean
---
import { FIELD_TYPES, SchemaBuilder } from "/snippets/schema-builder.mdx";
When building browser automations in code, you can extract structured data from any page using `page.extract` with a JSON schema, or by passing a `data_extraction_schema` to `page.agent.run_task`. By default, Skyvern returns extracted data in whatever format makes sense for the action. Pass a schema to enforce a specific shape using [JSON Schema](https://json-schema.org/).
If you're using the Cloud UI workflow editor instead, extraction works through the Extract block. See [Block Types and Configuration](/cloud/building-workflows/configure-blocks) for setup.
---
## Define a schema
Pass a JSON Schema object to `page.extract` via the `schema` parameter, or to `run_task` via `data_extraction_schema`:
<Tabs>
<Tab title="page.extract (browser automation)">
<CodeGroup>
```python Python
data = await page.extract(
"Get the title of the top post",
schema={
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "The title of the top post"
}
}
},
)
```
```typescript TypeScript
const data = await page.extract({
prompt: "Get the title of the top post",
schema: {
type: "object",
properties: {
title: {
type: "string",
description: "The title of the top post",
},
},
},
});
```
</CodeGroup>
</Tab>
<Tab title="run_task">
<CodeGroup>
```python Python
result = await client.run_task(
prompt="Get the title of the top post",
url="https://news.ycombinator.com",
data_extraction_schema={
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "The title of the top post"
}
}
}
)
```
```typescript TypeScript
const result = await client.runTask({
body: {
prompt: "Get the title of the top post",
url: "https://news.ycombinator.com",
data_extraction_schema: {
type: "object",
properties: {
title: {
type: "string",
description: "The title of the top post",
},
},
},
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Get the title of the top post",
"url": "https://news.ycombinator.com",
"data_extraction_schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "The title of the top post"
}
}
}
}'
```
</CodeGroup>
</Tab>
</Tabs>
The `description` field in each property helps Skyvern understand what data to extract. Be specific.
<Warning>
`description` fields drive extraction quality. Vague descriptions like "the data" produce vague results. Be specific: "The product price in USD, without currency symbol."
</Warning>
---
## Schema format
Skyvern uses standard JSON Schema. Common types:
| Type | JSON Schema | Example value |
|------|-------------|---------------|
| String | `{"type": "string"}` | `"Hello world"` |
| Number | `{"type": "number"}` | `19.99` |
| Integer | `{"type": "integer"}` | `42` |
| Boolean | `{"type": "boolean"}` | `true` |
| Array | `{"type": "array", "items": {...}}` | `[1, 2, 3]` |
| Object | `{"type": "object", "properties": {...}}` | `{"key": "value"}` |
<Note>
A schema doesn't guarantee all fields are populated. If the data isn't on the page, fields return `null`. Design your code to handle missing values.
</Note>
---
## Build your schema
Use the interactive builder to generate a schema, then copy it into your code.
<SchemaBuilder />
---
## Examples
### Single value
Extract one piece of information, such as the current price of Bitcoin:
<CodeGroup>
```python Python
result = await client.run_task(
prompt="Get the current Bitcoin price in USD",
url="https://coinmarketcap.com/currencies/bitcoin/",
data_extraction_schema={
"type": "object",
"properties": {
"price": {
"type": "number",
"description": "Current Bitcoin price in USD"
}
}
}
)
```
```typescript TypeScript
const result = await client.runTask({
body: {
prompt: "Get the current Bitcoin price in USD",
url: "https://coinmarketcap.com/currencies/bitcoin/",
data_extraction_schema: {
type: "object",
properties: {
price: {
type: "number",
description: "Current Bitcoin price in USD",
},
},
},
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Get the current Bitcoin price in USD",
"url": "https://coinmarketcap.com/currencies/bitcoin/",
"data_extraction_schema": {
"type": "object",
"properties": {
"price": {
"type": "number",
"description": "Current Bitcoin price in USD"
}
}
}
}'
```
</CodeGroup>
**Output (when completed):**
```json
{
"price": 104521.37
}
```
---
### List of items
Extract multiple items with the same structure, such as the top posts from a news site:
<CodeGroup>
```python Python
result = await client.run_task(
prompt="Get the top 5 posts",
url="https://news.ycombinator.com",
data_extraction_schema={
"type": "object",
"properties": {
"posts": {
"type": "array",
"description": "Top 5 posts from the front page",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Post title"
},
"points": {
"type": "integer",
"description": "Number of points"
},
"url": {
"type": "string",
"description": "Link to the post"
}
}
}
}
}
}
)
```
```typescript TypeScript
const result = await client.runTask({
body: {
prompt: "Get the top 5 posts",
url: "https://news.ycombinator.com",
data_extraction_schema: {
type: "object",
properties: {
posts: {
type: "array",
description: "Top 5 posts from the front page",
items: {
type: "object",
properties: {
title: {
type: "string",
description: "Post title",
},
points: {
type: "integer",
description: "Number of points",
},
url: {
type: "string",
description: "Link to the post",
},
},
},
},
},
},
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Get the top 5 posts",
"url": "https://news.ycombinator.com",
"data_extraction_schema": {
"type": "object",
"properties": {
"posts": {
"type": "array",
"description": "Top 5 posts from the front page",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Post title"
},
"points": {
"type": "integer",
"description": "Number of points"
},
"url": {
"type": "string",
"description": "Link to the post"
}
}
}
}
}
}
}'
```
</CodeGroup>
**Output (when completed):**
```json
{
"posts": [
{
"title": "Running Claude Code dangerously (safely)",
"points": 342,
"url": "https://blog.emilburzo.com/2026/01/running-claude-code-dangerously-safely/"
},
{
"title": "Linux kernel framework for PCIe device emulation",
"points": 287,
"url": "https://github.com/cakehonolulu/pciem"
},
{
"title": "I'm addicted to being useful",
"points": 256,
"url": "https://www.seangoedecke.com/addicted-to-being-useful/"
},
{
"title": "Level S4 solar radiation event",
"points": 198,
"url": "https://www.swpc.noaa.gov/news/g4-severe-geomagnetic-storm"
},
{
"title": "WebAssembly Text Format parser performance",
"points": 176,
"url": "https://blog.gplane.win/posts/improve-wat-parser-perf.html"
}
]
}
```
<Tip>
Arrays without limits extract everything visible on the page. Specify limits in your prompt (e.g., "top 5 posts") or the array description to control output size.
</Tip>
---
### Nested objects
Extract hierarchical data, such as a product with its pricing and availability:
<CodeGroup>
```python Python
result = await client.run_task(
prompt="Get product details including pricing and availability",
url="https://www.amazon.com/dp/B0EXAMPLE",
data_extraction_schema={
"type": "object",
"properties": {
"product": {
"type": "object",
"description": "Product information",
"properties": {
"name": {
"type": "string",
"description": "Product name"
},
"pricing": {
"type": "object",
"description": "Pricing details",
"properties": {
"current_price": {
"type": "number",
"description": "Current price in USD"
},
"original_price": {
"type": "number",
"description": "Original price before discount"
},
"discount_percent": {
"type": "integer",
"description": "Discount percentage"
}
}
},
"availability": {
"type": "object",
"description": "Stock information",
"properties": {
"in_stock": {
"type": "boolean",
"description": "Whether the item is in stock"
},
"delivery_estimate": {
"type": "string",
"description": "Estimated delivery date"
}
}
}
}
}
}
}
)
```
```typescript TypeScript
const result = await client.runTask({
body: {
prompt: "Get product details including pricing and availability",
url: "https://www.amazon.com/dp/B0EXAMPLE",
data_extraction_schema: {
type: "object",
properties: {
product: {
type: "object",
description: "Product information",
properties: {
name: {
type: "string",
description: "Product name",
},
pricing: {
type: "object",
description: "Pricing details",
properties: {
current_price: {
type: "number",
description: "Current price in USD",
},
original_price: {
type: "number",
description: "Original price before discount",
},
discount_percent: {
type: "integer",
description: "Discount percentage",
},
},
},
availability: {
type: "object",
description: "Stock information",
properties: {
in_stock: {
type: "boolean",
description: "Whether the item is in stock",
},
delivery_estimate: {
type: "string",
description: "Estimated delivery date",
},
},
},
},
},
},
},
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Get product details including pricing and availability",
"url": "https://www.amazon.com/dp/B0EXAMPLE",
"data_extraction_schema": {
"type": "object",
"properties": {
"product": {
"type": "object",
"description": "Product information",
"properties": {
"name": {
"type": "string",
"description": "Product name"
},
"pricing": {
"type": "object",
"description": "Pricing details",
"properties": {
"current_price": {
"type": "number",
"description": "Current price in USD"
},
"original_price": {
"type": "number",
"description": "Original price before discount"
},
"discount_percent": {
"type": "integer",
"description": "Discount percentage"
}
}
},
"availability": {
"type": "object",
"description": "Stock information",
"properties": {
"in_stock": {
"type": "boolean",
"description": "Whether the item is in stock"
},
"delivery_estimate": {
"type": "string",
"description": "Estimated delivery date"
}
}
}
}
}
}
}
}'
```
</CodeGroup>
**Output (when completed):**
```json
{
"product": {
"name": "Wireless Bluetooth Headphones",
"pricing": {
"current_price": 79.99,
"original_price": 129.99,
"discount_percent": 38
},
"availability": {
"in_stock": true,
"delivery_estimate": "Tomorrow, Jan 21"
}
}
}
```
---
## Accessing extracted data
How you access extracted data depends on which method you used.
### page.extract (browser automation)
`page.extract` returns the extracted data directly as the return value:
<CodeGroup>
```python Python
data = await page.extract(
"Get the top post",
schema={
"type": "object",
"properties": {
"title": {"type": "string", "description": "Post title"},
"points": {"type": "integer", "description": "Points"}
}
},
)
# data is the extracted result directly
print(f"Title: {data['title']}")
print(f"Points: {data['points']}")
```
```typescript TypeScript
const data = await page.extract({
prompt: "Get the top post",
schema: {
type: "object",
properties: {
title: { type: "string", description: "Post title" },
points: { type: "integer", description: "Points" },
},
},
});
// data is the extracted result directly
console.log(`Title: ${data.title}`);
console.log(`Points: ${data.points}`);
```
</CodeGroup>
### run_task (async task)
The extracted data appears in the `output` field of the completed run. Poll until the task reaches a terminal state, then access the output.
<CodeGroup>
```python Python
result = await client.run_task(
prompt="Get the top post",
url="https://news.ycombinator.com",
data_extraction_schema={
"type": "object",
"properties": {
"title": {"type": "string", "description": "Post title"},
"points": {"type": "integer", "description": "Points"}
}
}
)
run_id = result.run_id
while True:
run = await client.get_run(run_id)
if run.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
break
await asyncio.sleep(5)
# Access the extracted data
print(f"Output: {run.output}")
```
```typescript TypeScript
const result = await client.runTask({
body: {
prompt: "Get the top post",
url: "https://news.ycombinator.com",
data_extraction_schema: {
type: "object",
properties: {
title: { type: "string", description: "Post title" },
points: { type: "integer", description: "Points" },
},
},
},
});
const runId = result.run_id;
while (true) {
const run = await client.getRun(runId);
if (["completed", "failed", "terminated", "timed_out", "canceled"].includes(run.status)) {
console.log(`Output: ${JSON.stringify(run.output)}`);
break;
}
await new Promise((resolve) => setTimeout(resolve, 5000));
}
```
```bash cURL
RUN_ID="your_run_id_here"
while true; do
RESPONSE=$(curl -s -X GET "https://api.skyvern.com/v1/runs/$RUN_ID" \
-H "x-api-key: $SKYVERN_API_KEY")
STATUS=$(echo "$RESPONSE" | jq -r '.status')
if [[ "$STATUS" == "completed" || "$STATUS" == "failed" || "$STATUS" == "terminated" || "$STATUS" == "timed_out" || "$STATUS" == "canceled" ]]; then
echo "$RESPONSE" | jq '.output'
break
fi
sleep 5
done
```
</CodeGroup>
If using webhooks, the same `output` field appears in the webhook payload.
---
## Next steps
<CardGroup cols={2}>
<Card
title="Actions Reference"
icon="sliders"
href="/developers/browser-automations/actions-reference"
>
All available page actions and agent methods
</Card>
<Card
title="Build a Browser Automation"
icon="play"
href="/developers/browser-automations/overview"
>
Launch a browser, navigate pages, and extract data
</Card>
</CardGroup>
@@ -0,0 +1,253 @@
---
title: Handle Browsers
subtitle: Launch, connect, configure, and manage browser sessions
description: Launch cloud browsers, connect via CDP, configure proxies and timeouts, open multiple tabs, and manage browser lifecycle for Skyvern automations.
slug: developers/browser-automations/handle-browsers
keywords:
- launch_cloud_browser
- use_cloud_browser
- connect_to_cloud_browser_session
- connect_to_browser_over_cdp
- launch_local_browser
- get_working_page
- new_page
- close
- proxy
- CDP
- session timeout
---
Every browser automation starts with a browser. You launch a cloud Chromium instance, get a Playwright context, and write your automation against it. Cookies, localStorage, and auth state persist across every page you open inside that browser.
This page covers browser lifecycle for code-based automations using the Skyvern SDK. If you're running automations through the Cloud UI workflow editor, browser management is handled automatically. See [Browser Sessions](/cloud/browser-management/browser-sessions) for the Cloud UI equivalent.
---
## Launch a cloud browser
<CodeGroup>
```python Python
browser = await skyvern.launch_cloud_browser()
page = await browser.get_working_page()
```
```typescript TypeScript
const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const browser = await skyvern.launchCloudBrowser();
const page = await browser.getWorkingPage();
```
</CodeGroup>
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `timeout` | `int` | `None` | Session timeout in minutes (5-1440). Server default: 60 minutes |
| `proxy_location` | `ProxyLocation` | `None` | Route traffic through a geographic proxy |
The browser stays alive until `timeout` expires or you call `browser.close()`.
After a successful launch the handle exposes:
- `browser.browser_session_id`: the `pbs_*` session id, useful for locking tasks to this session or for logging
- `browser.pages`: the list of open Playwright pages in this browser context
If `timeout < 5`, Skyvern rejects the request with `UnprocessableEntityError` (422). An invalid `proxy_location` enum is rejected the same way.
<CodeGroup>
```python Python
# Launch with a 2-hour timeout and US residential proxy
browser = await skyvern.launch_cloud_browser(
timeout=120,
proxy_location="RESIDENTIAL"
)
```
```typescript TypeScript
const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const browser = await skyvern.launchCloudBrowser({
timeout: 120,
proxyLocation: "RESIDENTIAL",
});
```
</CodeGroup>
---
## Reuse an existing browser
If you have a cloud browser session already running, reuse it instead of launching a new one.
<CodeGroup>
```python Python
# Reuse the most recent available session, or create one if none exists
browser = await skyvern.use_cloud_browser()
# Connect to a specific session by ID
browser = await skyvern.connect_to_cloud_browser_session("pbs_abc123")
```
```typescript TypeScript
const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
// Reuse the most recent available session, or create one if none exists
const browser = await skyvern.useCloudBrowser();
// Connect to a specific session by ID
const browser = await skyvern.connectToCloudBrowserSession("pbs_abc123");
```
</CodeGroup>
`use_cloud_browser` checks for an available session first. If one exists, it connects to it. If not, it creates a new one with the options you provide.
Passing an unknown session id to `connect_to_cloud_browser_session` raises `NotFoundError` (HTTP 404).
---
## Connect to a local browser
Connect to any browser running with Chrome DevTools Protocol (CDP) enabled. This works with local Chrome, Chromium, or any CDP-compatible browser.
<CodeGroup>
```python Python
browser = await skyvern.connect_to_browser_over_cdp("http://localhost:9222")
page = await browser.get_working_page()
```
```typescript TypeScript
const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const browser = await skyvern.connectToBrowserOverCdp("http://localhost:9222");
const page = await browser.getWorkingPage();
```
</CodeGroup>
Start Chrome with CDP enabled:
```bash
# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
# Linux
google-chrome --remote-debugging-port=9222
```
For self-hosted Skyvern deployments, you can also launch a local Chromium browser directly (Python only):
```python
# Requires Skyvern.local() - not available in cloud mode
skyvern = Skyvern.local()
browser = await skyvern.launch_local_browser(headless=False, port=9222)
```
See the [Self-Hosted Browser Configuration](/developers/self-hosted/browser) guide for headless/headful modes, display settings, and Docker setups.
---
## Working with pages
### Get the current page
<CodeGroup>
```python Python
page = await browser.get_working_page()
```
```typescript TypeScript
const page = await browser.getWorkingPage();
```
</CodeGroup>
Returns the most recent page. If no pages are open, creates a new one. Each call returns a fresh `SkyvernBrowserPage` wrapper. Don't rely on identity (`is` / `===`) comparisons between the return value and earlier page references.
### Open a new tab
<CodeGroup>
```python Python
page2 = await browser.new_page()
await page2.goto("https://example.com/other-page")
```
```typescript TypeScript
const page2 = await browser.newPage();
await page2.goto("https://example.com/other-page");
```
</CodeGroup>
Both pages share the same browser context (cookies, auth state).
### Wrap an existing Playwright page (Python only)
```python
skyvern_page = await browser.get_page_for(existing_playwright_page)
```
Adds AI methods to a Playwright page you already have.
---
## Close the browser
<CodeGroup>
```python Python
await browser.close()
```
```typescript TypeScript
await browser.close();
```
</CodeGroup>
Closes the browser and releases cloud resources. If connected to a cloud session, the session ends. Any unsaved state (cookies, localStorage) is lost unless you saved a [browser profile](/developers/optimization/browser-profiles) first.
---
## Proxy and geolocation
Route browser traffic through residential proxies in specific countries.
<CodeGroup>
```python Python
browser = await skyvern.launch_cloud_browser(
proxy_location="RESIDENTIAL"
)
```
```typescript TypeScript
const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const browser = await skyvern.launchCloudBrowser({
proxyLocation: "RESIDENTIAL",
});
```
</CodeGroup>
Available locations:
| Value | Region |
|-------|--------|
| `RESIDENTIAL` | United States (default) |
| `RESIDENTIAL_GB` | United Kingdom |
| `RESIDENTIAL_DE` | Germany |
| `RESIDENTIAL_ES` | Spain |
| `RESIDENTIAL_FR` | France |
| `RESIDENTIAL_IE` | Ireland |
| `RESIDENTIAL_IN` | India |
| `RESIDENTIAL_JP` | Japan |
| `RESIDENTIAL_AU` | Australia |
| `RESIDENTIAL_CA` | Canada |
| `NONE` | No proxy (direct connection) |
For self-hosted proxy configuration, see [Proxy Setup](/developers/self-hosted/proxy).
---
## Session persistence
Two mechanisms for preserving browser state between automation runs:
**Browser Sessions** keep a browser alive between API calls. Use `create_browser_session` from the [Tasks API](/sdk-reference/tasks/run-task) to create a session, then pass its ID to multiple `run_task` calls. See [Browser Sessions](/developers/optimization/browser-sessions).
**Browser Profiles** save a snapshot of browser state (cookies, localStorage) that persists indefinitely. Create a profile from a completed run, then load it into future runs to skip login. See [Browser Profiles](/developers/optimization/browser-profiles).
---
## Full reference
- [launch_cloud_browser](/sdk-reference/browser-automation/launch-cloud-browser)
- [use_cloud_browser](/sdk-reference/browser-automation/use-cloud-browser)
- [connect_to_cloud_browser_session](/sdk-reference/browser-automation/connect-to-cloud-browser-session)
- [connect_to_browser_over_cdp](/sdk-reference/browser-automation/connect-to-browser-over-cdp)
- [launch_local_browser](/sdk-reference/browser-automation/launch-local-browser) (Python only)
- [get_working_page](/sdk-reference/browser-automation/get-working-page)
- [new_page](/sdk-reference/browser-automation/new-page)
- [get_page_for](/sdk-reference/browser-automation/get-page-for) (Python only)
- [close](/sdk-reference/browser-automation/close)
@@ -0,0 +1,588 @@
---
title: Build a Browser Automation
subtitle: Step-by-step guide to multi-step automations with code
description: Launch a cloud browser, interact with pages using AI and Playwright, chain agent tasks, and build complete browser automations in Python or TypeScript.
slug: developers/browser-automations/overview
keywords:
- launch_cloud_browser
- get_working_page
- page.act
- page.extract
- page.validate
- page.agent.login
- page.agent.run_task
- selector fallback
- login then extract
- multi-page
- Playwright
---
Browser automations are multi-step automations written in code. You launch a cloud browser, get a Playwright page with AI methods layered on top, and write your automation in Python or TypeScript. The code lives in your repo, runs in your CI, and deploys like any other software.
This is the code-first path. If you prefer building automations visually with drag-and-drop blocks, see [Workflows](/cloud/building-workflows/build-a-workflow) in the Cloud UI docs.
<Info>
**Workflows vs. Browser Automation:** Workflows are built and run in the Cloud UI, no code required. Browser automations are built and run in code using Page, Agent, and Browser. Both can do multi-step work across pages. Choose based on whether your team prefers a visual editor or a code editor.
</Info>
This guide walks through a real example: logging into a vendor portal, extracting invoice data, and downloading a PDF. Four steps:
1. **Launch a browser** and get a page
2. **Navigate and interact** with the page using AI actions, selectors, or both
3. **Use the agent** for complex goals like login, multi-step tasks, and file downloads
4. **Run the script** and check results
---
## Step 1: Launch a browser and get a page
Every automation starts by launching a cloud browser and getting a page. The browser is a Chromium instance hosted by Skyvern. The page is a Playwright page with AI methods added on top.
<Info>
Install the SDK first if you haven't:
<CodeGroup>
```bash Python
pip install skyvern
```
```bash TypeScript
npm install @skyvern/client
```
</CodeGroup>
`pip install skyvern` is enough for Skyvern Cloud and remote API usage. If you are using embedded local mode with `Skyvern.local()` or `launch_local_browser()`, install `pip install "skyvern[local]"`. For a local self-hosted server, install `pip install "skyvern[server]"`.
All code snippets below run inside an async function. See the [complete example](#complete-example) for the full runnable script.
</Info>
<CodeGroup>
```python Python
from skyvern import Skyvern
skyvern = Skyvern(api_key="YOUR_API_KEY")
browser = await skyvern.launch_cloud_browser()
page = await browser.get_working_page()
```
```typescript TypeScript
import { Skyvern } from "@skyvern/client";
const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const browser = await skyvern.launchCloudBrowser();
const page = await browser.getWorkingPage();
```
</CodeGroup>
The browser stays alive until you call `browser.close()` or the session times out (default: 60 minutes). All pages inside it share cookies, localStorage, and auth state.
For browser launch options (timeouts, proxies, connecting to local browsers), see [Managing Browsers](/developers/browser-automations/handle-browsers).
---
## Step 2: Navigate and interact with the page
Once you have a page, you can interact with it using standard Playwright, AI actions, or both. For the full list of available methods and parameters, see the [Actions Reference](/developers/browser-automations/actions-reference).
### Navigate
<CodeGroup>
```python Python
await page.goto("https://vendor-portal.example.com")
```
```typescript TypeScript
await page.goto("https://vendor-portal.example.com");
```
</CodeGroup>
### Use AI actions (no selectors needed)
Four methods let you interact with the page using natural language. Skyvern screenshots the page and determines which elements to target.
<CodeGroup>
```python Python
# Perform any action. Returns None.
await page.act("Click the login button")
# Extract structured data. Returns dict (or list if schema root is array).
data = await page.extract(
"Extract all product names and prices",
schema={
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {"type": "string"},
"price": {"type": "number"},
},
},
},
)
# Check page state. Returns bool.
is_logged_in = await page.validate("The user is logged in")
# Ask the AI a question. Returns {"llm_response": str}.
result = await page.prompt("What is the total at the bottom of the table?")
answer = result["llm_response"]
```
```typescript TypeScript
// Perform any action. Returns void.
await page.act("Click the login button");
// Extract structured data. Returns object (or array if schema root is array).
const data = await page.extract({
prompt: "Extract all product names and prices",
schema: {
type: "array",
items: {
type: "object",
properties: {
name: { type: "string" },
price: { type: "number" },
},
},
},
});
// Check page state. Returns boolean.
const isLoggedIn = await page.validate("The user is logged in");
// Ask the AI a question. Returns { llmResponse: string }.
const result = await page.prompt("What is the total at the bottom of the table?");
const answer = result.llmResponse;
```
</CodeGroup>
### Use selectors with AI fallback
`click`, `fill`, and `select_option` accept both a CSS selector and an AI prompt. The selector runs first. If it fails, the AI takes over.
<CodeGroup>
```python Python
# Selector only (fast, deterministic)
await page.click("#submit-button")
await page.fill("#email", value="user@example.com")
# AI only (no selector needed, resilient to layout changes)
await page.click(prompt="Click the 'Submit' button")
await page.fill(prompt="Fill 'user@example.com' in the email field")
# Both - selector first, AI fallback (best for production)
await page.click("#submit-button", prompt="Click the 'Submit' button")
await page.fill("#email", value="user@example.com", prompt="Fill the email field")
```
```typescript TypeScript
// Selector only (fast, deterministic)
await page.click("#submit-button");
await page.fill("#email", "user@example.com");
// AI only (no selector needed, resilient to layout changes)
await page.click({ prompt: "Click the 'Submit' button" });
await page.fill({ prompt: "Fill 'user@example.com' in the email field" });
// Both - selector first, AI fallback (best for production)
await page.click("#submit-button", { prompt: "Click the 'Submit' button" });
await page.fill("#email", "user@example.com", { prompt: "Fill the email field" });
```
</CodeGroup>
### Mix Playwright and AI
Standard Playwright methods work directly. Use selectors where you know the DOM, AI where you don't.
<CodeGroup>
```python Python
await page.goto("https://example.com/login")
await page.fill("#username", value="demo@example.com") # Playwright - known selector
await page.fill("#password", value="s3cur3-p4ss") # Playwright - known selector
await page.click(prompt="Click the sign-in button") # AI - button text varies
await page.wait_for_selector("#dashboard") # Playwright - wait for page load
data = await page.extract("Extract the account balance") # AI - table layout varies
```
```typescript TypeScript
await page.goto("https://example.com/login");
await page.fill("#username", "demo@example.com"); // Playwright - known selector
await page.fill("#password", "s3cur3-p4ss"); // Playwright - known selector
await page.click({ prompt: "Click the sign-in button" }); // AI - button text varies
await page.waitForSelector("#dashboard"); // Playwright - wait for page load
const data = await page.extract({ prompt: "Extract the account balance" }); // AI
```
</CodeGroup>
---
## Step 3: Use the agent for complex goals
For multi-step goals ("log in with 2FA", "navigate to billing and download the invoice"), hand off to the agent. The agent runs a full AI task loop inside your page, preserving all browser state.
### Login with stored credentials
<CodeGroup>
```python Python
await page.agent.login(
credential_type="skyvern",
credential_id="cred_123"
)
```
```typescript TypeScript
await page.agent.login("skyvern", { credentialId: "cred_123" });
```
</CodeGroup>
The agent handles multi-page login flows, CAPTCHAs, and 2FA automatically. Four credential providers: `skyvern` (built-in vault), `bitwarden`, `onepassword`, `azure_vault`. Store credentials via the [Credentials API](/sdk-reference/credentials/create-credential).
### Run a multi-step task
<CodeGroup>
```python Python
result = await page.agent.run_task(
"Go to the billing page and extract all invoice details",
data_extraction_schema={
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"amount": {"type": "string"},
},
},
)
print(result.output)
# {"invoice_number": "INV-2025-042", "amount": "$1,250.00"}
```
```typescript TypeScript
const result = await page.agent.runTask(
"Go to the billing page and extract all invoice details",
{
dataExtractionSchema: {
type: "object",
properties: {
invoice_number: { type: "string" },
amount: { type: "string" },
},
},
},
);
console.log(result.output);
// {"invoice_number": "INV-2025-042", "amount": "$1,250.00"}
```
</CodeGroup>
After the agent finishes, you take back control. The page retains all state:
<CodeGroup>
```python Python
await page.agent.run_task("Navigate to the settings page")
# Agent is done - use direct page actions
settings = await page.extract("Extract all notification preferences")
await page.click("#save-button")
```
```typescript TypeScript
await page.agent.runTask("Navigate to the settings page");
// Agent is done - use direct page actions
const settings = await page.extract({ prompt: "Extract all notification preferences" });
await page.click("#save-button");
```
</CodeGroup>
### Download files
<CodeGroup>
```python Python
result = await page.agent.download_files(
"Download the Q4 2025 financial report",
download_suffix=".pdf",
download_timeout=30,
)
for file in result.downloaded_files or []:
print(f"Downloaded: {file.url}")
```
```typescript TypeScript
const result = await page.agent.downloadFiles(
"Download the Q4 2025 financial report",
{ downloadSuffix: ".pdf", downloadTimeout: 30 },
);
for (const file of result.downloadedFiles ?? []) {
console.log(`Downloaded: ${file.url}`);
}
```
</CodeGroup>
### Run a workflow on the page
If you have built a workflow, run it on a page you already control:
<CodeGroup>
```python Python
await page.agent.login(credential_type="skyvern", credential_id="cred_123")
result = await page.agent.run_workflow(
"wpid_monthly_report",
parameters={"month": "2025-03"}
)
```
```typescript TypeScript
await page.agent.login("skyvern", { credentialId: "cred_123" });
const result = await page.agent.runWorkflow("wpid_monthly_report", {
parameters: { month: "2025-03" },
});
```
</CodeGroup>
**`agent.run_workflow` vs `skyvern.run_workflow`:** The top-level `run_workflow` opens its own browser. Use `agent.run_workflow` when you need to log in first or do setup before the workflow runs.
---
## Complete example
Putting it all together: log into a vendor portal, extract invoices, and download a statement.
<CodeGroup>
```python Python
import asyncio
from skyvern import Skyvern
async def main():
skyvern = Skyvern(api_key="YOUR_API_KEY")
browser = await skyvern.launch_cloud_browser()
page = await browser.get_working_page()
# Navigate
await page.goto("https://vendor-portal.example.com")
# Login with stored credentials
await page.agent.login(credential_type="skyvern", credential_id="cred_abc123")
# Extract data using a mix of Playwright and AI
await page.click("#billing-tab")
invoices = await page.extract(
"Extract all invoice numbers, dates, and amounts",
schema={
"type": "array",
"items": {
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"date": {"type": "string"},
"amount": {"type": "string"},
},
},
},
)
# Download a file
result = await page.agent.download_files(
"Download the latest monthly statement",
download_suffix=".pdf",
)
# Check results
print(f"Found {len(invoices)} invoices")
for inv in invoices:
print(f" {inv['invoice_number']}: {inv['amount']}")
for file in result.downloaded_files or []:
print(f"Downloaded: {file.url}")
await browser.close()
asyncio.run(main())
```
```typescript TypeScript
import { Skyvern } from "@skyvern/client";
async function main() {
const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const browser = await skyvern.launchCloudBrowser();
const page = await browser.getWorkingPage();
// Navigate
await page.goto("https://vendor-portal.example.com");
// Login with stored credentials
await page.agent.login("skyvern", { credentialId: "cred_abc123" });
// Extract data using a mix of Playwright and AI
await page.click("#billing-tab");
const invoices = await page.extract({
prompt: "Extract all invoice numbers, dates, and amounts",
schema: {
type: "array",
items: {
type: "object",
properties: {
invoice_number: { type: "string" },
date: { type: "string" },
amount: { type: "string" },
},
},
},
});
// Download a file
const result = await page.agent.downloadFiles(
"Download the latest monthly statement",
{ downloadSuffix: ".pdf" },
);
// Check results
console.log(`Found ${invoices.length} invoices`);
for (const inv of invoices) {
console.log(` ${inv.invoice_number}: ${inv.amount}`);
}
for (const file of result.downloadedFiles ?? []) {
console.log(`Downloaded: ${file.url}`);
}
await browser.close();
}
main();
```
</CodeGroup>
---
## Step 4: Run and get results
Run the script:
<CodeGroup>
```bash Python
python your_automation.py
```
```bash TypeScript
npx tsx your_automation.ts
```
</CodeGroup>
You'll see the browser session URL in the console output. Open it in your browser to watch the automation run in real time.
### Example output
Here's what the Complete Example prints, grouped by the call that produced each block:
```text wrap
# skyvern.launch_cloud_browser()
[Skyvern] Launched new cloud browser session url=https://app.skyvern.com/browser-session/pbs_519895987620976102
# page.agent.login(...)
[Skyvern] AI login workflow finished run_id=wr_519896041203554782 status=completed
# page.extract(...)
[Skyvern] AI extract prompt=Extract all invoice numbers, dates, and amounts
# page.agent.download_files(...)
[Skyvern] Starting AI file download workflow navigation_goal=Download the latest monthly statement
[Skyvern] AI file download workflow is running, this may take a while run_id=wr_519896107880060430
[Skyvern] AI file download workflow finished run_id=wr_519896107880060430 status=completed
# print(f"Found {len(invoices)} invoices") + for inv in invoices: print(...)
Found 3 invoices
INV-2025-042: $2,340.00
INV-2025-043: $1,850.00
INV-2025-044: $3,100.00
# for file in result.downloaded_files: print(f"Downloaded: {file.url}")
Downloaded: https://skyvern-uploads.s3.amazonaws.com/downloads/production/o_510.../wr_519.../statement.pdf?AWS...
```
The `[Skyvern] ...` lines come from the SDK's built-in logger and stream in real time as each call runs. Your own `print` output appears after the awaited call returns.
For the full response shape, see [`TaskRunResponse`](/sdk-reference/tasks/run-task#returns-taskrunresponse) and [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse).
### View results in the Cloud UI
Every run appears in the [Runs page](https://app.skyvern.com/runs). Click any run to see:
- **Recording** - video of the browser session
- **Actions** - step-by-step timeline with screenshots and AI reasoning
- **Output** - extracted data as JSON
- **Artifacts** - screenshots, HAR files, generated code
### Artifacts
Every run captures recordings, screenshots, AI reasoning logs, network HAR files, and downloaded files. Access them via the Cloud UI or programmatically:
<CodeGroup>
```python Python
artifacts = await skyvern.get_run_artifacts(result.run_id)
for artifact in artifacts:
print(f"{artifact.artifact_type}: {artifact.uri}")
```
```typescript TypeScript
const artifacts = await skyvern.getRunArtifacts(result.run_id);
for (const artifact of artifacts) {
console.log(`${artifact.artifact_type}: ${artifact.uri}`);
}
```
</CodeGroup>
For the full artifact type reference and debugging workflows, see [Using Artifacts](/developers/debugging/using-artifacts).
---
## Next steps
<CardGroup cols={2}>
<Card
title="Actions Reference"
icon="list"
href="/developers/browser-automations/actions-reference"
>
Every page action and agent method with parameters and return types
</Card>
<Card
title="Managing Browsers"
icon="browser"
href="/developers/browser-automations/handle-browsers"
>
Launch options, multiple tabs, proxies, connecting to local browsers
</Card>
</CardGroup>
<CardGroup cols={2}>
<Card
title="Store Credentials"
icon="key"
href="/sdk-reference/credentials/create-credential"
>
Set up credentials for automated login with the agent
</Card>
<Card
title="SDK Reference"
icon="code"
href="/sdk-reference/complete-reference"
>
Every SDK method, parameter, and type on one page (Python + TypeScript)
</Card>
</CardGroup>
<CardGroup cols={2}>
<Card
title="API Reference"
icon="plug"
href="/api-reference"
>
Full OpenAPI spec for every REST endpoint
</Card>
<Card
title="llms.txt"
icon="file-lines"
href="https://skyvern.com/docs/llms.txt"
>
Machine-readable index of the entire documentation for AI coding agents
</Card>
</CardGroup>
@@ -0,0 +1,181 @@
---
title: Work with Files
subtitle: Download files from websites during browser automations
description: Use agent.download_files to navigate websites, find download links, and retrieve files. Access downloaded files via presigned URLs.
slug: developers/browser-automations/work-with-files
keywords:
- download_files
- downloaded_files
- presigned URL
- PDF
- invoice
- download_suffix
- download_timeout
- FileInfo
---
In a browser automation, `agent.download_files` navigates a page, finds the download link, and captures the file. Downloaded files are stored in Skyvern's cloud storage and returned as presigned URLs in the response.
If you're building workflows in the Cloud UI instead, use the File Download block. See [Block Types and Configuration](/cloud/building-workflows/configure-blocks).
---
## Download a file
<CodeGroup>
```python Python
browser = await skyvern.launch_cloud_browser()
page = await browser.get_working_page()
await page.goto("https://portal.example.com")
await page.agent.login(credential_type="skyvern", credential_id="cred_123")
result = await page.agent.download_files(
"Download the Q4 2025 financial report",
download_suffix=".pdf",
download_timeout=30,
)
for file in result.downloaded_files or []:
print(f"File: {file.filename}")
print(f"URL: {file.url}")
print(f"Checksum: {file.checksum}")
await browser.close()
```
```typescript TypeScript
const browser = await skyvern.launchCloudBrowser();
const page = await browser.getWorkingPage();
await page.goto("https://portal.example.com");
await page.agent.login("skyvern", { credentialId: "cred_123" });
const result = await page.agent.downloadFiles(
"Download the Q4 2025 financial report",
{ downloadSuffix: ".pdf", downloadTimeout: 30 },
);
for (const file of result.downloadedFiles ?? []) {
console.log(`File: ${file.filename}`);
console.log(`URL: ${file.url}`);
console.log(`Checksum: ${file.checksum}`);
}
await browser.close();
```
</CodeGroup>
---
## Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | `str` / `string` | Yes | Describe what to download. The agent navigates the page to find and click the download link. |
| `url` | `str` / `string` | No | URL to navigate to before downloading. Defaults to the current page URL. |
| `download_suffix` | `str` / `string` | No | Filename hint prepended to the saved file (e.g., `"invoice"` → `invoice.pdf`). **Not a validator**; mismatched extensions don't fail the run. Omit this to get a system-generated filename like `download-<timestamp>-<random>.pdf`. |
| `download_timeout` | `float` / `number` | No | Soft hint (seconds) for how long to wait for a download to start. Not a hard cap; the overall `timeout` below governs failure. |
| `max_steps_per_run` | `int` / `number` | No | Cap AI steps for the download navigation. |
| `timeout` | `float` / `number` | No | Total timeout in seconds (default: 1800). |
---
## Response
`agent.download_files` returns a `WorkflowRunResponse`. The downloaded files are in the `downloaded_files` field.
### Response fields
Most-used fields:
| Field | Type | Description |
|-------|------|-------------|
| `run_id` | `str` | Run identifier (prefix: `wr_`) |
| `status` | `str` | `completed`, `failed`, `terminated`, `timed_out`, or `canceled` |
| `downloaded_files` | `list[FileInfo]` | Files captured during the run |
| `output` | `dict \| None` | Any extracted data (may be `None` even on `completed`) |
| `app_url` | `str` | Link to view this run in the Cloud UI |
| `recording_url` | `str \| None` | Video recording of the download session |
| `failure_reason` | `str \| None` | Error description if the download failed |
| `step_count` | `int` | Number of AI steps taken |
See the [`WorkflowRunResponse`](/sdk-reference/workflows/run-workflow#returns-workflowrunresponse) reference for the full field list.
### FileInfo fields
Each file in `downloaded_files` has:
| Field | Type | Description |
|-------|------|-------------|
| `url` | `str` | Presigned URL to download the file. Valid for a limited time. |
| `filename` | `str \| None` | Saved filename. Reflects `download_suffix` if you set one, otherwise system-generated. |
| `checksum` | `str \| None` | SHA-256 checksum for integrity verification |
| `file_size` | `int \| None` | Size of the file in bytes |
| `modified_at` | `datetime \| None` | Last-modified timestamp if the source provides one |
---
## Where files are stored
Files are stored in Skyvern's managed cloud storage (S3). You access them through the presigned URLs returned in `downloaded_files`. Files are not saved to your local machine automatically.
To save a file locally:
<CodeGroup>
```python Python
import requests
for file in result.downloaded_files or []:
response = requests.get(file.url)
with open(file.filename or "download.pdf", "wb") as f:
f.write(response.content)
print(f"Saved {file.filename}")
```
```typescript TypeScript
import fs from "fs";
for (const file of result.downloadedFiles ?? []) {
const response = await fetch(file.url);
const buffer = await response.arrayBuffer();
fs.writeFileSync(file.filename ?? "download.pdf", Buffer.from(buffer));
console.log(`Saved ${file.filename}`);
}
```
</CodeGroup>
---
## Tips
**Set `download_suffix`** to get a predictable filename (e.g., `"invoice-q4"` → `invoice-q4.pdf`). Without it, files are saved with a system-generated name like `download-<timestamp>-<random>.pdf`. It does **not** validate or filter by extension.
**Raise the overall `timeout`** for large files. `download_timeout` is a soft hint; `timeout` is what actually fails the run.
**Verify with checksums.** The `checksum` field contains a SHA-256 hash. Compare it against expected values to verify file integrity.
**Login first.** Most download portals require authentication. Call `agent.login` before `agent.download_files` - the agent reuses the authenticated session.
---
## File operations in workflows
If you build workflows in the Cloud UI, file operations use dedicated blocks instead of `agent.download_files`:
| Block | Purpose |
|-------|---------|
| **File Download** | Download files during workflow execution |
| **File Parser** | Parse PDFs, CSVs, and Excel files |
| **Download to S3** | Save files from URLs to Skyvern's S3 |
| **Upload to S3** | Upload workflow files to S3 |
| **File Upload** | Upload to your own S3 or Azure Blob Storage |
Files downloaded during a workflow accumulate in a temporary directory and can be passed between blocks using workflow parameters. See [Workflow Blocks Reference](/cloud/building-workflows/configure-blocks) for block configuration details.
---
## Full reference
- [agent.download_files](/sdk-reference/browser-automation/agent-download-files) - SDK reference with all parameter options
- [Using Artifacts](/developers/debugging/using-artifacts) - access recordings, screenshots, and downloaded files from any run
+515
View File
@@ -0,0 +1,515 @@
---
title: Handle 2FA
subtitle: Configure two-factor authentication for automated logins
description: Configure two-factor authentication for Skyvern automations using TOTP secrets, pushed verification codes, pull-based endpoints, or magic links. Supports Bitwarden TOTP integration.
slug: developers/credentials/handle-2fa
keywords:
- TOTP
- 2FA
- totp_identifier
- totp_url
- authenticator
- email code
- SMS code
- magic link
- send_totp_code
- verification
---
Many websites require two-factor authentication (2FA) during login. Skyvern supports multiple 2FA methods to handle these flows automatically.
---
## Choose your method
Select the method that matches how you receive verification codes:
| Scenario | Recommended Method |
|----------|-------------------|
| You have the TOTP secret key | [Store TOTP secret](#method-1-store-totp-secret): Skyvern generates codes |
| Codes sent to email/SMS you can forward | [Push codes to Skyvern](#method-2-push-codes-to-skyvern) |
| Codes sent to a system you control | [Skyvern pulls from your endpoint](#method-3-skyvern-pulls-from-your-endpoint) |
| Passwordless/magic link auth | [Magic links](#method-4-magic-links) |
| Using Bitwarden with TOTP | [Password manager integration](#password-manager-totp) |
---
## Method 1: Store TOTP secret
**Best for:** Sites where you have access to the TOTP secret (the setup QR code or manual key).
When you enable 2FA on a website, you're typically shown a QR code or a secret key. Store this secret with your credential, and Skyvern generates valid codes automatically.
<CodeGroup>
```python Python
import os
from skyvern import Skyvern
client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
credential = await client.create_credential(
name="Acme Portal Login",
credential_type="password",
credential={
"username": "user@example.com",
"password": "secure_password",
"totp": "JBSWY3DPEHPK3PXP", # Base32 secret from QR code
"totp_type": "authenticator",
},
)
```
```typescript TypeScript
import { SkyvernClient } from "@skyvern/client";
const client = new SkyvernClient({
apiKey: process.env.SKYVERN_API_KEY,
});
const credential = await client.createCredential({
name: "Acme Portal Login",
credential_type: "password",
credential: {
username: "user@example.com",
password: "secure_password",
totp: "JBSWY3DPEHPK3PXP",
totp_type: "authenticator",
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/credentials" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Portal Login",
"credential_type": "password",
"credential": {
"username": "user@example.com",
"password": "secure_password",
"totp": "JBSWY3DPEHPK3PXP",
"totp_type": "authenticator"
}
}'
```
</CodeGroup>
### TOTP types
| Type | Description |
|------|-------------|
| `authenticator` | Standard TOTP codes (Google Authenticator, Authy, etc.) |
| `email` | Codes sent via email that you'll push to Skyvern |
| `text` | Codes sent via SMS that you'll push to Skyvern |
<Tip>
Skyvern generates TOTP codes using standard 30-second windows. If the current code has less than 20 seconds remaining, Skyvern automatically uses the next code to ensure successful entry.
</Tip>
### Finding your TOTP secret
Most sites show the secret when you set up 2FA:
1. Go to your account's security settings
2. Click "Set up authenticator app"
3. Look for "Can't scan the QR code?" or "Manual entry"
4. Copy the secret key (usually Base32 format like `JBSWY3DPEHPK3PXP`)
<Note>
If you've already set up 2FA and don't have the secret, you may need to disable and re-enable 2FA to see the secret again. Contact [support@skyvern.com](mailto:support@skyvern.com) for help.
</Note>
---
## Method 2: Push codes to Skyvern
**Best for:** Codes sent to email or SMS that you can programmatically forward.
When your automation encounters a 2FA prompt, Skyvern polls for codes that you push via API. Your email or SMS forwarding system sends codes to Skyvern as they arrive.
### Step 1: Set up code forwarding
Configure your email or SMS to forward verification codes to Skyvern. Common approaches:
- **Email:** Gmail filter + Zapier webhook
- **SMS:** Twilio webhook to your server
- **Email:** AWS SES + Lambda function
<AccordionGroup>
<Accordion title="How to set up Email Forwarding with Zapier?">
This setup requires a Zapier Pro plan account.
<Steps>
<Step title="Create a Zapier Zap">
{/* TODO: Replace with actual video */}
<Frame>
<video
autoPlay
muted
loop
playsInline
className="rounded-xl"
src="/images/zapier-forwarding-setup.mp4"
></video>
</Frame>
1. Go to [zapier.com](https://zapier.com/app/home) and create a new Zap
2. In the newly created Zap draft, click the "Trigger" button
3. Click **Email by Zapier**
4. In the Email "Setup", pick **New Inbound Email** in the Trigger event selection. Click **Continue**
5. In Email "Configure", create an email address which will be used to forward emails for TOTP codes. Click **Continue**
6. Click the "Action" button and add **Webhooks by Zapier**
7. In the Setup, choose **POST** under the Action event selection. Click **Continue**
8. In the "Configure", set up these fields to make a POST request to Skyvern's TOTP API:
- **URL:** `https://api.skyvern.com/v1/credentials/totp`
- **Payload Type:** `json`
- **Data:**
- `totp_identifier`: choose **Raw To Email** after clicking the "+" sign
- `content`: choose **Body Plain** after clicking the "+" sign
- `source`: `email`
- **Headers:**
- `x-api-key`: your Skyvern API key
9. Click **Continue**
</Step>
<Step title="Add forwarding email and create a filter in Gmail">
Go to Gmail Settings → Forwarding and POP/IMAP → click **Add a forwarding address** → enter the Zapier email address you created. Complete any verification steps.
Then go to **Filters and Blocked Addresses**. Click **Create a new filter** and set up a filtering rule for your TOTP (2FA/MFA) emails. Click **Create filter**, check **Forward it to**, pick the Zapier email address, and update the filter.
<Frame>
<img src="/images/totp/create_email_forwarding.png" alt="Gmail forwarding filter" width="400"/>
</Frame>
</Step>
<Step title="Test it end to end">
Forward any previous TOTP email to the Zapier email address you created.
In Zapier, under the "Test" of the Webhooks action, send a request to test it out. If successful, you should see a "A request was sent to Webhooks by Zapier" message.
</Step>
</Steps>
</Accordion>
<Accordion title="How to set up SMS Forwarding with Twilio?">
Use a virtual phone number service like [Twilio](https://www.twilio.com/en-us/docs/usage/tutorials/how-to-use-your-free-trial-account) or [Plivo](https://www.plivo.com/) to receive SMS codes and forward them to Skyvern.
<Steps>
<Step title="Set up a Twilio phone number">
Create a Twilio account and provision a phone number. This number will receive the SMS verification codes.
</Step>
<Step title="Create a Twilio Function to forward codes">
In your Twilio console, create a new Function that forwards incoming SMS to Skyvern's TOTP API:
```javascript
// Twilio Function
exports.handler = async function(context, event, callback) {
const axios = require('axios');
await axios.post('https://api.skyvern.com/v1/credentials/totp', {
totp_identifier: event.To, // Your Twilio phone number
content: event.Body,
source: 'phone'
}, {
headers: {
'x-api-key': context.SKYVERN_API_KEY,
'Content-Type': 'application/json'
}
});
return callback(null, new Twilio.Response());
};
```
Add your `SKYVERN_API_KEY` as an environment variable in the Twilio Function configuration.
</Step>
<Step title="Configure the webhook">
In your Twilio phone number settings, set the **A Message Comes In** webhook to point to your Twilio Function URL.
</Step>
<Step title="Test it">
Send a test SMS to your Twilio number and verify the code appears in Skyvern:
```bash
curl -X GET "https://api.skyvern.com/v1/credentials/totp?totp_identifier=YOUR_TWILIO_NUMBER" \
-H "x-api-key: $SKYVERN_API_KEY"
```
</Step>
</Steps>
</Accordion>
</AccordionGroup>
### Step 2: Start the run with a TOTP identifier
When running your login, include a `totp_identifier` that matches what you'll use when pushing codes:
<CodeGroup>
```python Python
result = await client.login(
credential_type="skyvern",
url="https://portal.example.com/login",
credential_id="cred_xyz789",
totp_identifier="user@example.com", # Must match when pushing code
)
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/tasks/login" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"credential_type": "skyvern",
"url": "https://portal.example.com/login",
"credential_id": "cred_xyz789",
"totp_identifier": "user@example.com"
}'
```
</CodeGroup>
### Step 3: Push the code when received
When the verification code arrives, push it to Skyvern:
<CodeGroup>
```python Python
await client.send_totp_code(
totp_identifier="user@example.com",
content="Your verification code is 123456", # Full email/SMS body
source="email",
)
```
```typescript TypeScript
await client.sendTotpCode({
totp_identifier: "user@example.com",
content: "Your verification code is 123456",
source: "email",
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/credentials/totp" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"totp_identifier": "user@example.com",
"content": "Your verification code is 123456",
"source": "email"
}'
```
</CodeGroup>
<Note>
If `content` is longer than 10 characters, Skyvern's AI extracts the verification code automatically. You can send the full email or SMS body without parsing it yourself.
</Note>
---
## Method 3: Skyvern pulls from your endpoint
**Best for:** Environments where you control the system receiving 2FA codes and can expose them via an HTTP endpoint.
Instead of pushing codes to Skyvern, you implement an endpoint that Skyvern polls until a code is available.
### Step 1: Implement the endpoint
Your endpoint must accept POST requests and return the verification code:
**Request from Skyvern:**
```http
POST https://your-server.com/totp-webhook
x-skyvern-signature: <hmac-sha256-signature>
Content-Type: application/json
{
"task_id": "tsk_123456"
}
```
**Expected response:**
```json
{
"verification_code": "123456"
}
```
### Step 2: Verify request signatures
Skyvern signs all requests using HMAC-SHA256 with your API key. Verify the signature to ensure requests are authentic:
```python
import hmac
import hashlib
def verify_skyvern_request(request, api_key: str) -> bool:
signature = request.headers.get("x-skyvern-signature")
payload = request.body # bytes
expected = hmac.new(
api_key.encode("utf-8"),
msg=payload,
digestmod=hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected)
```
### Step 3: Configure the login
Pass `totp_url` when running your login:
<CodeGroup>
```python Python
result = await client.login(
credential_type="skyvern",
url="https://portal.example.com/login",
credential_id="cred_xyz789",
totp_url="https://your-server.com/totp-webhook",
)
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/tasks/login" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"credential_type": "skyvern",
"url": "https://portal.example.com/login",
"credential_id": "cred_xyz789",
"totp_url": "https://your-server.com/totp-webhook"
}'
```
</CodeGroup>
Skyvern polls your endpoint every 10 seconds until a code is returned or the timeout is reached.
---
## Method 4: Magic links
**Best for:** Passwordless authentication systems that send one-time login links.
When a site uses magic links instead of passwords, push the link to Skyvern:
<CodeGroup>
```python Python
await client.send_totp_code(
totp_identifier="user@example.com",
content="https://portal.example.com/login?token=abc123xyz",
source="email",
)
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/credentials/totp" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"totp_identifier": "user@example.com",
"content": "https://portal.example.com/login?token=abc123xyz",
"source": "email"
}'
```
</CodeGroup>
<Note>
Skyvern automatically detects URLs and classifies them as magic links. The automation will navigate to the link to complete authentication.
</Note>
For magic link flows, structure your workflow in two parts:
1. **Trigger the magic link**: Navigate to login and enter email
2. **Complete login**: Use the magic link as the starting URL for the next step
---
## Password manager TOTP
If you store TOTP secrets in Bitwarden or 1Password, Skyvern can retrieve both the password and TOTP code in a single request.
### Bitwarden
Store your TOTP secret in Bitwarden's authenticator field:
1. Open the vault item in Bitwarden
2. Click "Authenticator Key (TOTP)"
3. Enter your TOTP secret or scan the QR code
4. Skyvern retrieves both password and TOTP when using this credential
**Supported TOTP formats:**
- Raw secret: `JBSWY3DPEHPK3PXP`
- otpauth URI: `otpauth://totp/Example:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Example`
### 1Password
Store TOTP in 1Password's one-time password field:
1. Edit the login item in 1Password
2. Add a "One-Time Password" field
3. Enter the TOTP secret or scan the QR code
4. Reference the item in your Skyvern workflow
---
## Multi-field TOTP entry
Some sites split TOTP codes across multiple input fields (one digit per box). Skyvern handles this automatically:
1. Detects multi-field TOTP layouts
2. Enters the same code across all fields
3. Caches the code to prevent requesting a new one mid-entry
<Note>
No special configuration needed. Skyvern's AI recognizes multi-field TOTP inputs and handles them correctly.
</Note>
---
## Timeouts and polling
Skyvern waits for 2FA codes based on configurable timeouts:
| Setting | Default | Description |
|---------|---------|-------------|
| Polling interval | 10 seconds | How often Skyvern checks for new codes |
| Polling timeout | 15 minutes | Maximum wait time before failing |
If you're pushing codes, ensure your forwarding pipeline delivers codes within the timeout window.
---
## List recent codes
Debug your 2FA integration by listing recent codes received:
```bash
curl -X GET "https://api.skyvern.com/v1/credentials/totp?totp_identifier=user@example.com&limit=10" \
-H "x-api-key: $SKYVERN_API_KEY"
```
**Query parameters:**
| Parameter | Description |
|-----------|-------------|
| `totp_identifier` | Filter by identifier (email, phone, etc.) |
| `workflow_run_id` | Filter by specific workflow run |
| `otp_type` | Filter by type: `totp` or `magic_link` |
| `limit` | Number of records (default 50, max 200) |
<Note>
Skyvern only returns codes from the last 10 minutes (configurable via `TOTP_LIFESPAN_MINUTES`).
</Note>
---
## Next steps
<CardGroup cols={2}>
<Card title="Store Credentials" icon="key" href="/developers/credentials/store-credentials">
Set up your credential vault integration
</Card>
<Card title="Troubleshooting" icon="wrench" href="/developers/credentials/troubleshooting-login">
Debug 2FA and login failures
</Card>
</CardGroup>
@@ -0,0 +1,495 @@
---
title: Store Credentials
subtitle: Securely manage login credentials, credit cards, and API secrets
description: Create, manage, and delete credentials using Skyvern's credential API. Store passwords, credit cards, and API secrets in Bitwarden, 1Password, Azure Key Vault, or a custom vault.
slug: developers/credentials/store-credentials
keywords:
- create_credential
- get_credentials
- delete_credential
- password
- credit card
- secret
- Bitwarden
- 1Password
- Azure Key Vault
- custom vault
---
Skyvern provides a credential management layer that gives you a unified API to create, use, and delete credentials. Your actual secrets are never stored in Skyvern. They live in your external vault (Bitwarden by default, or 1Password, Azure Key Vault, or your own service).
---
## How it works
When you create a credential via Skyvern's API, two things happen:
**Skyvern stores metadata** for easy lookup: credential names, IDs like `cred_xyz789`, usernames, and non-sensitive identifiers (like the last 4 digits of a card). This lets you list and manage credentials without exposing secrets.
**Your vault stores the secrets**: passwords, TOTP keys, full card numbers, and API tokens. Skyvern only retrieves these at runtime when needed, then discards them immediately after use.
```mermaid
flowchart LR
subgraph Your Infrastructure
Vault[(Your Vault<br/>Bitwarden, 1Password, Azure, etc.)]
end
subgraph Skyvern
Fetch[Fetch at runtime]
Fill[Fill forms]
end
subgraph Outputs
Browser[Browser]
Logs[Logs & LLM]
end
Vault -->|secrets| Fetch
Fetch -->|real values| Fill
Fill -->|real values| Browser
Fetch -.->|"placeholders<br/>(BW_PASSWORD)"| Logs
```
This gives you:
- **Friendly IDs**: Reference credentials by `cred_xyz789` instead of vault-specific item IDs
- **Vault abstraction**: Switch between Bitwarden, Azure, or custom vaults without changing your code
- **Security by design**: Secrets never appear in logs, API responses, or LLM prompts
---
## Credential types
Skyvern supports three credential types, each designed for specific use cases.
### Password credentials
Store usernames, passwords, and optional TOTP secrets for website logins.
<CodeGroup>
```python Python
import os
from skyvern import Skyvern
client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
credential = await client.create_credential(
name="Acme Portal Login",
credential_type="password",
credential={
"username": "user@example.com",
"password": "secure_password_here",
},
)
print(f"Credential ID: {credential.credential_id}")
```
```typescript TypeScript
import { SkyvernClient } from "@skyvern/client";
const client = new SkyvernClient({
apiKey: process.env.SKYVERN_API_KEY,
});
const credential = await client.createCredential({
name: "Acme Portal Login",
credential_type: "password",
credential: {
username: "user@example.com",
password: "secure_password_here",
},
});
console.log(`Credential ID: ${credential.credential_id}`);
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/credentials" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Portal Login",
"credential_type": "password",
"credential": {
"username": "user@example.com",
"password": "secure_password_here"
}
}'
```
</CodeGroup>
### Credit card credentials
Store payment information for checkout automations. Skyvern only stores the last 4 digits in metadata for identification.
<CodeGroup>
```python Python
credential = await client.create_credential(
name="Corporate Card",
credential_type="credit_card",
credential={
"card_number": "4242424242424242",
"card_cvv": "123",
"card_exp_month": "12",
"card_exp_year": "2028",
"card_brand": "visa",
"card_holder_name": "John Smith",
},
)
```
```typescript TypeScript
const credential = await client.createCredential({
name: "Corporate Card",
credential_type: "credit_card",
credential: {
card_number: "4242424242424242",
card_cvv: "123",
card_exp_month: "12",
card_exp_year: "2028",
card_brand: "visa",
card_holder_name: "John Smith",
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/credentials" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Corporate Card",
"credential_type": "credit_card",
"credential": {
"card_number": "4242424242424242",
"card_cvv": "123",
"card_exp_month": "12",
"card_exp_year": "2028",
"card_brand": "visa",
"card_holder_name": "John Smith"
}
}'
```
</CodeGroup>
**Supported card brands:** `visa`, `mastercard`, `amex`, `discover`
### Secret credentials
Store API keys, tokens, or other sensitive strings for use in HTTP Request blocks or custom integrations.
<CodeGroup>
```python Python
credential = await client.create_credential(
name="API Key",
credential_type="secret",
credential={
"secret_value": "sk-abc123xyz",
"secret_label": "Production API Key", # optional
},
)
```
```typescript TypeScript
const credential = await client.createCredential({
name: "API Key",
credential_type: "secret",
credential: {
secret_value: "sk-abc123xyz",
secret_label: "Production API Key",
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/credentials" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "API Key",
"credential_type": "secret",
"credential": {
"secret_value": "sk-abc123xyz",
"secret_label": "Production API Key"
}
}'
```
</CodeGroup>
---
## Vault integrations
Skyvern integrates with external password managers so credentials never leave your infrastructure.
### Bitwarden
Connect Skyvern to your Bitwarden organization to use existing vault items.
**Cloud setup:**
1. Create a Bitwarden organization at [bitwarden.com](https://bitwarden.com)
2. Create a collection to share with Skyvern
3. Contact [support@skyvern.com](mailto:support@skyvern.com) to complete the integration
4. Get your collection ID from the Bitwarden URL
5. Reference credentials by collection ID in your workflows
**Self-hosted setup:**
For self-hosted Bitwarden or Vaultwarden, configure these environment variables:
```bash
SKYVERN_AUTH_BITWARDEN_ORGANIZATION_ID=your-org-id
SKYVERN_AUTH_BITWARDEN_MASTER_PASSWORD=your-master-password
SKYVERN_AUTH_BITWARDEN_CLIENT_ID=user.your-client-id
SKYVERN_AUTH_BITWARDEN_CLIENT_SECRET=your-client-secret
BW_HOST=https://your-bitwarden-server.com
```
### 1Password
Connect via service account tokens for secure credential access.
1. Create a 1Password service account with access to your vault
2. Store the service account token in Skyvern:
```bash
curl -X POST "https://api.skyvern.com/v1/credentials/onepassword/create" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"token": "your-1password-service-account-token"
}'
```
3. Reference vault items by ID in your workflows
### Azure Key Vault
Store credentials in Azure Key Vault for enterprise environments.
```bash
curl -X POST "https://api.skyvern.com/v1/credentials/azure_credential/create" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"credential": {
"client_id": "your-azure-client-id",
"client_secret": "your-azure-client-secret",
"tenant_id": "your-azure-tenant-id"
}
}'
```
### Custom HTTP vault
Integrate your own credential service via HTTP API. Your service must implement these endpoints:
| Endpoint | Method | Description |
|----------|--------|-------------|
| `{base_url}` | POST | Create credential, return `{"id": "..."}` |
| `{base_url}/{id}` | GET | Return credential data |
| `{base_url}/{id}` | DELETE | Delete credential |
Configure via environment variables:
```bash
CREDENTIAL_VAULT_TYPE=custom
CUSTOM_CREDENTIAL_API_BASE_URL=https://credentials.company.com/api/v1/credentials
CUSTOM_CREDENTIAL_API_TOKEN=your_api_token
```
Or via API for per-organization configuration:
```bash
curl -X POST "https://api.skyvern.com/v1/credentials/custom_credential/create" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"config": {
"api_base_url": "https://credentials.company.com/api/v1/credentials",
"api_token": "your_api_token"
}
}'
```
---
## Using credentials in workflows
Workflows are the recommended way to use credentials. Add a credential parameter to your workflow, then reference it in login blocks.
<CodeGroup>
```python Python
# Run a workflow with credential parameter
result = await client.run_workflow(
workflow_id="wpid_abc123",
parameters={
"login_credential": "cred_xyz789", # Your credential ID
"target_url": "https://portal.example.com",
},
)
```
```typescript TypeScript
const result = await client.runWorkflow({
body: {
workflow_id: "wpid_abc123",
parameters: {
login_credential: "cred_xyz789",
target_url: "https://portal.example.com",
},
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "wpid_abc123",
"parameters": {
"login_credential": "cred_xyz789",
"target_url": "https://portal.example.com"
}
}'
```
</CodeGroup>
<Note>
You can also manage credentials directly from the Skyvern UI. See the [Managing Credentials](/cloud/managing-credentials/overview) guide for details.
</Note>
---
## Using credentials with login
For direct login automations, use the dedicated `login` method which handles credential retrieval and authentication:
<CodeGroup>
```python Python
result = await client.login(
credential_type="skyvern",
url="https://portal.example.com/login",
credential_id="cred_xyz789",
prompt="Navigate to the dashboard after logging in",
)
```
```typescript TypeScript
const result = await client.login({
credential_type: "skyvern",
url: "https://portal.example.com/login",
credential_id: "cred_xyz789",
prompt: "Navigate to the dashboard after logging in",
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/tasks/login" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"credential_type": "skyvern",
"url": "https://portal.example.com/login",
"credential_id": "cred_xyz789",
"prompt": "Navigate to the dashboard after logging in"
}'
```
</CodeGroup>
**Credential types for login:**
| Type | Description |
|------|-------------|
| `skyvern` | Use credentials created via Skyvern's API (stored in your configured vault) |
| `bitwarden` | Directly reference Bitwarden vault items by collection/item ID |
| `1password` | Directly reference 1Password vault items by vault/item ID |
| `azure_vault` | Directly reference Azure Key Vault secrets by name |
---
## Managing credentials
### List credentials
<CodeGroup>
```python Python
credentials = await client.get_credentials()
for cred in credentials:
print(f"{cred.name}: {cred.credential_id}")
```
```bash cURL
curl -X GET "https://api.skyvern.com/v1/credentials" \
-H "x-api-key: $SKYVERN_API_KEY"
```
</CodeGroup>
### Get credential metadata
<CodeGroup>
```python Python
credential = await client.get_credential("cred_xyz789")
print(f"Name: {credential.name}")
print(f"Type: {credential.credential_type}")
```
```bash cURL
curl -X GET "https://api.skyvern.com/v1/credentials/cred_xyz789" \
-H "x-api-key: $SKYVERN_API_KEY"
```
</CodeGroup>
<Note>
The GET endpoint returns metadata only, never the actual credential values. This is by design for security.
</Note>
### Delete a credential
<CodeGroup>
```python Python
await client.delete_credential("cred_xyz789")
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/credentials/cred_xyz789/delete" \
-H "x-api-key: $SKYVERN_API_KEY"
```
</CodeGroup>
<Warning>
Credential deletion is permanent. Workflows using the deleted credential will fail on their next run.
</Warning>
---
## Security architecture
Skyvern's credential handling is designed with security at every layer:
1. **Vault fetch**: Credentials are retrieved from your external vault only when needed
2. **Memory only**: Values exist in Skyvern's memory briefly during execution
3. **Placeholder tokens**: When sending data to LLMs, real values are replaced with tokens like `BW_PASSWORD`
4. **No persistence**: Real values are never written to databases, logs, or API responses
5. **LLM isolation**: Credentials are never sent to language models. The LLM sees only placeholder tokens
<Note>
When you view a run's artifacts or recordings, you'll see placeholder values like `BW_PASSWORD`, `BW_USERNAME`, or `BW_TOTP` instead of actual credentials.
</Note>
---
## Next steps
<CardGroup cols={2}>
<Card title="Handle 2FA" icon="shield" href="/developers/credentials/handle-2fa">
Set up two-factor authentication for your automations
</Card>
<Card title="Troubleshooting" icon="wrench" href="/developers/credentials/troubleshooting-login">
Debug common login failures
</Card>
</CardGroup>
@@ -0,0 +1,349 @@
---
title: Troubleshooting Login Failures
subtitle: Debug common authentication issues in your automations
description: Debug common login failures in Skyvern automations including credential errors, expired 2FA codes, CAPTCHA blocks, SSO redirects, and multi-step login flows. Includes a step-by-step debugging checklist.
slug: developers/credentials/troubleshooting-login
keywords:
- login failure
- debug
- expired code
- CAPTCHA block
- SSO redirect
- multi-step login
- session timeout
- checklist
- recording
- screenshot
---
Login failures are the most common issue in web automation. This guide covers the most frequent problems and how to resolve them.
---
## Common failure patterns
### Credentials not entered
**Symptoms:** Task completes but login never happened. The final screenshot shows the login page.
**Causes:**
- Credential parameter not linked to workflow
- Wrong `credential_id` referenced
- Vault connection failed
**Solutions:**
1. Verify the credential exists:
```bash
curl -X GET "https://api.skyvern.com/v1/credentials/cred_xyz789" \
-H "x-api-key: $SKYVERN_API_KEY"
```
2. Check workflow parameter configuration to ensure the credential parameter is linked to a Login block
3. For vault integrations (Bitwarden, 1Password), verify connectivity:
- Check vault credentials are valid
- Ensure collection/vault IDs are correct
- Test vault access independently
---
### Wrong credentials entered
**Symptoms:** Site shows "Invalid username or password" error.
**Causes:**
- Credentials stored incorrectly in your vault
- Site expects different format (email vs username)
- Password contains special characters causing issues
**Solutions:**
1. **Verify credentials work manually**: Log in to the site yourself with the same credentials
2. **Check username format**: Some sites require email, others want a username:
```
❌ john.smith
✓ john.smith@company.com
```
3. **Test credential retrieval**: Create a simple test task to verify Skyvern can access the credential
4. **Check for copy/paste errors**: Re-enter credentials in your vault, avoiding trailing spaces
---
### 2FA code expired
**Symptoms:** "Invalid code" or "Code expired" error after entering TOTP.
**Causes:**
- Clock drift between Skyvern and your authenticator
- Code fetched too early in the 30-second window
- Multi-field entry took too long
**Solutions:**
1. **Skyvern handles timing automatically**: If a TOTP code has less than 20 seconds remaining, Skyvern uses the next code
2. **For pushed codes**: Ensure your forwarding pipeline sends codes promptly. Delays over 30 seconds cause expiration.
3. **Check system clocks**: If self-hosting, ensure your server time is synchronized (NTP)
4. **Retry the run**: Intermittent timing issues often resolve on retry
---
### 2FA code never received
**Symptoms:** Task times out waiting for verification code.
**Causes:**
- Push endpoint not forwarding codes
- `totp_url` returning errors
- `totp_identifier` mismatch between run and push
**Solutions:**
1. **Verify your push endpoint**: Check that it's receiving and forwarding codes:
```bash
# Test your Zapier/webhook endpoint manually
curl -X POST "https://api.skyvern.com/v1/credentials/totp" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"totp_identifier": "user@example.com",
"content": "Your code is 123456",
"source": "email"
}'
```
2. **Check `totp_identifier` matches**: The identifier in your login must exactly match what you push:
```python
# These must match exactly
result = await client.login(
credential_type="skyvern",
credential_id="cred_xyz789",
totp_identifier="user@example.com", # ← This
...
)
await client.send_totp_code(
totp_identifier="user@example.com", # ← Must match this
...
)
```
3. **List recent codes** to verify they're being received:
```bash
curl -X GET "https://api.skyvern.com/v1/credentials/totp?totp_identifier=user@example.com" \
-H "x-api-key: $SKYVERN_API_KEY"
```
4. **For pull-based 2FA**: Check your endpoint returns the correct format:
```json
{
"task_id": "tsk_123456",
"verification_code": "123456"
}
```
---
## Site-specific issues
### CAPTCHA blocking login
**Symptoms:** Login page shows CAPTCHA challenge that blocks automation.
**Solutions:**
1. **Use residential proxies**: Many CAPTCHAs trigger on datacenter IPs:
```python
result = await client.run_task(
url="https://portal.example.com/login",
prompt="Log in to the portal",
proxy_location="RESIDENTIAL",
)
```
2. **Some CAPTCHAs can be solved**: Skyvern's AI can solve simple image-based challenges
3. **Browser profiles help**: Persistent browser state reduces CAPTCHA frequency:
```python
result = await client.login(
credential_type="skyvern",
url="https://portal.example.com/login",
credential_id="cred_xyz789",
browser_profile_id="bp_abc123",
)
```
4. **For persistent CAPTCHAs**: Contact [support@skyvern.com](mailto:support@skyvern.com) for enterprise CAPTCHA solutions
---
### SSO/OAuth redirects
**Symptoms:** Task fails when encountering "Sign in with Google/Microsoft" or similar SSO flows.
**Solutions:**
1. **Prefer direct credentials**: SSO flows involve multiple domains and are harder to automate. If possible, use direct username/password login.
2. **For required SSO**: Use browser sessions to maintain authentication state:
```python
# First run: Complete SSO manually or with Skyvern
result = await client.run_task(
url="https://portal.example.com/login",
prompt="Log in using Google SSO",
browser_session_id="bs_xyz789", # Persistent session
)
# Subsequent runs: Reuse the authenticated session
result = await client.run_task(
url="https://portal.example.com/dashboard",
prompt="Navigate to reports",
browser_session_id="bs_xyz789",
)
```
3. **Check for direct login options**: Many sites offer traditional login alongside SSO (often under "Other login options")
---
### Multi-step login flows
**Symptoms:** Task enters username but fails to proceed to password page, or misses subsequent steps.
**Solutions:**
1. **Increase `max_steps`**: Multi-step logins require more navigation:
```python
result = await client.run_task(
url="https://portal.example.com/login",
prompt="Log in with my credentials",
max_steps=15, # Default is 10
)
```
2. **Use explicit prompts**: Guide Skyvern through the steps:
```python
result = await client.run_task(
url="https://portal.example.com/login",
prompt="""
1. Enter the username and click Next
2. Wait for the password page to load
3. Enter the password and click Sign In
4. If 2FA is required, enter the code
""",
)
```
<Tip>
For login flows with credentials, use the `login()` method, which handles credential retrieval and 2FA automatically. Use `run_task()` only for general automation without credential management.
</Tip>
3. **Review recordings**: Watch the recording artifact to see exactly where the flow breaks
---
## Debugging checklist
Use this checklist to systematically debug login failures:
<Accordion title="Step-by-step debugging process">
**1. Check run status**
```bash
curl -X GET "https://api.skyvern.com/v1/runs/YOUR_RUN_ID" \
-H "x-api-key: $SKYVERN_API_KEY"
```
Look at `status` and `failure_reason`.
**2. Review the recording**
Download the recording artifact and watch where the automation fails:
```bash
curl -X GET "https://api.skyvern.com/v1/runs/YOUR_RUN_ID/artifacts?artifact_type=recording" \
-H "x-api-key: $SKYVERN_API_KEY"
```
**3. Check the final screenshot**
```bash
curl -X GET "https://api.skyvern.com/v1/runs/YOUR_RUN_ID/artifacts?artifact_type=screenshot_final" \
-H "x-api-key: $SKYVERN_API_KEY"
```
**4. Verify credential access**
```bash
curl -X GET "https://api.skyvern.com/v1/credentials/YOUR_CREDENTIAL_ID" \
-H "x-api-key: $SKYVERN_API_KEY"
```
**5. For 2FA issues, check code history**
```bash
curl -X GET "https://api.skyvern.com/v1/credentials/totp?totp_identifier=YOUR_IDENTIFIER" \
-H "x-api-key: $SKYVERN_API_KEY"
```
**6. Review LLM reasoning**
Check `llm_request` and `llm_response` artifacts to understand what the AI was thinking.
</Accordion>
---
## Error messages reference
| Error | Meaning | Fix |
|-------|---------|-----|
| `FailedToGetTOTPVerificationCode` | HTTP request to `totp_url` failed | Check endpoint availability and response format |
| `NoTOTPVerificationCodeFound` | Polling timed out without receiving code | Ensure codes are pushed or endpoint returns codes |
| `TOTPExpiredError` | Code became invalid during entry | Usually auto-resolved on retry; check timing pipeline |
| `CredentialParameterNotFoundError` | Referenced credential parameter not found | Verify credential ID and parameter configuration |
| `CredentialParameterParsingError` | Failed to parse credential data | Check credential format matches expected schema |
| `CustomCredentialConfigurationError` | Custom vault service misconfigured | Verify API base URL and token are set correctly |
---
## Getting help
If you're stuck after trying the above solutions, contact Skyvern support with:
1. **Run ID**: The `run_id` from your failed run
2. **Recording**: Download and attach the recording artifact
3. **Description**: What you expected vs. what happened
4. **Target site**: The URL you're trying to automate (if not confidential)
Contact [support@skyvern.com](mailto:support@skyvern.com) or join our [Discord](https://discord.gg/skyvern) for community help.
---
## Next steps
<CardGroup cols={2}>
<Card title="Store Credentials" icon="key" href="/developers/credentials/store-credentials">
Review credential setup
</Card>
<Card title="Handle 2FA" icon="shield" href="/developers/credentials/handle-2fa">
Configure two-factor authentication
</Card>
</CardGroup>
+407
View File
@@ -0,0 +1,407 @@
---
title: Frequently Asked Questions
subtitle: Common questions and answers from the Skyvern community
description: Answers to common Skyvern questions covering troubleshooting failed tasks, workflow parameters, credentials, scheduling, proxy configuration, API polling, data extraction, and LLM model selection.
slug: developers/debugging/faq
keywords:
- FAQ
- common questions
- troubleshooting
- rate limit
- model selection
- polling
- concurrent runs
- community
---
## Troubleshooting
<Accordion title="Why did my task fail or terminate?">
Check these in order:
1. **Run status**: Use `get_run(run_id)` to see the status and `failure_reason`
2. **Timeline**: Use `get_run_timeline(run_id)` to find which block failed
3. **Artifacts**: Check `screenshot_final` to see where it stopped, and `recording` to watch what happened
Common causes:
- **`terminated`**: The AI couldn't complete the goal (CAPTCHA, login blocked, element not found)
- **`timed_out`**: Exceeded `max_steps`. Increase it or simplify the task
- **`failed`**: System error (browser crash, network failure)
See the [Troubleshooting Guide](/developers/debugging/troubleshooting-guide) for detailed steps.
</Accordion>
<Accordion title="Why is the AI clicking the wrong element?">
Multiple similar elements on the page can confuse the AI. Fix this by:
1. **Add visual context**: "Click the **blue** Submit button at the **bottom** of the form"
2. **Reference surrounding text**: "Click Download in the row that says 'January 2024'"
3. **Be specific about position**: "Click the first result" or "Click the link in the header"
Check the `llm_response_parsed` artifact to see what action the AI decided to take.
</Accordion>
<Accordion title="Why is my task timing out?">
Tasks time out when they exceed `max_steps` (default: 50). This happens when:
- The task is too complex for the step limit
- The AI gets stuck in a navigation loop
- Missing completion criteria causes infinite attempts
**Fixes:**
- Increase `max_steps` in your task parameters
- Add explicit completion criteria: "COMPLETE when you see 'Order confirmed'"
- Break complex tasks into multiple workflow blocks
</Accordion>
<Accordion title="Why can't Skyvern find an element on the page?">
Elements may not be detected if they:
- Load dynamically after the page appears
- Are inside an iframe
- Require scrolling to become visible
- Use unusual rendering (canvas, shadow DOM)
**Fixes:**
- Add `max_screenshot_scrolls` to capture lazy-loaded content
- Describe elements visually rather than by technical properties
- Add explicit wait or scroll instructions in your prompt
</Accordion>
<Accordion title="Why is the extracted data wrong or incomplete?">
Check the `screenshot_final` artifact to verify the AI ended on the right page.
Common causes:
- Prompt was ambiguous about what to extract
- `data_extraction_schema` descriptions weren't specific enough
- Multiple similar elements and the AI picked the wrong one
**Fixes:**
- Add specific descriptions: `"description": "The price in USD, without currency symbol"`
- Add visual hints: "The price is displayed in bold below the product title"
</Accordion>
---
## Workflows
<Accordion title="How do I pass parameters to a workflow?">
Define parameters in the workflow editor, then pass them when starting a run:
```python
result = await client.run_workflow(
workflow_id="wpid_123456",
parameters={
"url": "https://example.com",
"username": "user@example.com"
}
)
```
Parameters are available in prompts using `{{ parameter_name }}` syntax. See [Workflow Parameters](/cloud/building-workflows/add-parameters) for details.
</Accordion>
<Accordion title="How do I use credentials in a workflow?">
1. **Store credentials**: Go to Settings > Credentials and add your login
2. **Reference in workflow**: Select the credential in the Login block's credential dropdown
3. **Never hardcode**: Don't put passwords directly in prompts
The AI will automatically fill the credential fields when it encounters a login form. See [Credentials](/sdk-reference/credentials) for setup instructions.
</Accordion>
<Accordion title="Can I run workflows on a schedule?">
Yes. Skyvern has built-in cron-based scheduling for workflows. You define a cron expression and timezone, and Skyvern triggers the workflow automatically at each interval.
- **Cloud UI**: Create and manage schedules from the [Schedules page](/cloud/building-workflows/scheduling)
- **API**: Use the [scheduling API](/cloud/building-workflows/run-from-code#create-a-schedule) to create, update, enable/disable, and delete schedules programmatically
Scheduled runs appear in [Run History](/cloud/viewing-results/run-history) with a calendar icon badge. Set up a [webhook](/developers/going-to-production/webhooks) to get notified when scheduled runs complete.
</Accordion>
<Accordion title="Why isn't my workflow using the parameter values I passed?">
Make sure you're using the parameter placeholder syntax correctly:
- **Correct:** `{{ parameter_name }}`
- **Wrong:** `{parameter_name}` or `$parameter_name`
Also verify:
- The parameter name matches exactly (case-sensitive)
- The parameter is defined in the workflow's parameter list
- You're passing the parameter when starting the run, not after
</Accordion>
<Accordion title="How do I run workflows sequentially with the same credentials?">
Use the "Run Sequentially" option with a credential key:
1. Enable "Run Sequentially" in workflow settings
2. Set the sequential key to your credential identifier
3. Skyvern will queue runs that share the same credential
This prevents concurrent logins that could trigger security blocks.
</Accordion>
---
## Configuration
<Accordion title="Where do I find my API key?">
Go to [Settings](https://app.skyvern.com/settings) in the Skyvern Cloud UI. Your API key is displayed there.
For local installations, run `skyvern init` to generate a local API key, which will be saved in your `.env` file.
</Accordion>
<Accordion title="How do I change the LLM model?">
**Cloud:** The model is managed by Skyvern. Contact support for custom model requirements.
**Self-hosted:** Run `skyvern init llm` to reconfigure, or set these environment variables:
- `LLM_KEY`: Primary model (e.g., `OPENAI_GPT5_5`, `ANTHROPIC_CLAUDE4.7_OPUS`)
- `SECONDARY_LLM_KEY`: Optional lightweight model for faster operations
</Accordion>
<Accordion title="How do I configure proxy settings?">
Set `proxy_location` when running a task:
```python
result = await client.run_task(
prompt="...",
url="https://example.com",
proxy_location="RESIDENTIAL_US" # or RESIDENTIAL_ISP for static IPs
)
```
Available locations include `RESIDENTIAL_US`, `RESIDENTIAL_UK`, `RESIDENTIAL_ISP`, and more. Use `RESIDENTIAL_ISP` for sites that require consistent IP addresses.
</Accordion>
<Accordion title="Can I increase the max steps limit beyond 75?">
Yes. Contact support to increase the limit for your account. Higher limits may incur additional costs.
Alternatively, break complex tasks into multiple workflow blocks, each with its own step budget.
</Accordion>
---
## API & Integration
<Accordion title="How do I poll for task completion?">
Check the run status in a loop:
```python
while True:
run = await client.get_run(run_id)
if run.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
break
await asyncio.sleep(5)
```
Or use [webhooks](/developers/going-to-production/webhooks) to get notified when runs complete without polling.
</Accordion>
<Accordion title="Where can I find extracted data after a run completes?">
The extracted data is in `run.output`:
```python
run = await client.get_run(run_id)
print(run.output) # {"field1": "value1", "field2": "value2"}
```
For downloaded files, check `run.downloaded_files` which contains signed URLs.
</Accordion>
<Accordion title="How do I get the recording URL from the API?">
The recording URL is included in the run response:
```python
run = await client.get_run(run_id)
print(run.recording_url) # https://skyvern-artifacts.s3.amazonaws.com/.../recording.webm
```
Note: Signed URLs expire after 24 hours. Request fresh URLs if expired.
</Accordion>
<Accordion title="How do I trigger a workflow via API?">
Use the `run_workflow` method:
```python
result = await client.run_workflow(
workflow_id="wpid_123456",
parameters={"key": "value"}
)
print(result.run_id) # wr_789012
```
The workflow starts asynchronously. Poll the run status or configure a webhook to track completion.
</Accordion>
---
## Authentication & Credentials
<Accordion title="Why is my login failing?">
Check these common causes:
1. **Credentials expired**: Verify username/password in your credential store
2. **CAPTCHA appeared**: Use a browser profile with an existing session
3. **MFA required**: Configure TOTP if the site requires 2FA
4. **Site detected automation**: Use `RESIDENTIAL_ISP` proxy for trusted IPs
Watch the `recording` artifact to see exactly what happened during login.
</Accordion>
<Accordion title="How do I handle CAPTCHA?">
Options to bypass CAPTCHAs:
1. **Browser profile**: Create a profile with an authenticated session that skips login entirely
2. **Human interaction block**: Pause the workflow for manual CAPTCHA solving
3. **Residential proxy**: Use `RESIDENTIAL_ISP` for static IPs that sites trust more
Skyvern has built-in CAPTCHA solving for common types, but some sites use advanced anti-bot measures.
</Accordion>
<Accordion title="How do I set up 2FA/TOTP?">
1. Go to Settings > Credentials
2. Create a new TOTP credential with your authenticator secret
3. Reference the TOTP credential in your workflow's login block
The AI will automatically fetch and enter the TOTP code when it encounters a 2FA prompt. See [TOTP Setup](/developers/credentials/totp) for detailed instructions.
</Accordion>
<Accordion title="How do I handle email OTP verification?">
Email OTP requires an external integration:
1. Set up an email listener (Zapier, custom webhook, etc.)
2. When the OTP arrives, send it back to Skyvern via the API
3. Use a Human Interaction block to wait for the code
Alternatively, check if the site supports TOTP authenticators, which Skyvern handles natively.
</Accordion>
---
## Browser & Proxy
<Accordion title="Why is the site blocking Skyvern?">
Sites may detect automation through:
- IP reputation (datacenter IPs are often blocked)
- Browser fingerprinting
- Rate limiting
**Fixes:**
- Use `RESIDENTIAL_ISP` proxy for consistent, trusted IPs
- Create a browser profile with an existing authenticated session
- Slow down requests by adding explicit waits in your prompt
</Accordion>
<Accordion title="How do I persist cookies across runs?">
Use browser profiles:
1. Create a browser profile in Settings > Browser Profiles
2. Log in manually or via a workflow
3. Reference the `browser_profile_id` in subsequent runs
The profile preserves cookies, localStorage, and session state across runs.
</Accordion>
<Accordion title="Can I connect Skyvern to my local browser?">
Yes, for self-hosted installations:
```bash
skyvern init # Choose "connect to existing Chrome" option
skyvern run server
```
This connects to Chrome running on your machine, useful for debugging or accessing internal tools.
</Accordion>
<Accordion title="Why am I getting a 504 timeout when creating browser sessions?">
This usually indicates high load or network issues:
- Wait a few seconds and retry
- Check your rate limits
- For self-hosted: verify your infrastructure has sufficient resources
If persistent, contact support with your run IDs.
</Accordion>
---
## Self-Hosting & Deployment
<Accordion title="What are the requirements for self-hosting Skyvern?">
- Python 3.11, 3.12, or 3.13
- PostgreSQL database
- An LLM API key (OpenAI, Anthropic, Azure, Gemini, or Ollama)
- Docker (optional, for containerized deployment)
Run `skyvern init` for an interactive setup wizard. See the [Quickstart](/developers/getting-started/quickstart) for full instructions.
</Accordion>
<Accordion title="How do I update my self-hosted Skyvern instance?">
```bash
pip install --upgrade skyvern
alembic upgrade head # Run database migrations
skyvern run server # Restart the server
```
For Docker deployments, pull the latest image and restart your containers.
</Accordion>
<Accordion title="How do I configure a custom LLM provider?">
Set these environment variables:
```bash
ENABLE_OPENAI=true # or ENABLE_ANTHROPIC, ENABLE_AZURE, etc.
OPENAI_API_KEY=sk-...
LLM_KEY=OPENAI_GPT5_5
```
Skyvern supports OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, Gemini, and Ollama. Run `skyvern init llm` for guided configuration.
</Accordion>
---
## Billing & Pricing
<Accordion title="How is pricing calculated?">
Pricing depends on your plan:
- **Pay-as-you-go**: Charged per step or per task completion
- **Enterprise**: Custom pricing based on volume
View your usage and billing at [Settings > Billing](https://app.skyvern.com/billing).
</Accordion>
<Accordion title="Why does it say insufficient balance when I have credit?">
Credits may be reserved for in-progress runs. Check:
1. Active runs that haven't completed yet
2. Failed runs that consumed partial credit
3. Pending charges that haven't settled
Wait for active runs to complete, then check your balance again.
</Accordion>
<Accordion title="How do I get invoices for my payments?">
Go to [Settings > Billing](https://app.skyvern.com/billing) to download invoices. For custom invoice requirements (company name, VAT, etc.), contact support.
</Accordion>
---
## Still have questions?
<CardGroup cols={2}>
<Card
title="Troubleshooting Guide"
icon="wrench"
href="/developers/debugging/troubleshooting-guide"
>
Step-by-step debugging for failed runs
</Card>
<Card
title="Contact Support"
icon="headset"
href="https://app.skyvern.com"
>
Chat with us via the support widget
</Card>
</CardGroup>
@@ -0,0 +1,229 @@
---
title: Observability with Laminar
subtitle: Add observability to your Skyvern automations with Laminar
description: Integrate Laminar observability into Skyvern to capture traces of automation runs, track LLM call latency and token usage, monitor failure rates, and debug performance across tasks and workflows.
slug: developers/debugging/observability-with-laminar
keywords:
- Laminar
- traces
- LLM latency
- token usage
- failure rate
- monitoring
- performance
- observability
---
[Laminar](https://www.lmnr.ai/) is an observability platform for AI applications. When integrated with Skyvern, it captures traces of your automation runs in Laminar's dashboard. What you see depends on how you're running Skyvern:
- **Skyvern Cloud (via SDK)**: Laminar wraps the `run_task` / `run_workflow` call, so you get a trace span around the API request and response: latency, status, errors, and the returned output.
- **Self-hosted**: Skyvern's server can export full traces to Laminar, including every LLM call (prompts, responses, token usage), browser actions, and workflow step execution. See [self-hosted tracing setup](#self-hosted-tracing-setup) below.
<Tip>
Laminar traces complement [artifacts](/developers/debugging/using-artifacts). Use artifacts for per-run debugging (screenshots, recordings, logs) and Laminar for tracking patterns across runs (failure rates, response times, and which tasks are slowest).
</Tip>
<Note>
This guide is also available in the [Laminar documentation](https://docs.lmnr.ai/tracing/integrations/skyvern).
</Note>
---
## Prerequisites
Laminar integration requires a Skyvern SDK and the Laminar SDK:
<CodeGroup>
```bash Python
pip install skyvern 'lmnr[all]'
```
```bash TypeScript
npm install @skyvern/client @lmnr-ai/lmnr
```
</CodeGroup>
You will also need:
- A **Skyvern API key**: get one at [app.skyvern.com/settings](https://app.skyvern.com/settings/)
- A **Laminar API key**: sign up at [lmnr.ai](https://www.lmnr.ai/) and create a project
---
## Set up environment variables
Add both keys to your `.env` file:
```bash .env
SKYVERN_API_KEY=your-skyvern-api-key
LMNR_PROJECT_API_KEY=your-laminar-api-key
```
<Frame>
<video
autoPlay
controls
muted
playsInline
className="w-full aspect-video rounded-xl"
src="/images/laminar-keys.mp4"
></video>
</Frame>
---
## Run a traced task
This example scrapes the top 3 posts from Hacker News with Laminar tracing enabled. Call `Laminar.initialize()` before any Skyvern calls; it reads `LMNR_PROJECT_API_KEY` from your environment automatically.
<CodeGroup>
```python Python
import os
import asyncio
from dotenv import load_dotenv
load_dotenv()
from lmnr import Laminar
Laminar.initialize()
from skyvern import Skyvern
client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
async def main():
result = await client.run_task(
prompt="Get the title and URL of the top 3 posts on Hacker News.",
url="https://news.ycombinator.com",
wait_for_completion=True,
)
print(f"Status: {result.status}")
print(f"Output: {result.output}")
if __name__ == "__main__":
asyncio.run(main())
```
```typescript TypeScript
import { Laminar } from "@lmnr-ai/lmnr";
Laminar.initialize();
import { Skyvern } from "@skyvern/client";
const client = new Skyvern({
apiKey: process.env.SKYVERN_API_KEY,
});
async function main() {
const result = await client.runTask({
body: {
prompt: "Get the title and URL of the top 3 posts on Hacker News.",
url: "https://news.ycombinator.com",
},
waitForCompletion: true,
});
console.log(`Status: ${result.status}`);
console.log(`Output: ${JSON.stringify(result.output, null, 2)}`);
}
main();
```
</CodeGroup>
Expected output:
```json
{
"status": "completed",
"output": {
"posts": [
{"title": "Zig – Type Resolution Redesign and Language Changes", "url": "https://ziglang.org/devlog/2026/..."},
{"title": "Create value for others and don't worry about the returns", "url": "https://geohot.github.io/..."},
{"title": "U+237C ⍼ Is Azimuth", "url": "https://ionathan.ch/2026/02/16/angzarr.html"}
]
}
}
```
The task runs, the output is returned, and the full trace (every HTTP call, timing, and payload) appears in your Laminar dashboard.
<Note>
**Python only:** You will see a `ForgeApp is not initialized` error in stderr on startup. This is harmless; `lmnr[all]` tries to instrument Skyvern's server-side internals, which aren't present when using the client SDK. Your traces still work correctly.
</Note>
<Warning>
**Python only:** `LaminarLiteLLMCallback` is deprecated and unnecessary. Laminar instruments LiteLLM directly, so no callback setup is needed.
</Warning>
---
## What traces capture
What shows up in Laminar depends on your setup.
### Skyvern Cloud (via SDK)
When calling `run_task` or `run_workflow` through the SDK, Laminar traces the client-side call:
| Trace data | What it shows |
|------------|---------------|
| API request/response | The full round-trip to Skyvern's API (status, latency, payload size) |
| Task output | The extracted data or completion result |
| Errors | HTTP errors, timeouts, and task failures |
This is useful for monitoring how your application interacts with Skyvern: tracking which tasks fail, how long they take, and what outputs you're getting back.
### Self-hosted
When running Skyvern on your own infrastructure, you get deep server-side traces by configuring Laminar in Skyvern's environment. This gives you visibility into everything happening inside the agent:
| Trace data | What it shows |
|------------|---------------|
| LLM interactions | Every prompt sent to the model and its response, including token counts |
| Browser actions | Each click, type, and navigation the agent performed |
| Workflow steps | Sequential block execution and data passed between blocks |
| Image tracing | Screenshots sent to the LLM for analysis |
| Performance metrics | Latency and cost per LLM call |
| Errors | Exceptions at any layer: LLM, browser, workflow engine |
---
## Self-hosted tracing setup
If you're running Skyvern on your own infrastructure, add these to your server's environment:
```bash .env
LMNR_PROJECT_API_KEY=your-laminar-api-key
```
Skyvern's server initializes Laminar at startup, which auto-instruments LiteLLM to capture every LLM call, token count, and cost. No manual callback setup is needed.
If you're running a self-hosted Laminar instance, also set the base URL and ports:
```bash .env
LMNR_PROJECT_API_KEY=your-laminar-api-key
LMNR_BASE_URL=http://localhost
LMNR_GRPC_PORT=8011
LMNR_HTTP_PORT=8010
```
No code changes needed. Once the env vars are set, traces appear in your Laminar project automatically.
---
## Next steps
<CardGroup cols={2}>
<Card
title="Using Artifacts"
icon="file-lines"
href="/developers/debugging/using-artifacts"
>
Per-run recordings, screenshots, logs, and network data
</Card>
<Card
title="Troubleshooting Guide"
icon="wrench"
href="/developers/debugging/troubleshooting-guide"
>
Common issues and how to fix them
</Card>
</CardGroup>
@@ -0,0 +1,386 @@
---
title: Troubleshooting Guide
subtitle: Common issues, step timeline, and when to adjust what
description: Diagnose and fix common Skyvern run failures using the step timeline, artifacts, and run status. Covers issues like wrong output, timeouts, CAPTCHA blocks, login failures, and element detection problems.
slug: developers/debugging/troubleshooting-guide
keywords:
- step timeline
- wrong output
- timeout
- CAPTCHA block
- login failure
- element detection
- action failure
- diagnosis
---
When a run fails or produces unexpected results, this guide helps you identify the cause and fix it.
## Quick debugging checklist
<Frame>
<img src="/images/debugging-checklist.png" alt="Skyvern Debugging Checklist" />
</Frame>
<Steps>
<Step title="Check run status">
Call `get_run(run_id)` and check `status` and `failure_reason`
</Step>
<Step title="Find the failed step">
Call `get_run_timeline(run_id)` to see which block failed
</Step>
<Step title="Inspect artifacts">
Check `screenshot_final` to see where it stopped, `recording` to watch what happened
</Step>
<Step title="Determine the fix">
Adjust prompt, parameters, or file a bug based on what you find
</Step>
</Steps>
**Key artifacts to check:**
- `screenshot_final`: Final page state
- `recording`: Video of what happened
- `llm_response_parsed`: What the AI decided to do
- `visible_elements_tree`: What elements were detected
- `har`: Network requests if something failed to load
---
## Step 1: Check the run
<CodeGroup>
```python Python
import os
from skyvern import Skyvern
client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
run = await client.get_run(run_id)
print(f"Status: {run.status}")
print(f"Failure reason: {run.failure_reason}")
print(f"Step count: {run.step_count}")
print(f"Output: {run.output}")
```
```typescript TypeScript
import { SkyvernClient } from "@skyvern/client";
const client = new SkyvernClient({
apiKey: process.env.SKYVERN_API_KEY,
});
const run = await client.getRun(runId);
console.log(`Status: ${run.status}`);
console.log(`Failure reason: ${run.failure_reason}`);
console.log(`Step count: ${run.step_count}`);
console.log(`Output: ${JSON.stringify(run.output)}`);
```
```bash cURL
curl -X GET "https://api.skyvern.com/v1/runs/$RUN_ID" \
-H "x-api-key: $SKYVERN_API_KEY" \
| jq '{status, failure_reason, step_count, output}'
```
</CodeGroup>
| Status | What it means | Likely cause |
|--------|---------------|--------------|
| `completed` | Run finished, but output may be wrong | Prompt interpretation issue |
| `failed` | System error | Browser crash, network failure |
| `terminated` | AI gave up | Login blocked, CAPTCHA, page unavailable |
| `timed_out` | Exceeded `max_steps` | Task too complex, or AI got stuck |
| `canceled` | Manually stopped | N/A |
---
## Step 2: Read the step timeline
The timeline shows each block and action in execution order.
<CodeGroup>
```python Python
timeline = await client.get_run_timeline(run_id)
for item in timeline:
if item.type == "block":
block = item.block
print(f"Block: {block.label}")
print(f" Status: {block.status}")
print(f" Duration: {block.duration}s")
if block.failure_reason:
print(f" Failure: {block.failure_reason}")
for action in block.actions:
print(f" Action: {action.action_type} -> {action.status}")
```
```typescript TypeScript
const timeline = await client.getRunTimeline(runId);
for (const item of timeline) {
if (item.type === "block") {
const block = item.block;
console.log(`Block: ${block.label}`);
console.log(` Status: ${block.status}`);
console.log(` Duration: ${block.duration}s`);
if (block.failure_reason) {
console.log(` Failure: ${block.failure_reason}`);
}
for (const action of block.actions || []) {
console.log(` Action: ${action.action_type} -> ${action.status}`);
}
}
}
```
```bash cURL
curl -X GET "https://api.skyvern.com/v1/runs/$RUN_ID/timeline" \
-H "x-api-key: $SKYVERN_API_KEY"
```
</CodeGroup>
---
## Step 3: Inspect artifacts
<CodeGroup>
```python Python
artifacts = await client.get_run_artifacts(
run_id,
artifact_type=["screenshot_final", "llm_response_parsed", "skyvern_log"]
)
for a in artifacts:
print(f"{a.artifact_type}: {a.signed_url}")
```
```typescript TypeScript
const artifacts = await client.getRunArtifacts(runId, {
artifact_type: ["screenshot_final", "llm_response_parsed", "skyvern_log"]
});
for (const a of artifacts) {
console.log(`${a.artifact_type}: ${a.signed_url}`);
}
```
```bash cURL
curl -X GET "https://api.skyvern.com/v1/runs/$RUN_ID/artifacts?artifact_type=screenshot_final&artifact_type=llm_response_parsed&artifact_type=skyvern_log" \
-H "x-api-key: $SKYVERN_API_KEY" \
| jq '.[] | "\(.artifact_type): \(.signed_url)"'
```
</CodeGroup>
See [Using Artifacts](/developers/debugging/using-artifacts) for the full list of artifact types.
---
## Common issues and fixes
### Run Status Issues
<Accordion title="Run completed but output is wrong">
**Symptom:** Status is `completed`, but the extracted data is incorrect or incomplete.
**Check:** `screenshot_final` (right page?) and `llm_response_parsed` (right elements?)
**Fix:**
- Add specific descriptions in your schema: `"description": "The price in USD, without currency symbol"`
- Add visual hints: "The price is displayed in bold below the product title"
</Accordion>
<Accordion title="Run timed out">
**Symptom:** Status is `timed_out`.
**Check:** `recording` (stuck in a loop?) and `step_count` (how many steps?)
**Fix:**
- Increase `max_steps` if the task genuinely needs more steps
- Add explicit completion criteria: "COMPLETE when you see 'Order confirmed'"
- Break complex tasks into multiple workflow blocks
</Accordion>
<Accordion title="Run stuck in queued state">
**Symptom:** Run stays in `queued` status and never starts.
**Likely causes:** Concurrency limit hit, sequential run lock, or high platform load.
**Fix:**
- Wait for other runs to complete
- Check your plan's concurrency limits in Settings
- If using "Run Sequentially" with credentials, ensure prior runs finish
</Accordion>
<Accordion title="504 Gateway Timeout on browser session">
**Symptom:** Getting `504 Gateway Timeout` errors when creating browser sessions.
**Fix:**
- Retry after a few seconds; usually transient
- For self-hosted: check infrastructure resources
- If persistent, contact support with your run IDs
</Accordion>
### Element & Interaction Issues
<Accordion title="AI clicked the wrong element">
**Symptom:** Recording shows the AI clicking something other than intended.
**Check:** `visible_elements_tree` (element detected?) and `llm_prompt` (target described clearly?)
**Fix:**
- Add distinguishing details: "Click the **blue** Submit button at the **bottom** of the form"
- Reference surrounding text: "Click Download in the row that says 'January 2024'"
</Accordion>
<Accordion title="Element not found">
**Symptom:** `failure_reason` mentions an element couldn't be found.
**Check:** `screenshot_final` (element visible?) and `visible_elements_tree` (element detected?)
**Likely causes:** Dynamic loading, iframe, below the fold, unusual rendering (canvas, shadow DOM)
**Fix:**
- Add `max_screenshot_scrolls` to capture lazy-loaded content
- Describe elements visually rather than by technical properties
- Add wait or scroll instructions in your prompt
</Accordion>
<Accordion title="Date fields entering wrong values">
**Symptom:** Dates entered in wrong format (MM/DD vs DD/MM) or wrong date entirely.
**Check:** `recording` (how did AI interact with the date picker?)
**Fix:**
- Specify exact format: "Enter the date as **15/01/2024** (DD/MM/YYYY format)"
- For date pickers: "Click the date field, then select January 15, 2024 from the calendar"
- If site auto-formats: "Type 01152024 and let the field format it"
</Accordion>
<Accordion title="Address autocomplete cycling or wrong selection">
**Symptom:** AI keeps clicking through address suggestions in a loop, or selects wrong address.
**Check:** `recording` (is autocomplete dropdown appearing?)
**Fix:**
- Specify selection: "Type '123 Main St' and select the first suggestion showing 'New York, NY'"
- Disable autocomplete: "Type the full address without using autocomplete suggestions"
- Break into steps: "Enter street address, wait for dropdown, select the matching suggestion"
</Accordion>
### Authentication Issues
<Accordion title="Login failed">
**Symptom:** Status is `terminated` with login-related failure reason.
**Check:** `screenshot_final` (error message?) and `recording` (fields filled correctly?)
**Likely causes:** Expired credentials, CAPTCHA, MFA required, automation detected
**Fix:**
- Verify credentials in your credential store
- Use `RESIDENTIAL_ISP` proxy for more stable IPs
- Configure TOTP if MFA is required
- Use a browser profile with an existing session
</Accordion>
<Accordion title="CAPTCHA blocked the run">
**Symptom:** `failure_reason` mentions CAPTCHA.
**Fix options:**
1. **Browser profile**: Use an authenticated session that skips login
2. **Human interaction block**: Pause for manual CAPTCHA solving
3. **Different proxy**: Use `RESIDENTIAL_ISP` for static IPs sites trust more
</Accordion>
### Data & Output Issues
<Accordion title="AI hallucinating or inventing data">
**Symptom:** Extracted data contains information not on the page.
**Check:** `screenshot_final` (data visible?) and `llm_response_parsed` (what did AI claim to see?)
**Fix:**
- Add instruction: "Only extract data **visibly displayed** on the page. Return null if not found"
- Make schema fields optional where appropriate
- Add validation: "If price is not displayed, set price to null instead of guessing"
</Accordion>
<Accordion title="File downloads not working">
**Symptom:** Files download repeatedly, wrong files, or downloads don't complete.
**Check:** `recording` (download button clicked correctly?) and `downloaded_files` in response
**Fix:**
- Be specific: "Click the **PDF** download button, not the Excel one"
- Add wait time: "Wait for the download to complete"
- For multi-step downloads: "Click Download, then select PDF format, then click Confirm"
</Accordion>
### Environment Issues
<Accordion title="Site showing content in wrong language">
**Symptom:** Site displays in unexpected language based on proxy location.
**Check:** What `proxy_location` is being used? Does site geo-target?
**Fix:**
- Use appropriate proxy: `RESIDENTIAL_US` for English US sites
- Add instruction: "If the site asks for language preference, select English"
- Set language in URL: `https://example.com/en/`
</Accordion>
<Accordion title="Workflow gets stuck in a loop">
**Symptom:** Recording shows AI repeating the same actions without progressing.
**Check:** `recording` (what pattern is repeating?) and conditional block exit conditions
**Fix:**
- Add termination: "STOP if you've attempted this action 3 times without success"
- Add completion markers: "COMPLETE when you see 'Success' message"
- Review loop conditions to ensure exit criteria are achievable
</Accordion>
---
## When to adjust prompts vs parameters
<CardGroup cols={3}>
<Card title="Adjust prompt" icon="pen">
- AI misunderstood what to do
- Clicked wrong element
- Ambiguous completion criteria
- Extracted wrong data
</Card>
<Card title="Adjust parameters" icon="sliders">
- Timed out → increase `max_steps`
- Site blocked → change `proxy_location`
- Content didn't load → increase `max_screenshot_scrolls`
</Card>
<Card title="File a bug" icon="bug">
- Visible element not detected
- Standard UI patterns don't work
- Consistent wrong element despite clear prompts
</Card>
</CardGroup>
---
## Next steps
<CardGroup cols={2}>
<Card
title="Using Artifacts"
icon="file-lines"
href="/developers/debugging/using-artifacts"
>
Detailed reference for all artifact types
</Card>
<Card
title="Reliability Tips"
icon="shield-check"
href="/developers/going-to-production/reliability-tips"
>
Write prompts that fail less often
</Card>
</CardGroup>
@@ -0,0 +1,222 @@
---
title: Using Artifacts
subtitle: Access recordings, screenshots, logs, and network data for every run
description: Retrieve and inspect artifacts from Skyvern runs including browser recordings, screenshots, AI reasoning logs, DOM element trees, network HAR files, and Playwright traces to debug failures and unexpected results.
slug: developers/debugging/using-artifacts
keywords:
- artifact
- recording
- screenshot
- HAR file
- Playwright trace
- DOM tree
- AI reasoning log
- network data
- generated code
---
When a Skyvern run fails or produces unexpected results, artifacts are your debugging toolkit. Every run automatically captures what happened: recordings of the browser session, screenshots at each step, the AI's reasoning, and network traffic.
This page covers how to retrieve artifacts and what each type tells you.
<Tip>
Looking for a specific artifact type? Jump to the [artifact types reference](#artifact-types-reference) to see all available types, then come back here to learn how to retrieve them.
</Tip>
---
## Before you start
You need a `run_id` to retrieve artifacts. You get this when you [run a task](/running-automations/run-a-task) or workflow.
---
## Retrieve artifacts
Use `get_run_artifacts` with the `run_id` from your task or workflow run:
<CodeGroup>
```python Python
import os
from skyvern import Skyvern
client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
artifacts = await client.get_run_artifacts(run_id)
for artifact in artifacts:
print(f"{artifact.artifact_type}: {artifact.signed_url}")
```
```typescript TypeScript
import { SkyvernClient } from "@skyvern/client";
const client = new SkyvernClient({
apiKey: process.env.SKYVERN_API_KEY,
});
const artifacts = await client.getRunArtifacts(runId);
for (const artifact of artifacts) {
console.log(`${artifact.artifact_type}: ${artifact.signed_url}`);
}
```
```bash cURL
curl -X GET "https://api.skyvern.com/v1/runs/$RUN_ID/artifacts" \
-H "x-api-key: $SKYVERN_API_KEY"
```
</CodeGroup>
<Note>
Signed URLs expire after 24 hours. If a URL has expired, call `get_run_artifacts` again to get fresh URLs. When running Skyvern locally, `signed_url` will be `null`. Access artifacts directly from your local file system instead.
</Note>
---
## Filter by artifact type
To get only specific artifact types, pass `artifact_type`:
<CodeGroup>
```python Python
# Get only recordings and final screenshots
artifacts = await client.get_run_artifacts(
run_id,
artifact_type=["recording", "screenshot_final"]
)
```
```typescript TypeScript
const artifacts = await client.getRunArtifacts(runId, {
artifact_type: ["recording", "screenshot_final"],
});
```
```bash cURL
curl -X GET "https://api.skyvern.com/v1/runs/$RUN_ID/artifacts?artifact_type=recording&artifact_type=screenshot_final" \
-H "x-api-key: $SKYVERN_API_KEY"
```
</CodeGroup>
---
## Artifact types reference
### Visual artifacts
These show you what the browser looked like at various points.
| Type | What it contains | Use this to |
|------|------------------|-------------|
| `recording` | Full video of the browser session (WebM) | Watch the entire run, see exactly what happened |
| `screenshot` | Base screenshot capture | General page state capture |
| `screenshot_final` | Screenshot when the run ended | Check the final state (did it end on the right page?) |
| `screenshot_action` | Screenshot taken after each action | See the page state after each click, type, or navigation |
| `screenshot_llm` | Screenshot sent to the LLM for decision-making | Understand what the AI "saw" when it made each decision |
**Debugging tip:** If the run failed, start with `screenshot_final` to see where it stopped, then watch the `recording` to see how it got there.
### AI reasoning artifacts
These show you why the AI made each decision.
| Type | What it contains | Use this to |
|------|------------------|-------------|
| `llm_prompt` | The prompt sent to the LLM | See exactly what instructions the AI received |
| `llm_request` | Full request including context | Check if the right context was included |
| `llm_response` | Raw LLM response | See the AI's unprocessed output |
| `llm_response_parsed` | Parsed response (extracted actions) | Understand what actions the AI decided to take |
| `llm_response_rendered` | Parsed response with real URLs | Debug URL targeting issues (see below) |
**Debugging tip:** If the AI did something unexpected, check `llm_prompt` to see if your prompt was interpreted correctly, then `llm_response_parsed` to see what action it extracted.
**About `llm_response_rendered`:** Skyvern hashes URLs before sending them to the LLM to reduce token usage and avoid confusing the model with long query strings. The `llm_response_parsed` artifact contains these hashed placeholders (like `{{_a1b2c3}}`), while `llm_response_rendered` shows the same response with actual URLs substituted back in. Use this when you need to verify which exact URL the AI targeted.
### Page structure artifacts
These show how Skyvern interpreted the page.
| Type | What it contains | Use this to |
|------|------------------|-------------|
| `visible_elements_tree` | DOM tree of visible elements (JSON) | See which elements Skyvern detected |
| `visible_elements_tree_trimmed` | Trimmed tree (sent to LLM) | See what the AI could "see" |
| `visible_elements_tree_in_prompt` | Element tree as plain text | Read exactly what was embedded in the prompt |
| `visible_elements_id_css_map` | CSS selectors for each element | Debug element targeting issues |
| `visible_elements_id_frame_map` | Element-to-iframe mapping | Debug elements inside iframes |
| `visible_elements_id_xpath_map` | XPath selectors for each element | Alternative element targeting debug |
| `hashed_href_map` | Mapping of hashed URLs to original URLs | Decode URL placeholders in LLM responses |
| `html` | Generic HTML capture | Inspect page HTML |
| `html_scrape` | Full HTML captured during scraping | Inspect the raw page structure |
| `html_action` | HTML captured after an action | See how the page changed after each action |
**Debugging tip:** If the AI couldn't find an element, check `visible_elements_tree` to see if it was detected. If not, the element might be in an iframe, dynamically loaded, or outside the viewport.
**About the element tree variants:** The `visible_elements_tree` is a JSON structure, while `visible_elements_tree_in_prompt` is the plain-text representation that gets embedded directly into the LLM prompt. The latter is often easier to read when debugging prompt issues. If you're debugging iframe-related problems, `visible_elements_id_frame_map` shows which frame contains each element ID.
### Log artifacts
These contain structured execution data.
| Type | What it contains | Use this to |
|------|------------------|-------------|
| `skyvern_log` | Formatted execution logs | Read through the run step-by-step |
| `skyvern_log_raw` | Raw JSON logs | Parse programmatically for automation |
| `browser_console_log` | Browser console output | Debug JavaScript errors on the page |
**Debugging tip:** `skyvern_log` is human-readable and shows the flow of execution. Start here for an overview before diving into specific artifacts.
### Network artifacts
| Type | What it contains | Use this to |
|------|------------------|-------------|
| `har` | HTTP Archive (network requests/responses) | Debug API calls, check for failed requests, see response data |
| `trace` | Playwright trace file | Replay the session in Playwright Trace Viewer |
**Debugging tip:** The HAR file captures every network request. If a form submission failed, check the HAR to see if the request was sent and what the server responded.
### File artifacts
| Type | What it contains | Use this to |
|------|------------------|-------------|
| `script_file` | Generated Playwright scripts | See the code Skyvern would use to repeat this task |
---
## Artifact response fields
| Field | Type | Description |
|-------|------|-------------|
| `artifact_id` | string | Unique identifier |
| `artifact_type` | string | Type (see tables above) |
| `uri` | string | Internal storage path |
| `signed_url` | string \| null | Pre-signed URL for downloading |
| `task_id` | string \| null | Associated task ID |
| `step_id` | string \| null | Associated step ID |
| `run_id` | string \| null | Run ID (e.g., `tsk_v2_...`, `wr_...`) |
| `workflow_run_id` | string \| null | Workflow run ID |
| `workflow_run_block_id` | string \| null | Workflow block ID |
| `organization_id` | string | Your organization |
| `created_at` | datetime | When created |
| `modified_at` | datetime | When modified |
---
## Next steps
<CardGroup cols={2}>
<Card
title="Troubleshooting Guide"
icon="wrench"
href="/developers/debugging/troubleshooting-guide"
>
Common issues and how to fix them
</Card>
<Card
title="Error Handling"
icon="triangle-exclamation"
href="/developers/going-to-production/error-handling"
>
Map errors to custom codes for programmatic handling
</Card>
</CardGroup>
@@ -0,0 +1,68 @@
---
title: Authentication & 2FA
subtitle: Log in to any site, including sites with multi-factor authentication
description: Skyvern handles logins with stored credentials, TOTP/authenticator codes, email and SMS verification, magic links, and password manager integrations with Bitwarden, 1Password, and Azure Key Vault.
slug: developers/features/authentication-and-2fa
icon: key
keywords:
- authentication
- login
- 2FA
- MFA
- TOTP
- magic link
- SSO
- Bitwarden
- 1Password
- Azure Key Vault
---
Most browser automations hit a login wall within the first few seconds. Skyvern handles authentication end-to-end, from simple passwords to multi-factor flows with TOTP codes, email verification, and magic links. Secrets live in your vault and never touch the LLM.
## What's supported
**Credential types:** passwords (with optional TOTP secret bundled in), credit cards for checkout automations, and arbitrary secrets or API keys.
**2FA methods:**
- **TOTP / authenticator apps** store the secret once and Skyvern generates valid codes on every run.
- **Email or SMS codes** can be pushed to Skyvern via API, or you can expose an endpoint that Skyvern polls every 10 seconds until the code arrives.
- **Magic links** work the same way: push the one-time login URL and Skyvern detects and follows it automatically.
- **Multi-field TOTP** handles split-box layouts (one digit per input) by filling all fields with the same code.
**Vault integrations:** Bitwarden (Cloud and self-hosted / Vaultwarden), 1Password (via service account token), Azure Key Vault, and a custom HTTP vault option if you want to bring your own service.
## How credentials stay safe
When a run needs a credential, Skyvern fetches it from your vault, injects it directly into the browser's form field, and discards it as soon as the field is filled. The value never enters an LLM prompt, never lands in a log line, and never gets written to any persistent Skyvern storage.
You'll see this in practice: run recordings, action timelines, and LLM prompts show stable placeholder tokens like `BW_PASSWORD`, `BW_USERNAME`, and `BW_TOTP` wherever real credentials were used. The prefix reflects the vault source (`BW_` for Bitwarden, `OP_` for 1Password, `AZ_` for Azure Key Vault, `SK_` for Skyvern's built-in vault) so you can audit which credential fired without the secret ever leaving your vault.
## Learn more
<CardGroup cols={2}>
<Card
title="Store credentials"
href="/developers/credentials/store-credentials"
>
Create passwords, cards, and secrets. Wire up Bitwarden, 1Password, Azure, or a custom vault.
</Card>
<Card
title="Handle 2FA"
href="/developers/credentials/handle-2fa"
>
TOTP setup, pushed codes, polled endpoints, and magic links.
</Card>
<Card
title="Troubleshoot logins"
href="/developers/credentials/troubleshooting-login"
>
Debug 2FA and login failures.
</Card>
<Card
title="SDK reference"
href="/sdk-reference/browser-automation/agent-login"
>
`agent.login()`, `send_totp_code()`, and the credentials API.
</Card>
</CardGroup>
@@ -0,0 +1,64 @@
---
title: Browser Sessions
subtitle: Keep a live browser open across multiple tasks and workflows
description: Skyvern browser sessions are live browser instances that persist cookies, local storage, and page state across runs. Use them for back-to-back tasks, human-in-the-loop flows, and real-time agents.
slug: developers/features/browser-sessions
icon: window-restore
keywords:
- browser sessions
- persistent state
- human-in-the-loop
- real-time agent
- cookies
- local storage
- browser profile
---
A Browser Session is a live browser instance that Skyvern keeps running between runs. Cookies, local storage, open tabs, and the current page all persist, so later operations pick up exactly where the previous one stopped.
## What you can build
**Back-to-back tasks:** log in with one operation, search and extract with the next, with no re-authentication in between.
**Human-in-the-loop flows:** pause for approval between steps without losing browser state. The VNC stream lets you watch or take control at any point.
**Real-time agents:** keep a browser open for hours while the agent responds to events as they happen.
**Task and workflow chaining:** run tasks and workflows through the same live browser instance, mixing code-driven and UI-defined automation in a single session.
## Configuration
Sessions support timeouts from 5 minutes to 24 hours (defaulting to 60 minutes), proxy locations across any of Skyvern's [21 supported countries](/developers/going-to-production/proxy-geolocation), Chrome or Edge browser types, and built-in extensions for ad-blocking and CAPTCHA solving. Every session exposes a live VNC stream.
## Sessions vs. Profiles
Sessions are live browsers that bill while open. [Browser Profiles](/developers/optimization/browser-profiles) are saved snapshots of browser state you reuse across days or weeks. You can create a profile from a finished session to save its authenticated state for later.
## Learn more
<CardGroup cols={2}>
<Card
title="Browser sessions guide"
href="/developers/optimization/browser-sessions"
>
Create sessions, run operations through them, and close cleanly.
</Card>
<Card
title="Browser profiles"
href="/developers/optimization/browser-profiles"
>
Save state to reuse across days or weeks.
</Card>
<Card
title="Connect your local browser"
href="/developers/self-hosted/browser"
>
Use your own Chrome with its existing logins and extensions.
</Card>
<Card
title="SDK reference"
href="/sdk-reference/browser-sessions/create-browser-session"
>
`create_browser_session`, `get_browser_session`, `close_browser_session`.
</Card>
</CardGroup>
@@ -0,0 +1,85 @@
---
title: CAPTCHA & Bot Bypass
subtitle: How Skyvern handles CAPTCHAs and avoids triggering anti-bot systems
description: Learn how Skyvern automatically detects and solves CAPTCHAs including reCAPTCHA, hCaptcha, and Cloudflare Turnstile, and how to reduce bot detection risk using residential proxies, browser sessions, and browser profiles.
slug: developers/features/captcha-and-bot-bypass
icon: shield-halved
keywords:
- CAPTCHA
- reCAPTCHA
- hCaptcha
- Cloudflare Turnstile
- bot detection
- fingerprinting
- residential proxy
- stealth
- anti-bot
---
Skyvern detects CAPTCHAs using its vision model and solves them automatically. This works for reCAPTCHA v2/v3, hCaptcha, Cloudflare Turnstile, FunCaptcha/ArkoseLabs, MTCaptcha, and standard text/number image CAPTCHAs.
That said, CAPTCHA solving is not guaranteed. Solvers can fail on novel challenges or rate-limited IPs. The rest of this page covers what Skyvern does automatically and what you can do to improve your success rate.
## Built-in bot detection avoidance
Every run gets these protections automatically, with no configuration needed:
- The `AutomationControlled` Blink feature flag is disabled so the browser isn't marked as automated.
- `navigator.webdriver` is hidden by suppressing the `enable-automation` flag, which defeats the most common JavaScript detection scripts.
- Viewport and user agent are set to match real consumer browsers.
- Locale and timezone auto-match the proxy location, so you never end up with a mismatched fingerprint (an English locale on a Japanese IP, for example).
## Reducing detection risk
Beyond fingerprinting, how you structure your automation affects whether you get flagged.
**Use residential proxies for sensitive sites.** Datacenter IPs are the single most common bot signal. Residential proxies route through real ISP addresses. Set `proxy_location="RESIDENTIAL"` or use `RESIDENTIAL_ISP` for a static IP that persists across the session. See [Proxy & Geolocation](/developers/going-to-production/proxy-geolocation).
**Reuse browser sessions for multi-step flows.** Creating a fresh browser for every step is suspicious. A persistent session maintains cookies, cache, and history between operations. See [Browser Sessions](/developers/optimization/browser-sessions).
**Use browser profiles for repeat visits.** Profiles save browser state from a previous session. The site sees a known browser with familiar cookies instead of a blank slate. See [Browser Profiles](/developers/optimization/browser-profiles).
**Add wait blocks between rapid actions.** Instant back-to-back actions can trigger behavioral detection. A short pause between steps looks more human.
## If you get blocked
Increase `max_steps` first, because some bot challenges (especially Cloudflare) loop through multiple verification pages and the solver needs more attempts. If that doesn't help, switch to a `RESIDENTIAL_ISP` proxy for a static IP that services trust more. Try loading a browser profile that previously passed the challenge on that domain. You can also load Chrome extensions for additional stealth by setting `EXTENSIONS` and `EXTENSIONS_BASE_PATH` in your environment.
## Manual fallback
If automatic solving fails and you need a human in the loop, you can manually solve any CAPTCHA without cancelling the run. In the Cloud UI, go to **Runs**, click your run, and click the **Take Control** button over the browser stream. Release control when you're done and the agent resumes where you left off.
<img src="/images/take-control.png" />
## Self-hosted deployments
Automatic CAPTCHA solving is not available for self-hosted deployments. When a CAPTCHA is detected, the agent pauses for 30 seconds to allow manual intervention. Solve it in the browser window yourself, then the agent continues automatically.
## Related
<CardGroup cols={2}>
<Card
title="Proxy & Geolocation"
href="/developers/going-to-production/proxy-geolocation"
>
Route traffic through residential proxies in 21 countries.
</Card>
<Card
title="Handle 2FA"
href="/developers/credentials/handle-2fa"
>
Configure TOTP, email, and SMS verification codes.
</Card>
<Card
title="Browser Sessions"
href="/developers/optimization/browser-sessions"
>
Persist browser state across multiple runs.
</Card>
<Card
title="Error Handling"
href="/developers/going-to-production/error-handling"
>
Map CAPTCHA and bot failures to custom error codes.
</Card>
</CardGroup>
+73
View File
@@ -0,0 +1,73 @@
---
title: Code Caching
subtitle: Convert successful runs into cached code for faster, deterministic replays
description: Skyvern records the actions an AI run takes and generates executable code from them. Subsequent runs execute the cached code directly, skipping LLM inference and screenshot analysis. Faster, cheaper, deterministic.
slug: developers/features/code-caching
icon: bolt
keywords:
- code caching
- code generation
- run_with
- Skyvern 2.0 with Code
- deterministic runs
- script generation
- cost optimization
- progressive caching
---
When Skyvern's agent completes a task or workflow, it records the actions it took and generates reusable code from them. Later runs can execute that cached code directly, skipping LLM inference and screenshot analysis entirely. This makes cached runs faster, cheaper, and deterministic. If the cached code fails because a page changed, Skyvern falls back to the agent automatically and regenerates the cache.
## How it works
The first run uses the agent as normal. Set `engine="skyvern-2.0"` when creating the task or workflow, and Skyvern records the actions as generated code while the agent executes.
On subsequent runs, pass `run_with="code"` to execute the cached code directly. No screenshots, no LLM reasoning, just the recorded action sequence replaying against the page.
If the cached code hits something unexpected (a layout change, a new field, a missing element), Skyvern re-runs with the full agent and regenerates the cache. You don't need to handle this yourself.
<Note>
The SDK default engine is `skyvern-1.0`. To use code caching, explicitly set `engine="skyvern-2.0"`. In the Cloud UI, `skyvern-2.0` is the default.
</Note>
## What gets cached
**Tasks** cache the full action sequence the agent took: clicks, form fills, extractions, and navigation.
**Workflows** cache per block. Each block that successfully executes gets its own cached script, so a partially-cached workflow still saves time on the blocks that have been seen before.
**Progressive caching** handles workflows with conditionals. Run 1 covers branch A, run 2 covers branch B, and so on. Previous caches are preserved, so coverage builds up over time.
**Not cached:** conditional evaluation blocks, wait blocks, and code blocks always run live because their behavior depends on runtime state.
<Tip>
Pair cached code with [scheduled workflows](/cloud/building-workflows/scheduling) for cheap, reliable recurring runs. The first scheduled run builds the cache, and every subsequent run executes from it.
</Tip>
## Learn more
<CardGroup cols={2}>
<Card
title="Cost control"
href="/developers/optimization/cost-control"
>
Use `run_with: code` plus `max_steps` and engine tiers to manage costs.
</Card>
<Card
title="Scheduling workflows"
href="/cloud/building-workflows/scheduling"
>
Run cached workflows on a cron schedule.
</Card>
<Card
title="Reliability tips"
href="/developers/going-to-production/reliability-tips"
>
Keep cached runs stable as target sites evolve.
</Card>
<Card
title="Run from code"
href="/cloud/building-workflows/run-from-code"
>
Trigger and monitor cached workflows from your own code.
</Card>
</CardGroup>
@@ -0,0 +1,62 @@
---
title: Proxy & GEO Targeting
subtitle: Route browser traffic through residential IPs in 21 countries
description: Skyvern routes browser traffic through residential proxies in 21 countries, with city- and state-level targeting in the US. Use it to access region-locked content, test geo-specific experiences, and reduce bot detection risk.
slug: developers/features/proxy-and-geo-targeting
icon: globe
keywords:
- proxy
- geolocation
- residential proxy
- RESIDENTIAL
- RESIDENTIAL_ISP
- GeoTarget
- geo-targeting
- country
- city
---
Skyvern routes browser traffic through residential proxies so every run looks like it's coming from a real consumer ISP in the country you choose. Locale and timezone auto-match the proxy region, so you never end up with a mismatched fingerprint that gives the automation away.
## Coverage
21 countries of residential coverage spanning the Americas (US, CA, MX, AR, BR), Europe (GB, IE, NL, DE, FR, ES, IT, TR), Asia (IN, PH, KR, JP, SA), Africa (ZA), and Oceania (AU, NZ).
For services that require a stable IP across a session, `RESIDENTIAL_ISP` provides a static ISP address instead of a rotating one. In the United States, you can target down to city and state level using `GeoTarget`, for example `{"country": "US", "subdivision": "CA", "city": "San Francisco"}`.
## How it's applied
**Per task:** pass `proxy_location` in the run request. **Per workflow:** set a default on the workflow and override on any individual run. **Per session:** lock a proxy to a [browser session](/developers/optimization/browser-sessions) so every operation in that session shares the same IP.
## When to use it
Region-locked pricing, inventory, or UX becomes visible when you route through the right country. Regulatory filings that require a local IP can be submitted from inside the target jurisdiction. Residential IPs also help with bot detection since they look like real consumer traffic rather than a datacenter. And `RESIDENTIAL_ISP` keeps the same IP for a full session, which matters for services that track IP changes mid-flow.
## Learn more
<CardGroup cols={2}>
<Card
title="Proxy & geolocation guide"
href="/developers/going-to-production/proxy-geolocation"
>
Full country list, `proxy_location` values, and `GeoTarget` examples.
</Card>
<Card
title="CAPTCHA & bot bypass"
href="/developers/features/captcha-and-bot-bypass"
>
Pair residential proxies with stealth for sensitive sites.
</Card>
<Card
title="Browser sessions"
href="/developers/optimization/browser-sessions"
>
Lock a proxy location across multiple operations in one session.
</Card>
<Card
title="Self-hosted proxy"
href="/developers/self-hosted/proxy"
>
Bring your own proxy on self-hosted deployments.
</Card>
</CardGroup>
@@ -0,0 +1,20 @@
---
title: AI Agents Quickstart
subtitle: Give your AI coding assistant full browser automation in one command
description: Give your AI coding assistant full browser control capabilities in one prommpt
slug: developers/getting-started/ai-agents-quickstart
keywords:
- MCP
- Claude Desktop
- Cursor
- Windsurf
- VS Code
- AI assistant
- Model Context Protocol
- pip install
- npm install
---
import AIAgentsQuickstartContent from "/snippets/ai-agents-quickstart-content.mdx";
<AIAgentsQuickstartContent />
@@ -0,0 +1,24 @@
---
title: Core Concepts
subtitle: The building blocks of Skyvern automations
description: Learn about tasks, workflows, browser sessions, credentials, and other building blocks that make up Skyvern automations.
slug: developers/getting-started/core-concepts
keywords:
- task
- workflow
- browser session
- browser profile
- credential
- block
- parameter
- schedule
- navigation block
- action block
- extract block
- loop block
- text prompt block
---
import CoreConceptsContent from "/snippets/core-concepts-content.mdx";
<CoreConceptsContent />
@@ -0,0 +1,20 @@
---
title: What is Skyvern?
subtitle: AI-powered browser automation for any website
description: Skyvern automates browser-based workflows using LLMs and computer vision. It navigates websites it has never seen before, filling forms, extracting data, and completing multi-step tasks via a simple API.
slug: developers/getting-started/introduction
keywords:
- browser automation
- AI agent
- computer vision
- LLM
- natural language
- visual reasoning
- web scraping
- form filling
- Playwright
---
import IntroductionContent from "/snippets/introduction-content.mdx";
<IntroductionContent />
+27
View File
@@ -0,0 +1,27 @@
---
title: MCP Server
subtitle: Connect AI assistants to browser automation via Model Context Protocol
description: Install and configure Skyvern's MCP server so Claude Desktop, Claude Code, Cursor, Windsurf, Codex, Hermes, OpenClaw, and other AI tools can run browser automations against Skyvern Cloud or a self-hosted instance over OAuth, API key, or local stdio.
slug: developers/getting-started/mcp
keywords:
- MCP
- Model Context Protocol
- OAuth
- Claude Desktop
- Claude Code
- Cursor
- Windsurf
- Codex
- Hermes
- OpenClaw
- MCPorter
- AI assistant
- tools
- stdio
- streamable-http
- self-hosted
---
import McpContent from "/snippets/mcp-content.mdx";
<McpContent />
@@ -0,0 +1,355 @@
---
title: Quickstart
subtitle: Run your first browser automation in 5 minutes
description: Launch a cloud browser, go to a webpage, and extract structured data with Python, TypeScript, or cURL in under 5 minutes.
slug: developers/getting-started/quickstart
keywords:
- quickstart
- launch_cloud_browser
- get_working_page
- page.extract
- page.agent.run_task
- cURL
- Python
- Typescript
- pip install
- npm install
- installation
---
Run your first browser automation in 5 minutes. By the end of this guide, you'll launch a cloud browser, navigate to Hacker News, and extract the top post title using Skyvern SDK's Page, Agent and Browser methods.
<Note>
Prefer a visual interface? Try the [Cloud UI](/cloud/getting-started/overview) instead. No code required.
</Note>
## Step 1: Get your API key
<img src="/images/get-api-key.png" alt="Get Skyvern API key" />
Sign up at [app.skyvern.com](https://app.skyvern.com) and go to [Settings](https://app.skyvern.com/settings) to copy your API key.
## Step 2: Install the SDK
<CodeGroup>
```bash Python
pip install skyvern
```
```bash TypeScript
npm install @skyvern/client
```
</CodeGroup>
<Info>
`pip install skyvern` is the lightweight Python SDK for Skyvern Cloud and remote API usage. If you are using embedded local mode with `Skyvern.local()` or `launch_local_browser()`, install the local extra: `pip install "skyvern[local]"`. For a local Skyvern server, self-hosted instance, or local stdio MCP, install the server extra instead: `pip install "skyvern[server]"`. For full local setup with migrations and the web UI, use Docker Compose or a source checkout.
</Info>
<Accordion title="Troubleshooting: Python version errors">
The Skyvern SDK requires Python 3.11, 3.12, or 3.13. If you encounter version errors, try using pipx:
```bash
pipx install skyvern
```
pipx installs Python packages in isolated environments while making them globally available.
</Accordion>
## Step 3: Launch a browser and extract data
When you call `launch_cloud_browser()`, Skyvern spins up a Chromium instance in the cloud. Your code drives that browser via a Playwright `Page` that also has AI methods (`act`, `extract`, `validate`, `prompt`) layered on top. You can watch the browser live at any time.
<CodeGroup>
```python Python
import os
import asyncio
from skyvern import Skyvern
async def main():
skyvern = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
# 1. Launch a cloud browser and get a page
browser = await skyvern.launch_cloud_browser()
page = await browser.get_working_page()
print(f"Watch live: https://app.skyvern.com/browser-session/{browser.browser_session_id}")
try:
# 2. Navigate
await page.goto("https://news.ycombinator.com")
# 3. Extract data with an AI prompt
result = await page.extract("Get the title of the #1 post")
print(f"Extracted: {result}")
finally:
# 4. Always close the browser to free cloud resources
await browser.close()
asyncio.run(main())
```
```typescript TypeScript
import { Skyvern } from "@skyvern/client";
async function main() {
const skyvern = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY });
// 1. Launch a cloud browser and get a page
const browser = await skyvern.launchCloudBrowser();
const page = await browser.getWorkingPage();
console.log(`Watch live: https://app.skyvern.com/browser-session/${browser.browserSessionId}`);
try {
// 2. Navigate
await page.goto("https://news.ycombinator.com");
// 3. Extract data with an AI prompt
const result = await page.extract("Get the title of the #1 post");
console.log("Extracted:", result);
} finally {
// 4. Always close the browser to free cloud resources
await browser.close();
}
}
main();
```
```bash cURL
# The SDK's browser/page pattern is a client-side abstraction over several
# REST calls. For a single curl example, use the task API, which handles
# browser + navigation + extraction as one request:
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Go to news.ycombinator.com and get the title of the #1 post",
"url": "https://news.ycombinator.com"
}'
```
</CodeGroup>
<Info>
**Why `page.extract` is enough here.** For a one-shot read on a single page, `page.extract(prompt, schema=...)` returns the extracted data directly (a `dict` in Python, `object` in TS). For multi-step goals like *"log in, navigate to billing, download the invoice"*, use `page.agent.run_task(prompt)` instead; it runs a full AI task loop on the page and returns a [`TaskRunResponse`](/sdk-reference/tasks/run-task#returns-taskrunresponse). See [Build a Browser Automation](/developers/browser-automations/overview) for the full walkthrough.
</Info>
## Step 4: Understand the output
`page.extract` returns the extracted data as a dict. For the Hacker News example you'll see something like:
```text
Watch live: https://app.skyvern.com/browser-session/pbs_519891155782767800
Extracted: {'top_post_title': 'Linux kernel framework for PCIe device emulation, in userspace'}
```
- **`Watch live: ...`** is printed before any AI calls. Open it in another tab to watch the browser navigate and extract in real time.
- **`Extracted: {...}`** appears after `page.extract` returns. The key names come from the AI (unless you pass a `schema`, in which case they match your schema). For typed, predictable output, see [Extract Structured Data](/developers/browser-automations/extract-structured-data).
### If you used the cURL path
The task API is asynchronous. The POST returns a `run_id`; poll for the final result:
```bash
RUN_ID="tsk_..." # from the POST response above
while true; do
RESPONSE=$(curl -s -X GET "https://api.skyvern.com/v1/runs/$RUN_ID" \
-H "x-api-key: $SKYVERN_API_KEY")
STATUS=$(echo "$RESPONSE" | jq -r '.status')
echo "Status: $STATUS"
if [[ "$STATUS" == "completed" || "$STATUS" == "failed" || "$STATUS" == "terminated" || "$STATUS" == "timed_out" || "$STATUS" == "canceled" ]]; then
echo "$RESPONSE" | jq '.output'
break
fi
sleep 5
done
```
**Run states:**
- `created`, `queued`: Waiting for an available browser
- `running`: AI is navigating and executing
- `completed`: Task finished successfully
- `failed` / `terminated` / `timed_out` / `canceled`: Non-success terminal states
## Step 5: Watch the recording
Every run is recorded. Two ways to access it:
### Live
While the script runs, the `Watch live: ...` URL printed in Step 3 streams the browser in real time.
### After the run
Open [Runs](https://app.skyvern.com/runs) and click on your run to see the Recording tab, step-by-step actions with screenshots, and AI reasoning for each decision.
<img src="/images/view-recording.png" alt="Recording tab in Skyvern Cloud" />
This is invaluable for debugging and understanding how Skyvern interprets your prompts.
---
## Run with a local server
You can run Skyvern with a browser on your own machine. This is useful for development, debugging, or automating internal tools on your local network.
**Prerequisites:**
- Skyvern server extra installed (`pip install "skyvern[server]"`)
- Source checkout or Docker Compose for guided quickstart and database migrations
- PostgreSQL database (local install or Docker)
- An LLM API key (OpenAI, Anthropic, Azure OpenAI, Gemini, Ollama, or any OpenAI-compatible provider)
<Note>
Docker is optional. If you have PostgreSQL installed locally, Skyvern will detect and use it automatically. Use `skyvern init --no-postgres` to skip database setup entirely if you're managing PostgreSQL separately. The PyPI wheel installs the local-server dependencies, but guided quickstart currently needs repository migration files from a source checkout.
</Note>
### Set up local Skyvern
```bash
# Run this from your app or repo root if you want Claude Code + /qa set up in-place
skyvern quickstart
# Or use setup-only mode if you do not want to start services yet
skyvern init
```
<p align="center">
<img src="/images/skyvern-init.gif" alt="Skyvern init interactive setup wizard" />
</p>
This interactive wizard will:
1. Set up your database (detects local PostgreSQL or uses Docker)
2. Configure your LLM provider
3. Choose browser mode (headless, headful, or connect to existing Chrome)
4. Generate local API credentials
5. Optionally configure local MCP for Claude Code, Claude Desktop, Cursor, or Windsurf
6. Download the Chromium browser
If you choose **Claude Code** during the MCP step and you run the wizard inside a project or repo, Skyvern will:
- write a project-local `.mcp.json`
- pin the MCP command to the active Python interpreter (`/path/to/python -m skyvern run mcp`)
- install bundled Claude Code skills into `.claude/skills/`, including `/qa`
- keep the whole path local, so Claude Code can test `localhost` directly without Skyvern Cloud or browser tunneling
This will generate a .env file that stores your local configuration, LLM api keys and your local `BASE_URL` and `SKYVERN_API_KEY`:
```.env
ENV='local'
ENABLE_OPENAI='true'
OPENAI_API_KEY='<API_KEY>'
...
LLM_KEY='OPENAI_GPT5_5'
SECONDARY_LLM_KEY=''
BROWSER_TYPE='chromium-headful'
MAX_SCRAPING_RETRIES='0'
VIDEO_PATH='./videos'
BROWSER_ACTION_TIMEOUT_MS='5000'
MAX_STEPS_PER_RUN='50'
LOG_LEVEL='INFO'
LITELLM_LOG='CRITICAL'
DATABASE_STRING='postgresql+psycopg://skyvern@localhost/skyvern'
PORT='8000'
...
SKYVERN_BASE_URL='http://localhost:8000'
SKYVERN_API_KEY='eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.....hSo3YA'
```
### Start the local server
If you used `skyvern quickstart` and chose to start services, Skyvern is already running. If you used `skyvern init`, start the server with:
```bash
skyvern run server
```
<p align="center">
<img src="/images/skyvern-run-server.gif" alt="Skyvern local server logs" />
</p>
### Run locally
The only difference from cloud is the `base_url` parameter pointing to your local server. The Page/Agent/Browser API is identical, so the same code works in both environments. Develop locally, deploy to cloud without changes.
```python
import os
import asyncio
from skyvern import Skyvern
async def main():
skyvern = Skyvern(
base_url="http://localhost:8000",
api_key=os.getenv("SKYVERN_API_KEY"),
)
browser = await skyvern.launch_local_browser()
page = await browser.get_working_page()
try:
await page.goto("https://news.ycombinator.com")
result = await page.extract("Get the title of the #1 post")
print(f"Extracted: {result}")
finally:
await browser.close()
asyncio.run(main())
```
A browser window will open on your machine (if you chose headful mode). Recordings and logs are saved in the directory where you started the server.
If you also selected Claude Code during setup, start your local frontend dev server and run `/qa http://localhost:3000` in Claude Code to validate the app against your local environment.
<video style={{ aspectRatio: '16 / 9', width: '100%' }} controls>
<source src="https://github.com/naman06dev/skyvern-docs/raw/8706c85d746e2a6870d81b6a95eaa511ad66dbf8/fern/images/skyvern-agent-local.mp4" type="video/mp4" />
</video>
---
## Next steps
<CardGroup cols={2}>
<Card
title="Build a Browser Automation"
icon="browser"
href="/developers/browser-automations/overview"
>
The full Page/Agent/Browser walkthrough: AI actions, Playwright selectors, and agent tasks
</Card>
<Card
title="Actions Reference"
icon="list"
href="/developers/browser-automations/actions-reference"
>
Every page action and agent method with parameters and return types
</Card>
<Card
title="Extract Structured Data"
icon="database"
href="/developers/browser-automations/extract-structured-data"
>
Define a schema to get typed JSON output from your automations
</Card>
<Card
title="Handle Logins"
icon="key"
href="/sdk-reference/credentials/create-credential"
>
Store credentials securely for sites that require authentication
</Card>
<Card
title="Build Workflows"
icon="diagram-project"
href="/cloud/building-workflows/build-a-workflow"
>
Chain multiple steps together for complex automations
</Card>
<Card
title="Use Webhooks"
icon="webhook"
href="/developers/going-to-production/webhooks"
>
Get notified when tasks complete instead of polling
</Card>
</CardGroup>
@@ -0,0 +1,705 @@
---
title: Error Handling
subtitle: Build systems that detect, classify, and recover from failures
description: Detect, classify, and recover from task and workflow failures using run status, failure_reason, custom error_code_mapping, and validation blocks. Build programmatic error handling with retry logic and branching.
slug: developers/going-to-production/error-handling
keywords:
- failure_reason
- run status
- error_code_mapping
- validation block
- retry logic
- branching
- failed
- terminated
- timed_out
---
Skyvern lets you make your workflows and tasks handle errors gracefully instead of failing silently.
Every run returns a `status`. When it's not `completed`, you need to know what went wrong and respond programmatically. The flow is:
1. **Check `status`** to detect failure states
2. **Read `failure_reason`** to get the raw error description
3. **Set up `error_code_mapping`** to map failures to your own error codes
4. **Respond in code** to branch your logic based on the error code
This page covers each step with exact field locations and full code examples.
---
## Step 1: Check `status`
Every run transitions through these states:
| Status | What it means |
|--------|---------------|
| `created` | Run initialized, not yet queued |
| `queued` | Waiting for an available browser |
| `running` | AI is navigating and executing |
| `completed` | Success. Check `output` for results |
| `failed` | System error (browser crash, network failure, exception) |
| `terminated` | AI determined the goal is unachievable (login blocked, page unavailable) |
| `timed_out` | Exceeded `max_steps` or time limit |
| `canceled` | Manually stopped |
**Terminal states:** `completed`, `failed`, `terminated`, `timed_out`, `canceled`
You can detect failures in two ways:
1. by polling `get_run`
2. by checking the webhook payload
Both contain the same `status` field.
<CodeGroup>
```json Polling Response
{
"run_id": "tsk_v2_486305187432193504",
"status": "failed", // <-- Check this field
"output": null,
"failure_reason": "Login failed: Invalid credentials",
...
}
```
```json Webhook Payload
{
"run_id": "tsk_v2_486306851394503256",
"status": "completed", // <-- Check this field
"output": {
"top_post_title": "Linux kernel framework for PCIe device emulation, in userspace"
},
"failure_reason": null,
"errors": [],
"webhook_callback_url": "https://your-server.com/webhook",
"created_at": "2026-01-20T11:58:57.414123",
"finished_at": "2026-01-20T12:00:31.512692",
...
}
```
</CodeGroup>
The `status` field is at the top level of both responses.
### For tasks
Poll `get_run` until the status is terminal:
<CodeGroup>
```python Python
run_id = result.run_id
while True:
run = await client.get_run(run_id)
if run.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
break
await asyncio.sleep(5)
if run.status == "completed":
process_output(run.output)
else:
handle_failure(run)
```
```typescript TypeScript
const runId = result.run_id;
while (true) {
const run = await client.getRun(runId);
if (["completed", "failed", "terminated", "timed_out", "canceled"].includes(run.status)) {
break;
}
await new Promise((resolve) => setTimeout(resolve, 5000));
}
if (run.status === "completed") {
processOutput(run.output);
} else {
handleFailure(run);
}
```
```bash cURL
# Poll until terminal state
while true; do
RESPONSE=$(curl -s -X GET "https://api.skyvern.com/v1/runs/$RUN_ID" \
-H "x-api-key: $SKYVERN_API_KEY")
STATUS=$(echo $RESPONSE | jq -r '.status')
if [[ "$STATUS" == "completed" ]] || [[ "$STATUS" == "failed" ]] || \
[[ "$STATUS" == "terminated" ]] || [[ "$STATUS" == "timed_out" ]] || \
[[ "$STATUS" == "canceled" ]]; then
echo $RESPONSE | jq
break
fi
sleep 5
done
```
</CodeGroup>
### For workflows
Same polling pattern works for workflow runs:
<CodeGroup>
```python Python
run_id = result.run_id
while True:
run = await client.get_run(run_id)
if run.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
break
await asyncio.sleep(5)
if run.status == "completed":
process_output(run.output)
else:
handle_failure(run)
```
```typescript TypeScript
const runId = result.run_id;
while (true) {
const run = await client.getRun(runId);
if (["completed", "failed", "terminated", "timed_out", "canceled"].includes(run.status)) {
break;
}
await new Promise((resolve) => setTimeout(resolve, 5000));
}
if (run.status === "completed") {
processOutput(run.output);
} else {
handleFailure(run);
}
```
```bash cURL
# Poll workflow run until terminal state
while true; do
RESPONSE=$(curl -s -X GET "https://api.skyvern.com/v1/runs/$WORKFLOW_RUN_ID" \
-H "x-api-key: $SKYVERN_API_KEY")
STATUS=$(echo $RESPONSE | jq -r '.status')
if [[ "$STATUS" == "completed" ]] || [[ "$STATUS" == "failed" ]] || \
[[ "$STATUS" == "terminated" ]] || [[ "$STATUS" == "timed_out" ]] || \
[[ "$STATUS" == "canceled" ]]; then
echo $RESPONSE | jq
break
fi
sleep 5
done
```
</CodeGroup>
**`failed` vs `terminated`:** A `failed` run hit infrastructure problems, so retry might work. A `terminated` run means the AI recognized the goal is unachievable with current conditions. Retrying without changes (new credentials, different URL) will produce the same result.
---
## Step 2: Read `failure_reason`
When a run fails or terminates, the `failure_reason` field contains a description of what went wrong. This is a free-text string, useful for logging but hard to branch on programmatically.
The field is available in both the polling response and webhook payload:
```json
{
"run_id": "tsk_v2_486305187432193504",
"status": "terminated",
"output": null,
"failure_reason": "Login failed: The page displayed 'Invalid username or password' after submitting credentials", // <-- Raw error text
...
}
```
### For tasks
<CodeGroup>
```python Python
run = await client.get_run(run_id)
if run.status in ["failed", "terminated"]:
print(f"Run failed: {run.failure_reason}")
# Fragile: parsing free text
if "login" in run.failure_reason.lower():
refresh_credentials()
```
```typescript TypeScript
const run = await client.getRun(runId);
if (["failed", "terminated"].includes(run.status)) {
console.log(`Run failed: ${run.failure_reason}`);
// Fragile: parsing free text
if (run.failure_reason?.toLowerCase().includes("login")) {
refreshCredentials();
}
}
```
```bash cURL
RESPONSE=$(curl -s -X GET "https://api.skyvern.com/v1/runs/$RUN_ID" \
-H "x-api-key: $SKYVERN_API_KEY")
STATUS=$(echo $RESPONSE | jq -r '.status')
FAILURE_REASON=$(echo $RESPONSE | jq -r '.failure_reason')
if [[ "$STATUS" == "failed" ]] || [[ "$STATUS" == "terminated" ]]; then
echo "Run failed: $FAILURE_REASON"
# Fragile: parsing free text
if echo "$FAILURE_REASON" | grep -qi "login"; then
# refresh_credentials
echo "Login error detected"
fi
fi
```
</CodeGroup>
### For workflows
<CodeGroup>
```python Python
run = await client.get_run(workflow_run_id)
if run.status in ["failed", "terminated"]:
print(f"Workflow failed: {run.failure_reason}")
# Fragile: parsing free text
if "login" in run.failure_reason.lower():
refresh_credentials()
```
```typescript TypeScript
const run = await client.getRun(workflowRunId);
if (["failed", "terminated"].includes(run.status)) {
console.log(`Workflow failed: ${run.failure_reason}`);
// Fragile: parsing free text
if (run.failure_reason?.toLowerCase().includes("login")) {
refreshCredentials();
}
}
```
```bash cURL
RESPONSE=$(curl -s -X GET "https://api.skyvern.com/v1/runs/$WORKFLOW_RUN_ID" \
-H "x-api-key: $SKYVERN_API_KEY")
STATUS=$(echo $RESPONSE | jq -r '.status')
FAILURE_REASON=$(echo $RESPONSE | jq -r '.failure_reason')
if [[ "$STATUS" == "failed" ]] || [[ "$STATUS" == "terminated" ]]; then
echo "Workflow failed: $FAILURE_REASON"
# Fragile: parsing free text
if echo "$FAILURE_REASON" | grep -qi "login"; then
# refresh_credentials
echo "Login error detected"
fi
fi
```
</CodeGroup>
---
## Step 3: Use `error_code_mapping`
`failure_reason` contains an AI-generated description of what went wrong. Define custom error codes to get consistent, actionable error messages.
When the run fails, Skyvern evaluates your natural language error descriptions against the page state and returns the matching code.
**How it works:** The `error_code_mapping` values are LLM-evaluated descriptions, so you don't need exact string matches. For example, `"The login credentials are incorrect"` will match pages showing "Invalid password", "Wrong username", "Authentication failed", etc.
### In tasks
Pass `error_code_mapping` as a parameter to `run_task`:
<CodeGroup>
```python Python
result = await client.run_task(
prompt="Log in and download the invoice for January 2024",
url="https://vendor-portal.example.com",
error_code_mapping={
"login_failed": "The login credentials are incorrect, account is locked, or MFA is required",
"invoice_not_found": "No invoice exists for the requested date range",
"maintenance": "The website is down for maintenance or unavailable",
"access_denied": "User does not have permission to view invoices"
}
)
```
```typescript TypeScript
const result = await client.runTask({
body: {
prompt: "Log in and download the invoice for January 2024",
url: "https://vendor-portal.example.com",
error_code_mapping: {
login_failed: "The login credentials are incorrect, account is locked, or MFA is required",
invoice_not_found: "No invoice exists for the requested date range",
maintenance: "The website is down for maintenance or unavailable",
access_denied: "User does not have permission to view invoices",
},
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Log in and download the invoice for January 2024",
"url": "https://vendor-portal.example.com",
"error_code_mapping": {
"login_failed": "The login credentials are incorrect, account is locked, or MFA is required",
"invoice_not_found": "No invoice exists for the requested date range",
"maintenance": "The website is down for maintenance or unavailable",
"access_denied": "User does not have permission to view invoices"
}
}'
```
</CodeGroup>
### In workflows
Add `error_code_mapping` to individual blocks (navigation, task, validation):
<Note>
The JSON examples below include comments (`//`) for clarity. Remove comments before using in actual workflow definitions; JSON does not support comments.
</Note>
<CodeGroup>
```json JSON
{
"blocks": [
{
"block_type": "navigation",
"label": "login_step",
"url": "https://vendor-portal.example.com/login",
"navigation_goal": "Log in using the stored credentials",
"error_code_mapping": {
"login_failed": "Login credentials are incorrect or account is locked",
"mfa_required": "Two-factor authentication is being requested",
"captcha_blocked": "CAPTCHA is displayed and cannot be bypassed"
}
},
{
"block_type": "navigation",
"label": "download_invoice",
"navigation_goal": "Download the invoice for {{invoice_date}}",
"error_code_mapping": {
"invoice_not_found": "No invoice found for the specified date",
"download_failed": "Invoice exists but download button is broken or missing"
}
}
]
}
```
```yaml YAML
- block_type: navigation
label: login_step
url: "https://vendor-portal.example.com/login"
navigation_goal: "Log in using the stored credentials"
error_code_mapping:
login_failed: "Login credentials are incorrect or account is locked"
mfa_required: "Two-factor authentication is being requested"
captcha_blocked: "CAPTCHA is displayed and cannot be bypassed"
- block_type: navigation
label: download_invoice
navigation_goal: "Download the invoice for {{invoice_date}}"
error_code_mapping:
invoice_not_found: "No invoice found for the specified date"
download_failed: "Invoice exists but download button is broken or missing"
```
</CodeGroup>
### Where the error code appears
When a mapped error occurs, your code appears in `output.error`. This field is available in both polling responses and webhook payloads:
<CodeGroup>
```json Polling Response
{
"run_id": "tsk_v2_486305187432193504",
"status": "terminated",
"output": {
"error": "login_failed" // <-- Your custom code
},
"failure_reason": "Login failed: The page displayed 'Invalid username or password'"
}
```
```json Webhook Payload
{
"run_id": "tsk_v2_486305187432193504",
"status": "terminated",
"output": {
"error": "login_failed" // <-- Your custom code
},
"failure_reason": "Login failed: The page displayed 'Invalid username or password'",
"webhook_callback_url": "https://your-server.com/webhook",
"created_at": "2026-01-20T11:58:57.414123",
"finished_at": "2026-01-20T12:00:31.512692"
}
```
</CodeGroup>
Both `output.error` (your code) and `failure_reason` (raw text) are present. Use `output.error` for branching, `failure_reason` for logging.
**Quick reference:** Where error codes appear
| Context | Field | Example |
|---------|-------|---------|
| Polling response | `run.output.error` | `run.output.get("error")` in Python |
| Webhook payload | `output.error` | Same structure as polling |
| Successful run | `output` contains your extracted data | No `error` key present |
---
## Step 4: Respond in code
Now you can write clean switch/match logic:
<CodeGroup>
```python Python
import asyncio
from skyvern import Skyvern
client = Skyvern(api_key="your-api-key")
async def run_with_error_handling(retries=1):
result = await client.run_task(
prompt="Log in and download the invoice",
url="https://vendor-portal.example.com",
error_code_mapping={
"login_failed": "Login credentials are incorrect or account is locked",
"invoice_not_found": "No invoice for the requested date",
"maintenance": "Site is down for maintenance"
}
)
run_id = result.run_id
# Poll until terminal state
while True:
run = await client.get_run(run_id)
if run.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
break
await asyncio.sleep(5)
# Handle based on status and error code
if run.status == "completed":
return {"success": True, "data": run.output}
error_code = run.output.get("error") if run.output else None
if error_code == "login_failed":
if retries > 0:
await refresh_credentials("vendor-portal")
return await run_with_error_handling(retries=retries - 1)
return {"success": False, "reason": "login_failed", "details": "Retry limit reached"}
elif error_code == "invoice_not_found":
# Expected condition: no invoice for this period
return {"success": False, "reason": "no_invoice", "date": invoice_date}
elif error_code == "maintenance":
# Schedule retry for later
await schedule_retry(run_id, delay_minutes=60)
return {"success": False, "reason": "scheduled_retry"}
else:
# Unknown error: log and alert
log_error(run_id, run.failure_reason)
return {"success": False, "reason": "unknown", "details": run.failure_reason}
```
```typescript TypeScript
async function runWithErrorHandling(retries = 1) {
const result = await client.runTask({
body: {
prompt: "Log in and download the invoice",
url: "https://vendor-portal.example.com",
error_code_mapping: {
login_failed: "Login credentials are incorrect or account is locked",
invoice_not_found: "No invoice for the requested date",
maintenance: "Site is down for maintenance",
},
},
});
const runId = result.run_id;
// Poll until terminal state
let run;
while (true) {
run = await client.getRun(runId);
if (["completed", "failed", "terminated", "timed_out", "canceled"].includes(run.status)) {
break;
}
await new Promise((r) => setTimeout(r, 5000));
}
// Handle based on status and error code
if (run.status === "completed") {
return { success: true, data: run.output };
}
const errorCode = run.output?.error;
switch (errorCode) {
case "login_failed":
if (retries > 0) {
await refreshCredentials("vendor-portal");
return runWithErrorHandling(retries - 1);
}
return { success: false, reason: "login_failed", details: "Retry limit reached" };
case "invoice_not_found":
return { success: false, reason: "no_invoice", date: invoiceDate };
case "maintenance":
await scheduleRetry(runId, { delayMinutes: 60 });
return { success: false, reason: "scheduled_retry" };
default:
logError(runId, run.failure_reason);
return { success: false, reason: "unknown", details: run.failure_reason };
}
}
```
</CodeGroup>
---
## Validation blocks as assertions
Validation blocks are assertions that check conditions at critical points, like unit test assertions. If validation fails, the workflow terminates immediately with your error code instead of continuing and failing later with a confusing error.
Use validation blocks after steps where you need to confirm success before proceeding:
<CodeGroup>
```json JSON
{
"blocks": [
{
// First, attempt to log in
"block_type": "navigation",
"label": "login",
"url": "https://vendor-portal.example.com/login",
"navigation_goal": "Log in using stored credentials"
},
{
// Then verify login succeeded before continuing
"block_type": "validation",
"label": "verify_login",
"complete_criterion": "Dashboard or account overview page is visible",
"terminate_criterion": "Login error message, CAPTCHA, or still on login page",
"error_code_mapping": {
"login_failed": "Login error message is displayed",
"captcha_required": "CAPTCHA verification is shown",
"session_expired": "Session timeout message appeared"
}
},
{
// Only runs if validation passed
"block_type": "navigation",
"label": "download_invoice",
"navigation_goal": "Navigate to invoices and download {{invoice_date}}",
"error_code_mapping": {
"invoice_not_found": "No invoice for the specified date"
}
}
]
}
```
```yaml YAML
blocks:
# First, attempt to log in
- block_type: navigation
label: login
url: "https://vendor-portal.example.com/login"
navigation_goal: "Log in using stored credentials"
# Then verify login succeeded before continuing
- block_type: validation
label: verify_login
complete_criterion: "Dashboard or account overview page is visible"
terminate_criterion: "Login error message, CAPTCHA, or still on login page"
error_code_mapping:
login_failed: "Login error message is displayed"
captcha_required: "CAPTCHA verification is shown"
session_expired: "Session timeout message appeared"
# Only runs if validation passed
- block_type: navigation
label: download_invoice
navigation_goal: "Navigate to invoices and download {{invoice_date}}"
error_code_mapping:
invoice_not_found: "No invoice for the specified date"
```
</CodeGroup>
| Parameter | Purpose |
|-----------|---------|
| `complete_criterion` | Condition that must be true to continue to the next block |
| `terminate_criterion` | Condition that stops the workflow immediately |
| `error_code_mapping` | Maps termination conditions to your error codes |
If `verify_login` sees a login error, the workflow terminates with `output.error = "login_failed"`. Your Step 4 code handles it the same way as any other error code.
---
## Common error patterns
| Error Code | Description | Typical Response |
|------------|-------------|------------------|
| `login_failed` | Credentials wrong, account locked, or MFA | Refresh credentials, retry |
| `captcha_required` | CAPTCHA blocking automation | Use `human_interaction` block or browser profile |
| `not_found` | Target data doesn't exist | Return empty result, don't retry |
| `maintenance` | Site temporarily down | Schedule retry with backoff |
| `rate_limited` | Too many requests | Add delays, use different proxy |
| `access_denied` | Permission issue | Check account permissions |
| `timeout` | Task took too long | Increase `max_steps`, simplify task |
---
## Next steps
<CardGroup cols={2}>
<Card
title="Reliability Tips"
icon="shield-check"
href="/developers/going-to-production/reliability-tips"
>
Write prompts that fail less often
</Card>
<Card
title="Webhooks"
icon="webhook"
href="/developers/going-to-production/webhooks"
>
Get notified when runs complete or fail
</Card>
</CardGroup>
File diff suppressed because one or more lines are too long
@@ -0,0 +1,406 @@
---
title: Reliability Tips
subtitle: Write robust prompts and handle edge cases
description: Write robust prompts with clear completion criteria, choose the right block type for each step, handle dynamic pages and popups, and add validation blocks to catch errors before they cascade.
slug: developers/going-to-production/reliability-tips
keywords:
- prompt engineering
- completion criteria
- block selection
- dynamic pages
- popups
- validation block
- edge cases
- robust prompts
---
The difference between a demo and production-ready automation is reliability. This page covers techniques for writing prompts that work consistently, handling dynamic pages, and validating results.
---
## Writing robust prompts
### Anatomy of a good prompt
Every prompt needs four components:
1. **Main goal** (required): What should happen
2. **Guardrails**: Constraints and boundaries
3. **Payload**: Data to use in form fields
4. **Completion criteria** (required): How to know when done
```
Your goal is to fill out the contact form with the provided information.
Only fill out required fields. Skip optional fields unless you have data for them.
Here is the information:
{{contact_data}}
COMPLETE when the form is submitted and you see a confirmation message.
TERMINATE if you see an error message or the form cannot be submitted.
```
### What works
**Be explicit about completion.** The AI needs to know when to stop. "COMPLETE when you see 'Order confirmed'" is unambiguous. Without this, the AI might keep navigating or stop too early.
<Tip>
**Don't forget the submit button.** A common failure mode is the AI completing after filling form fields but before clicking Submit. Be explicit: "COMPLETE when you have clicked the Submit button AND see a confirmation message." The AI might consider the form "done" once all fields are filled, so make clear that submission is part of the goal.
</Tip>
**Use visual descriptions.** "Click the blue Submit button at the bottom of the form" works better than "click Submit" because there might be multiple buttons, and visual context helps the AI pick the right one. Describe position, color, icons, and surrounding text.
**Start general, then refine.** Begin with simple prompts and add specifics based on failures. Over-specified prompts are brittle; the AI handles variation better when you describe goals rather than exact steps.
**Include termination criteria.** Tell the AI when to give up: "TERMINATE if login fails or account is locked." Without this, the AI might keep trying forever or fail silently.
**Reference visual indicators.** "The invoice download link has a PDF icon next to it" helps the AI identify the right element when there are multiple links with similar text.
### What doesn't work
**Vague goals.** "Do the thing on the website" gives the AI nothing to work with. Be specific about what outcome you want.
**Missing completion criteria.** Without knowing when to stop, the AI keeps navigating indefinitely or terminates at arbitrary points.
**Action lists without context.** "Click button A, then B, then C" breaks when the layout changes or buttons move. Describe the goal instead, and let the AI figure out the steps.
**HTML element names.** "Click the `<button id='submit'>` element" assumes IDs are stable and visible to the AI. They often change between deployments, and the AI works from visual screenshots, not DOM structure.
**Assuming page state.** The AI doesn't know what page you expect to be on. Always describe what you expect to see, not just what to do.
### Autocomplete and dropdown fields
Address fields, city selectors, and other autocomplete inputs are notoriously tricky. The AI might type a value, see suggestions appear, then second-guess itself, erasing and retyping, cycling through options like "Toronto" → "Ontario" → "Canada" → "Toronto" again before settling.
To reduce cycling behavior:
**Be explicit about the exact value.** Instead of "enter the city," say "type 'Toronto' and select it from the dropdown."
**Tell it to stop after selection.** Add "Once you've selected the value, move to the next field, and don't modify it further."
**Specify which suggestion to pick.** "Select the first suggestion that matches" or "Choose the option that shows the full address" reduces ambiguity.
```
Fill in the shipping address:
- For the City field, type "Toronto" and select the first matching suggestion
- Do NOT cycle through suggestions or second-guess your selection
- Once a field is filled, move to the next field immediately
{{address_data}}
```
<Warning>
Multi-select fields (where you pick several options from a list) are slower and less reliable than single-select. If the form allows it, consider making multiple API calls with single values rather than one call selecting many options.
</Warning>
---
## Choosing the right block type
Skyvern offers three block types with different tradeoffs between reliability and flexibility. The more interpretation you ask the AI to do, the more room for unexpected behavior.
**Action blocks** are the most deterministic. You tell Skyvern exactly what to do: "Click the Submit button." There's no interpretation; it either finds the element and clicks it, or fails. Use these when you know exactly what action is needed and the page structure is predictable.
**Navigation blocks** give Skyvern a goal: "Fill out the registration form." The AI figures out which fields to fill and in what order. This handles variation in form layouts (fields might be in different positions, have different labels, or be split across tabs), but the AI can misinterpret ambiguous forms or fill fields you didn't intend.
**Task blocks (Navigation V2)** handle multi-step goals: "Log in, navigate to settings, update profile." Maximum flexibility for complex workflows, but more room for the AI to take unexpected paths. A task block might navigate through menus you didn't anticipate or skip steps it deems unnecessary.
<Warning>
**Task blocks keep navigating until they believe the goal is complete.** If you want to click "Next" once and then stop, a Task block will likely click through ALL pages until it reaches the end. For single-action-then-stop behavior, use an Action block or Navigation block with explicit completion criteria like "COMPLETE after clicking Next once."
</Warning>
**Rule of thumb:** Start with the most deterministic block that can accomplish your goal. If a single click solves the problem, don't use a Task block, because you're adding unnecessary interpretation where errors can creep in. Reserve Task blocks for genuinely multi-step workflows where you can't predict the exact sequence of actions.
---
## Handling dynamic pages
### Lazy-loaded content
For pages that load content as you scroll:
```python
result = await client.run_task(
prompt="Extract all product listings from the page",
url="https://example.com/products",
max_screenshot_scrolls=5 # Scroll to load more content
)
```
### Popups and modals
Include handling instructions in your prompt:
```
Your goal is to add the item to cart.
If a popup appears asking about newsletter signup, close it by clicking the X.
If a cookie consent banner appears, click Accept.
COMPLETE when the item is in the cart and the cart count increases.
```
### Multi-step forms
For forms spread across multiple pages:
```
Your goal is to complete the checkout process.
Page 1: Fill in shipping address using {{shipping_data}}
Page 2: Select standard shipping
Page 3: Enter payment details using {{payment_data}}
Page 4: Review and submit
COMPLETE when you see the order confirmation number.
TERMINATE if any validation error cannot be resolved.
```
---
## Validation strategies
Workflows can silently produce wrong results. The AI might fill a form with incorrect data, navigate to the wrong page, or extract stale information. Validation blocks let you assert conditions at critical points and fail fast when something goes wrong, rather than discovering the problem downstream.
### Add validation blocks at critical points
**After login:** Verify you're actually authenticated before proceeding. A failed login might redirect to an error page or show a CAPTCHA, and subsequent blocks will fail in confusing ways if you don't catch this early.
```yaml
- block_type: validation
label: verify_login_success
complete_criterion: Dashboard or account page is visible
terminate_criterion: Login error, CAPTCHA, or still on login page
```
**Before form submission:** Catch data entry errors before they become permanent. The AI might have misinterpreted a field or filled in default values instead of your parameters.
```yaml
- block_type: validation
label: verify_form_data
complete_criterion: |
Review page shows correct values:
- Name matches {{name}}
- Email matches {{email}}
terminate_criterion: Data mismatch or missing required fields
```
### Use extraction to verify
For validation that requires exact matching (email addresses, confirmation numbers, prices), extract the values and compare programmatically in your code rather than relying on the AI's judgment:
```python
result = await client.run_task(
prompt="Fill out the form and extract the confirmation number",
data_extraction_schema={
"type": "object",
"properties": {
"confirmation_number": {"type": "string"},
"submitted_email": {"type": "string"}
}
}
)
# Verify in your code
if result.output["submitted_email"] != expected_email:
raise ValueError("Email mismatch")
```
<Warning>
**Validation blocks read from the current page, not from prior block outputs.** If you need to validate extracted data from a previous block, use a Code block to compare values programmatically. Validation blocks evaluate their criteria against what's visible on screen; they don't have access to data extracted by earlier extraction blocks.
</Warning>
---
## Loop reliability
Loops are especially prone to cascading failures: when one iteration fails, it can leave the browser in an unexpected state that breaks subsequent iterations. For example, if iteration 3 navigates to an error page and fails, iteration 4 starts from that error page instead of the expected list view, causing it to fail too. One bad item can take down your entire loop.
Use a For Loop when you have a known list of items before the loop begins. Use a While Loop when the workflow should keep running until page state changes, such as paginating while a Next button is enabled or polling until a status changes. While loops need an especially clear exit condition because the number of iterations is discovered at run time.
### Always set `continue_on_failure`
```yaml
- block_type: for_loop
label: process_items
loop_over_parameter_key: items_list
continue_on_failure: true # Don't stop the whole loop if one item fails
loop_blocks:
- block_type: navigation
label: process_item
navigation_goal: "Process: {{ process_item.current_value }}"
```
### Add a reset block
Each iteration should start from a known state. If iteration 3 fails on a detail page, iteration 4 needs to navigate back to the list before it can find its item. Add a reset block at the start of each loop iteration:
```yaml
loop_blocks:
- block_type: navigation
label: reset_to_list
url: "https://example.com/items"
navigation_goal: "Navigate back to the items list"
- block_type: navigation
label: process_item
navigation_goal: "Find and process: {{ process_item.current_value }}"
```
For While Loop pagination, each pass should leave the page ready for the next condition check. Extract the state that controls the loop, then advance the page:
```yaml
- block_type: while_loop
label: paginate_results
condition:
criteria_type: jinja2_template
expression: "{{ current_index == 0 or extract_page.has_next_page }}"
loop_blocks:
- block_type: extraction
label: extract_page
data_extraction_goal: Extract rows on this page and whether the Next button is enabled
data_schema:
type: object
properties:
rows:
type: array
items:
type: object
has_next_page:
type: boolean
- block_type: action
label: click_next
navigation_goal: "Click Next if it is enabled. COMPLETE after one click or if Next is disabled."
```
The first condition check uses `current_index == 0` to enter the loop before `extract_page` exists. Later checks use the previous extraction output so the loop exits naturally when no next page is available.
### Include termination criteria per iteration
```yaml
- block_type: navigation
label: process_item
navigation_goal: |
Process the item: {{ process_item.current_value }}
COMPLETE when the item is processed.
TERMINATE if you're not on the expected page or the item doesn't exist.
```
---
## Session timeouts and human-in-the-loop
Browser sessions have a default timeout. If you're using human-in-the-loop workflows where a person must approve an action before proceeding, the session can expire while waiting for approval, especially if the approver is slow or in a different timezone.
**Symptoms:** Runs that worked during testing fail in production with session expiry errors. The workflow waits for human approval, but by the time approval comes, the browser session has timed out.
**Solutions:**
1. **Increase session timeout**: Set a longer `timeout` when creating browser sessions for workflows that include human approval steps
2. **Remove the human step for time-sensitive flows**: If session expiry is causing failures, consider making the workflow fully automated and reviewing results after completion
3. **Split into multiple workflows**: Run the pre-approval steps, wait for human approval outside Skyvern, then trigger a second workflow for post-approval steps using a browser profile to maintain login state
```python
# Longer timeout for human-in-the-loop workflows
session = await client.create_browser_session(
timeout=300, # 5 minutes instead of default
proxy_location="RESIDENTIAL"
)
```
<Note>
For workflows with predictable human approval times, schedule runs to arrive in the approver's inbox during working hours when they can act quickly.
</Note>
---
## Keyboard actions and workarounds
<Note>
Direct keyboard shortcuts (Ctrl+C, Alt+Tab, Esc, etc.) are not currently supported. Here are workarounds for common scenarios.
</Note>
| Scenario | Workaround |
|----------|------------|
| **Copy text** | Use extraction block to get the text value |
| **Paste into field** | Pass the value as a parameter: `{{value_to_paste}}` |
| **Press Escape to close modal** | Click the X button or "Close" link instead. Add to prompt: "If a modal appears, close it by clicking the X button in the top right corner" |
| **Keyboard navigation (Tab, arrows)** | Describe the click target visually instead |
| **Ctrl+S to save** | Click the Save button in the UI, or look for auto-save indicators |
| **Hotkey-only features** | Look for menu alternatives, toolbar buttons, or right-click context menus |
| **Tab between fields** | AI handles field navigation automatically, so no workaround is needed |
| **Enter to submit** | Explicitly click the Submit button rather than relying on Enter key |
For applications that genuinely require keyboard shortcuts with no UI alternative:
1. **Use the Code block** with custom Playwright scripts. You can call `page.keyboard.press('Escape')` directly
2. **Check for an API**: Many web apps have APIs that bypass the UI entirely
3. **Use browser profiles** with pre-configured settings or extensions that add UI buttons for keyboard-only features
```python
# Example: Using Code block for keyboard actions
- block_type: code
label: press_escape
code: |
page = context["skyvern_page"].page
await page.keyboard.press("Escape")
result = {"escaped": True}
```
---
## Troubleshooting workflow
When a run fails:
1. **Check the recording**: Watch what actually happened
2. **Review screenshots**: See the state at each step
3. **Check LLM reasoning**: Understand why the AI made each decision
4. **Compare parameters**: Verify inputs match expectations
### Common fixes
| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| **Completed too early** | Ambiguous completion criteria | Add specific visual indicators. Include "click Submit AND see confirmation" |
| **Completed without submitting** | Submit button not included in goal | Explicitly state that clicking Submit is part of the task |
| **Didn't complete** | Missing completion criteria | Add explicit COMPLETE condition |
| **Wrong element clicked** | Multiple similar elements | Add distinguishing details: position, color, surrounding text |
| **Form field skipped** | Field not visible or labeled differently | Describe the field's visual position |
| **Loop stuck** | No reset between iterations | Add reset block at loop start |
| **Autocomplete cycling** | AI second-guessing dropdown selections | Add "select and move on; don't modify" to prompt |
| **Task navigates too far** | Task block continues until goal complete | Use Action/Navigation block for single-step actions |
| **Session expired** | Human-in-the-loop timeout | Increase timeout or split into multiple workflows |
| **Max steps reached** | Complex page or AI retrying actions | Increase `max_steps_per_run` or simplify the goal |
### When to adjust prompts vs file a bug
**Adjust your prompt if:**
- The AI misunderstood what to do
- Completion criteria were ambiguous
- Visual descriptions were unclear
**File a bug if:**
- Elements are visibly present but not detected
- Actions execute on wrong elements consistently
- Standard UI patterns (dropdowns, checkboxes) don't work
---
## Next steps
<CardGroup cols={2}>
<Card
title="Error Handling"
icon="triangle-exclamation"
href="/developers/going-to-production/error-handling"
>
Map errors to custom codes for programmatic handling
</Card>
<Card
title="Workflow Blocks Reference"
icon="cube"
href="/cloud/building-workflows/configure-blocks"
>
Detailed documentation for validation and other blocks
</Card>
</CardGroup>
@@ -0,0 +1,540 @@
---
title: Webhooks
subtitle: Get notified when tasks and workflows complete
description: Configure webhook URLs for tasks and workflows to receive notifications when runs reach terminal status. Includes payload structure, HMAC-SHA256 signature verification, failure handling, and retry mechanisms.
slug: developers/going-to-production/webhooks
keywords:
- webhook_url
- HMAC-SHA256
- signature verification
- payload
- callback
- notification
- retry
- failure handling
---
Workflows and task runs are asynchronous. When you call `run_task` or `run_workflow`, the API returns immediately with a run ID, but the actual execution happens in the background and can take variable time.
Instead of polling the `get_runs` endpoint, you can use Webhooks to get notified when they finish. Webhooks fire only when a run reaches a terminal status: `completed`, `failed`, `terminated`, `timed_out`, or `canceled`.
This page covers setting them up, explains payload structure, signature verification, and handling delivery failures.
---
## Step 1: Set webhook URL
### For tasks
<CodeGroup>
```python Python
result = await client.run_task(
prompt="Get the price of this product",
url="https://example.com/product/123",
webhook_url="https://your-server.com/webhook",
)
```
```typescript TypeScript
const result = await client.runTask({
body: {
prompt: "Get the price of this product",
url: "https://example.com/product/123",
webhook_url: "https://your-server.com/webhook",
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Get the price of this product",
"url": "https://example.com/product/123",
"webhook_url": "https://your-server.com/webhook"
}'
```
</CodeGroup>
### For workflows
Set a default webhook when creating the workflow, or override it per-run:
<CodeGroup>
```python Python
# Set default on workflow (webhook_callback_url goes inside json_definition)
workflow = await client.create_workflow(
json_definition={
"title": "Invoice Downloader",
"webhook_callback_url": "https://your-server.com/webhook",
"workflow_definition": {
"parameters": [],
"blocks": [
{
"block_type": "task",
"label": "download_invoice",
"url": "https://vendor-portal.example.com",
"prompt": "Download the latest invoice"
}
]
}
}
)
# Override for a specific run
run = await client.run_workflow(
workflow_id=workflow.workflow_permanent_id,
parameters={},
webhook_url="https://your-server.com/different-webhook"
)
```
```typescript TypeScript
// Set default on workflow (webhook_callback_url goes inside json_definition)
const workflow = await client.createWorkflow({
body: {
json_definition: {
title: "Invoice Downloader",
webhook_callback_url: "https://your-server.com/webhook",
workflow_definition: {
parameters: [],
blocks: [
{
block_type: "task",
label: "download_invoice",
url: "https://vendor-portal.example.com",
prompt: "Download the latest invoice",
},
],
},
},
},
});
// Override for a specific run
const run = await client.runWorkflow({
body: {
workflow_id: workflow.workflow_permanent_id,
parameters: {},
webhook_url: "https://your-server.com/different-webhook",
},
});
```
```bash cURL
# Set default on workflow (webhook_callback_url goes inside json_definition)
curl -X POST "https://api.skyvern.com/v1/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"json_definition": {
"title": "Invoice Downloader",
"webhook_callback_url": "https://your-server.com/webhook",
"workflow_definition": {
"parameters": [],
"blocks": [
{
"block_type": "task",
"label": "download_invoice",
"url": "https://vendor-portal.example.com",
"prompt": "Download the latest invoice"
}
]
}
}
}'
# Override for a specific run (use workflow_permanent_id from create response)
curl -X POST "https://api.skyvern.com/v1/run/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "wpid_123456789",
"parameters": {},
"webhook_url": "https://your-server.com/different-webhook"
}'
```
</CodeGroup>
<Info>
When creating a workflow, use `webhook_callback_url` inside `json_definition`; this sets the default for all runs. When running a workflow, use `webhook_url` at the top level to override for that specific run.
</Info>
**Quick reference:**
| Context | Parameter | Location |
|---------|-----------|----------|
| Task run | `webhook_url` | Top-level parameter |
| Workflow creation | `webhook_callback_url` | Inside `json_definition` |
| Workflow run (override) | `webhook_url` | Top-level parameter |
<Warning>
**Watch the parameter names.** Using `webhook_url` when creating a workflow (instead of `webhook_callback_url` inside `json_definition`) silently results in no webhook being sent. The API won't return an error. Your runs will just complete without notifications.
</Warning>
---
## Step 2: Understand the payload
Skyvern sends a JSON payload with run results. Here's a real example from a completed task:
**Webhook Payload:**
```json
{
"run_id": "tsk_v2_490440779503357994",
"task_id": "tsk_v2_490440779503357994",
"status": "completed",
"output": {
"top_post_title": "Antirender: remove the glossy shine on architectural renderings"
},
"summary": "I have successfully retrieved the title of the top post from the Hacker News homepage.",
"prompt": "Get the title of the top post on Hacker News",
"url": "https://news.ycombinator.com/",
"downloaded_files": [],
"recording_url": "https://skyvern-artifacts.s3.amazonaws.com/v1/production/o_485917350850524254/tsk_490440844256003946/.../recording.webm?AWSAccessKeyId=...&Signature=...&Expires=...",
"screenshot_urls": ["https://skyvern-artifacts.s3.amazonaws.com/v1/production/o_485917350850524254/tsk_490441394011816060/.../screenshot_final.png?AWSAccessKeyId=..."],
"failure_reason": null,
"errors": [],
"step_count": 4,
"run_type": "task_v2",
"app_url": "https://app.skyvern.com/runs/wr_490440779503358000",
"organization_id": "o_485917350850524254",
"workflow_run_id": "wr_490440779503358000",
"workflow_id": "w_490440779503357996",
"workflow_permanent_id": "wpid_490440779503357998",
"proxy_location": "RESIDENTIAL",
"webhook_callback_url": "https://webhook.site/d8d013c1-0481-48d0-8d13-281e8563a508",
"webhook_failure_reason": null,
"created_at": "2026-01-31T15:20:42.160725",
"modified_at": "2026-01-31T15:23:34.993138",
"queued_at": "2026-01-31T15:20:42.371545",
"started_at": "2026-01-31T15:20:44.391756",
"finished_at": "2026-01-31T15:23:34.992815"
}
```
**Request Headers Sent:**
```http
POST /d8d013c1-0481-48d0-8d13-281e8563a508 HTTP/1.1
Host: webhook.site
Content-Type: application/json
x-skyvern-signature: 024025ccf0bbfe1c8978bdaae43fc136fc8b614b92e2f63c3485be5a36866f68
x-skyvern-timestamp: 1769873016
Content-Length: 8208
User-Agent: python-httpx/0.28.1
{...json payload above...}
```
| Field | Type | Description |
|-------|------|-------------|
| `run_id` | string | Unique identifier for this run |
| `task_id` | string | Same as `run_id` |
| `status` | string | `completed`, `failed`, `terminated`, `timed_out`, or `canceled` |
| `output` | object \| null | Extracted data from the task. If you configured [`error_code_mapping`](/developers/going-to-production/error-handling#step-3-use-error_code_mapping), failed runs include `output.error` with your custom error code. |
| `summary` | string | AI-generated description of what was done |
| `prompt` | string | The prompt from the original request |
| `url` | string | The URL from the original request |
| `downloaded_files` | array | Files downloaded during execution |
| `recording_url` | string \| null | Video recording of the browser session |
| `screenshot_urls` | array \| null | Screenshots captured (latest first) |
| `failure_reason` | string \| null | Error message if the run failed |
| `errors` | array | List of errors encountered |
| `step_count` | integer \| null | Number of steps executed |
| `run_type` | string | Type of run: `task_v2`, `openai_cua`, `anthropic_cua` |
| `app_url` | string | Link to view this run in Skyvern Cloud |
| `organization_id` | string | Your organization ID |
| `workflow_run_id` | string | Associated workflow run ID |
| `workflow_id` | string | Internal workflow ID |
| `workflow_permanent_id` | string | Permanent workflow ID used to run the workflow |
| `proxy_location` | string | Proxy location used (e.g., `RESIDENTIAL`) |
| `webhook_callback_url` | string | The webhook URL that received this payload |
| `webhook_failure_reason` | string \| null | Error message if a previous webhook delivery failed (always `null` in the payload you receive) |
| `created_at` | datetime | When the run was created |
| `modified_at` | datetime | When the run was last updated |
| `queued_at` | datetime \| null | When the run entered the queue |
| `started_at` | datetime \| null | When execution began |
| `finished_at` | datetime \| null | When execution completed |
---
## Optional: Verify webhook signatures
Skyvern signs every webhook with your API key using HMAC-SHA256, so you can verify the request actually came from Skyvern before acting on it.
**Headers sent with every webhook:**
- `x-skyvern-signature`: HMAC-SHA256 signature of the payload
- `x-skyvern-timestamp`: Unix timestamp when the webhook was sent
- `Content-Type: application/json`
<CodeGroup>
```python Python
import hmac
import hashlib
from fastapi import Request, HTTPException
async def handle_webhook(request: Request):
signature = request.headers.get("x-skyvern-signature")
payload = await request.body()
expected = hmac.new(
SKYVERN_API_KEY.encode("utf-8"),
msg=payload,
digestmod=hashlib.sha256
).hexdigest()
if not hmac.compare_digest(signature, expected):
raise HTTPException(status_code=401, detail="Invalid signature")
data = await request.json()
# Process the webhook...
```
```typescript TypeScript
import crypto from "crypto";
import express from "express";
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
const signature = req.headers["x-skyvern-signature"];
const payload = req.body;
const expected = crypto
.createHmac("sha256", process.env.SKYVERN_API_KEY)
.update(payload)
.digest("hex");
// Use timing-safe comparison to prevent timing attacks
let valid = false;
try {
crypto.timingSafeEqual(
Buffer.from(signature || ''),
Buffer.from(expected)
);
valid = true;
} catch (err) {
valid = false;
}
if (!valid) {
return res.status(401).send("Invalid signature");
}
const data = JSON.parse(payload);
// Process the webhook...
res.status(200).send("OK");
});
```
```go Go
package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"io"
"net/http"
"os"
)
func webhookHandler(w http.ResponseWriter, r *http.Request) {
signature := r.Header.Get("x-skyvern-signature")
payload, err := io.ReadAll(r.Body)
if err != nil {
http.Error(w, "Failed to read request body", http.StatusBadRequest)
return
}
mac := hmac.New(sha256.New, []byte(os.Getenv("SKYVERN_API_KEY")))
mac.Write(payload)
expected := hex.EncodeToString(mac.Sum(nil))
if !hmac.Equal([]byte(signature), []byte(expected)) {
http.Error(w, "Invalid signature", http.StatusUnauthorized)
return
}
// Process the webhook...
w.WriteHeader(http.StatusOK)
}
```
</CodeGroup>
<Note>
**Use constant-time comparison** to prevent timing attacks:
- Python: `hmac.compare_digest()`
- TypeScript: `crypto.timingSafeEqual()`
- Go: `hmac.Equal()`
Never use simple equality operators (`==` or `===`) for signature comparison as they are vulnerable to timing attacks.
</Note>
<Warning>
**Always validate against the raw request body bytes.** Skyvern normalizes JSON before signing: it removes whitespace (using compact separators) and converts whole-number floats to integers (`3.0` becomes `3`). If you parse the JSON and re-serialize it, the byte representation will differ and signature validation will fail.
</Warning>
---
## Handling webhook failures
Task execution and webhook delivery are independent; a task can succeed while webhook delivery fails. When this happens, the run shows `status: "failed"` even though your data was extracted successfully.
```mermaid
graph TD
A["Run Finishes"] --> B{"Check status"}
B -->|"completed"| C["Task succeeded<br>Webhook delivered"]
B -->|"failed"| D{"Does failure_reason<br>mention 'webhook'?"}
B -->|"terminated"| E["Goal unachievable"]
D -->|"Yes"| F["Webhook delivery failed"]
D -->|"No"| G["Task execution failed"]
F --> H["Check output field<br>Data may still exist!"]
G --> I["Check failure_reason"]
C --> J["Process output"]
style A fill:#f8fafc,stroke:#6366F1,stroke-width:2px,color:#1e293b
style B fill:#f8fafc,stroke:#6366F1,stroke-width:2px,color:#1e293b
style C fill:#6366F1,stroke:#4F46E5,stroke-width:2px,color:#fff
style D fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#1e293b
style E fill:#f1f5f9,stroke:#64748b,stroke-width:2px,color:#475569
style F fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#92400e
style G fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#991b1b
style H fill:#6366F1,stroke:#4F46E5,stroke-width:2px,color:#fff
style I fill:#f1f5f9,stroke:#64748b,stroke-width:2px,color:#475569
style J fill:#6366F1,stroke:#4F46E5,stroke-width:2px,color:#fff
```
Webhook delivery can fail due to network issues, server errors, or misconfigured URLs.
When this happens, the run is marked as `failed` and the error is recorded in the `failure_reason` field. Check it by calling `get_run` after the run terminates:
<CodeGroup>
```python Python
run = await client.get_run(run_id)
if run.status == "failed" and "webhook" in (run.failure_reason or "").lower():
print(f"Webhook failed: {run.failure_reason}")
# The task may have completed successfully before webhook delivery failed
# Output data is still available
if run.output:
process_output(run.output)
```
```typescript TypeScript
const run = await client.getRun(runId);
if (run.status === "failed" && run.failure_reason?.toLowerCase().includes("webhook")) {
console.log(`Webhook failed: ${run.failure_reason}`);
// The task may have completed successfully before webhook delivery failed
// Output data is still available
if (run.output) {
processOutput(run.output);
}
}
```
```bash cURL
curl -X GET "https://api.skyvern.com/v1/runs/$RUN_ID" \
-H "x-api-key: $SKYVERN_API_KEY"
# Check status and failure_reason fields in response
```
</CodeGroup>
The `failure_reason` field contains the specific error message, for example:
```json
{
"run_id": "tsk_v2_486305187432193504",
"status": "failed",
"output": {"price": "$29.99"},
"failure_reason": "Failed to run task 2.0: Failed to send webhook. task_v2_id=tsk_v2_486305187432193504"
}
```
<Note>
Even when webhook delivery fails, the task's `output` field may still contain extracted data if the browser automation completed successfully before the webhook attempt.
</Note>
**Common reasons webhooks fail:**
- **Server unreachable**: Your server is down, behind a firewall, or the URL is incorrect. Verify the URL is publicly accessible (not `localhost`) and check your server logs for incoming requests.
- **Timeout**: Skyvern waits 10 seconds for a response. If your server takes longer, the delivery is marked as failed even if processing eventually succeeds. Return `200 OK` immediately and process the payload in a background job.
- **Server returns an error**: Your endpoint received the payload but responded with a non-2xx status code (e.g., 500). Check your server logs to identify the issue.
- **Signature validation fails**: If your verification logic rejects the request, make sure you're validating against the raw request body, not parsed-and-re-serialized JSON (re-serializing changes the byte representation). Also verify you're using the same API key that created the run.
**Recommended pattern:** Always have a fallback polling mechanism for critical workflows. If you don't receive a webhook within your expected window, call `get_run` to check if the run completed and retrieve the data directly.
### Retrying webhooks
Once you've identified and fixed the issue, you can replay the webhook using `retry_run_webhook`.
<Note>
Skyvern does not automatically retry failed webhooks. This is intentional: automatic retries can cause duplicate processing if your server received the payload but returned an error. You must explicitly call `retry_run_webhook` after fixing the issue.
</Note>
<CodeGroup>
```python Python
from skyvern.client import RetryRunWebhookRequest
await client.retry_run_webhook("tsk_v2_486305187432193504")
# Or send to a different URL
await client.retry_run_webhook(
"tsk_v2_486305187432193504",
request=RetryRunWebhookRequest(webhook_url="https://your-server.com/new-webhook")
)
```
```typescript TypeScript
await client.retryRunWebhook("tsk_v2_486305187432193504");
// Or send to a different URL
await client.retryRunWebhook("tsk_v2_486305187432193504", {
webhook_url: "https://your-server.com/new-webhook",
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/runs/tsk_v2_486305187432193504/retry_webhook" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
# Or send to a different URL
curl -X POST "https://api.skyvern.com/v1/runs/tsk_v2_486305187432193504/retry_webhook" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"webhook_url": "https://your-server.com/new-webhook"}'
```
</CodeGroup>
<Warning>
`retry_run_webhook` is fire-and-forget; it returns immediately without waiting for delivery confirmation. To verify success, monitor your webhook endpoint directly or check the run's `failure_reason` field after a short delay.
</Warning>
<Tip>
**Implement idempotency.** If you call `retry_run_webhook`, you may receive the same payload twice (once from the original attempt that your server processed but returned an error, and once from the retry). Use the `run_id` as an idempotency key: check if you've already processed this run before taking action.
</Tip>
You can pass a different `webhook_url` to send the payload to a new endpoint; useful if the original URL was misconfigured.
---
## Next steps
<CardGroup cols={2}>
<Card
title="Error Handling"
icon="triangle-exclamation"
href="/developers/going-to-production/error-handling"
>
Handle failures and map custom error codes
</Card>
<Card
title="Reliability Tips"
icon="shield-check"
href="/developers/going-to-production/reliability-tips"
>
Write robust prompts and add validation blocks
</Card>
</CardGroup>
@@ -0,0 +1,921 @@
---
title: Browser Profiles
subtitle: Save and reuse authenticated browser state across runs
description: Save browser state snapshots including cookies, localStorage, and session files as reusable profiles. Skip login steps and restore authenticated state instantly across workflow runs.
slug: developers/optimization/browser-profiles
keywords:
- create_browser_profile
- state snapshot
- skip login
- cookies
- localStorage
- session files
- persist_browser_session
---
A **Browser Profile** is a saved snapshot of browser state (cookies, localStorage, and session files) that you can reuse across multiple runs. Profiles let you skip login steps and restore authenticated state instantly.
Profiles are ideal when you:
- Run the same workflow repeatedly with the same account (daily data extraction, scheduled reports)
- Want multiple workflows to share the same authenticated state
- Need to avoid repeated authentication to save time and steps
---
## How profiles work
When a workflow runs with `persist_browser_session=true`, Skyvern archives the browser state (cookies, storage, session files) after the run completes. This archiving happens asynchronously in the background. Once the archive is ready, you can create a profile from it, then pass that profile to future workflow runs to restore the saved state.
---
## Create a Browser Profile
Create a workflow with `persist_browser_session=true` in the workflow definition, run it, wait for completion, then create a profile from the run. Session archiving happens asynchronously, so add brief retry logic when creating the profile.
<Note>
`persist_browser_session` must be set when **creating the workflow**, not when running it. It is a workflow definition property, not a runtime parameter.
</Note>
### From a workflow run
<CodeGroup>
```python Python
import asyncio
from skyvern import Skyvern
async def main():
client = Skyvern(api_key="YOUR_API_KEY")
# Step 1: Create a workflow with persist_browser_session=true
workflow = await client.create_workflow(
json_definition={
"title": "Login to Dashboard",
"persist_browser_session": True, # Set here in workflow definition
"workflow_definition": {
"parameters": [],
"blocks": [
{
"block_type": "navigation",
"label": "login",
"url": "https://dashboard.example.com/login",
"navigation_goal": "Login with the provided credentials"
}
]
}
}
)
print(f"Created workflow: {workflow.workflow_permanent_id}")
# Step 2: Run the workflow
workflow_run = await client.run_workflow(
workflow_id=workflow.workflow_permanent_id,
wait_for_completion=True,
)
print(f"Workflow completed: {workflow_run.status}")
# Step 3: Create profile from the completed run
# Retry briefly while session archives asynchronously
for attempt in range(10):
try:
profile = await client.create_browser_profile(
name="analytics-dashboard-login",
workflow_run_id=workflow_run.run_id,
description="Authenticated state for analytics dashboard",
)
print(f"Profile created: {profile.browser_profile_id}")
break
except Exception as e:
if "persisted" in str(e).lower() and attempt < 9:
await asyncio.sleep(1)
continue
raise
asyncio.run(main())
```
```typescript TypeScript
import { Skyvern } from "@skyvern/client";
async function main() {
const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });
// Step 1: Create a workflow with persist_browser_session=true
const workflow = await client.createWorkflow({
body: {
json_definition: {
title: "Login to Dashboard",
persist_browser_session: true, // Set here in workflow definition
workflow_definition: {
parameters: [],
blocks: [
{
block_type: "navigation",
label: "login",
url: "https://dashboard.example.com/login",
navigation_goal: "Login with the provided credentials"
}
]
}
}
}
});
console.log(`Created workflow: ${workflow.workflow_permanent_id}`);
// Step 2: Run the workflow and wait for completion
const workflowRun = await client.runWorkflow({
body: { workflow_id: workflow.workflow_permanent_id },
waitForCompletion: true,
});
console.log(`Workflow completed: ${workflowRun.status}`);
// Step 3: Create profile from the completed run
let profile;
for (let attempt = 0; attempt < 10; attempt++) {
try {
profile = await client.createBrowserProfile({
name: "analytics-dashboard-login",
workflow_run_id: workflowRun.run_id,
description: "Authenticated state for analytics dashboard",
});
break;
} catch (e) {
if (String(e).toLowerCase().includes("persisted") && attempt < 9) {
await new Promise((r) => setTimeout(r, 1000));
continue;
}
throw e;
}
}
console.log(`Profile created: ${profile.browser_profile_id}`);
}
main();
```
```bash cURL
# Step 1: Create a workflow with persist_browser_session=true
WORKFLOW_RESPONSE=$(curl -s -X POST "https://api.skyvern.com/v1/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"json_definition": {
"title": "Login to Dashboard",
"persist_browser_session": true,
"workflow_definition": {
"parameters": [],
"blocks": [
{
"block_type": "navigation",
"label": "login",
"url": "https://dashboard.example.com/login",
"navigation_goal": "Login with the provided credentials"
}
]
}
}
}')
WORKFLOW_ID=$(echo "$WORKFLOW_RESPONSE" | jq -r '.workflow_permanent_id')
echo "Created workflow: $WORKFLOW_ID"
# Step 2: Run the workflow
RUN_RESPONSE=$(curl -s -X POST "https://api.skyvern.com/v1/run/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"workflow_id\": \"$WORKFLOW_ID\"}")
RUN_ID=$(echo "$RUN_RESPONSE" | jq -r '.run_id')
# Wait for completion
while true; do
STATUS=$(curl -s "https://api.skyvern.com/v1/runs/$RUN_ID" \
-H "x-api-key: $SKYVERN_API_KEY" | jq -r '.status')
[ "$STATUS" != "created" ] && [ "$STATUS" != "queued" ] && [ "$STATUS" != "running" ] && break
sleep 5
done
# Step 3: Create profile (retry while session archives)
for i in {1..10}; do
PROFILE_RESPONSE=$(curl -s -X POST "https://api.skyvern.com/v1/browser_profiles" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"name\": \"analytics-dashboard-login\",
\"workflow_run_id\": \"$RUN_ID\",
\"description\": \"Authenticated state for analytics dashboard\"
}")
if echo "$PROFILE_RESPONSE" | jq -e '.browser_profile_id' > /dev/null 2>&1; then
echo "$PROFILE_RESPONSE"
break
fi
sleep 1
done
```
</CodeGroup>
**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Required. Display name for the profile. Must be unique within your organization |
| `workflow_run_id` | string | ID of the completed workflow run to create the profile from |
| `description` | string | Optional description of the profile's purpose |
### From a browser session
You can also create a profile from a [Browser Session](/developers/optimization/browser-sessions) that was used inside a workflow with `persist_browser_session=true`. After the workflow run completes and the session is closed, pass the session ID instead of the workflow run ID.
<Warning>
Only sessions that were part of a workflow with `persist_browser_session=true` produce an archive. A session created with `create_browser_session()` alone does not archive its state. Archiving happens asynchronously after the session closes, so add retry logic.
</Warning>
<CodeGroup>
```python Python
import asyncio
from skyvern import Skyvern
async def main():
client = Skyvern(api_key="YOUR_API_KEY")
# browser_session_id from a workflow run with persist_browser_session=true
session_id = "pbs_your_session_id"
# Create profile from the closed session (retry while archive uploads)
for attempt in range(10):
try:
profile = await client.create_browser_profile(
name="dashboard-admin-login",
browser_session_id=session_id,
description="Admin account for dashboard access",
)
print(f"Profile created: {profile.browser_profile_id}")
break
except Exception as e:
if "persisted" in str(e).lower() and attempt < 9:
await asyncio.sleep(2)
continue
raise
asyncio.run(main())
```
```typescript TypeScript
import { Skyvern } from "@skyvern/client";
async function main() {
const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });
// browser_session_id from a workflow run with persist_browser_session=true
const sessionId = "pbs_your_session_id";
// Create profile from the closed session (retry while archive uploads)
let profile;
for (let attempt = 0; attempt < 10; attempt++) {
try {
profile = await client.createBrowserProfile({
name: "dashboard-admin-login",
browser_session_id: sessionId,
description: "Admin account for dashboard access",
});
break;
} catch (e) {
if (String(e).toLowerCase().includes("persisted") && attempt < 9) {
await new Promise((r) => setTimeout(r, 2000));
continue;
}
throw e;
}
}
console.log(`Profile created: ${profile.browser_profile_id}`);
}
main();
```
```bash cURL
# browser_session_id from a workflow run with persist_browser_session=true
SESSION_ID="pbs_your_session_id"
# Create profile (retry while session archives)
for i in {1..10}; do
PROFILE_RESPONSE=$(curl -s -X POST "https://api.skyvern.com/v1/browser_profiles" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"name\": \"dashboard-admin-login\",
\"browser_session_id\": \"$SESSION_ID\",
\"description\": \"Admin account for dashboard access\"
}")
if echo "$PROFILE_RESPONSE" | jq -e '.browser_profile_id' > /dev/null 2>&1; then
echo "$PROFILE_RESPONSE"
break
fi
sleep 2
done
```
</CodeGroup>
**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Required. Display name for the profile. Must be unique within your organization |
| `browser_session_id` | string | ID of the closed browser session (starts with `pbs_`). The session must have been part of a workflow with `persist_browser_session=true` |
| `description` | string | Optional description of the profile's purpose |
---
## Use a Browser Profile
Pass `browser_profile_id` when running a workflow to restore the saved state. Skyvern restores cookies, localStorage, and session files before the first step runs.
<CodeGroup>
```python Python
import asyncio
from skyvern import Skyvern
async def main():
client = Skyvern(api_key="YOUR_API_KEY")
# Run workflow with saved profile, no login needed
result = await client.run_workflow(
workflow_id="wpid_daily_metrics",
browser_profile_id="bp_490705123456789012",
wait_for_completion=True,
)
print(f"Output: {result.output}")
asyncio.run(main())
```
```typescript TypeScript
import { Skyvern } from "@skyvern/client";
async function main() {
const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });
// Run workflow with saved profile, no login needed
const result = await client.runWorkflow({
body: {
workflow_id: "wpid_daily_metrics",
browser_profile_id: "bp_490705123456789012",
},
waitForCompletion: true,
});
console.log(`Output: ${JSON.stringify(result.output)}`);
}
main();
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "wpid_daily_metrics",
"browser_profile_id": "bp_490705123456789012"
}'
```
</CodeGroup>
**Example response:**
```json
{
"run_id": "wr_494469342201718946",
"status": "created",
"run_request": {
"workflow_id": "wpid_daily_metrics",
"browser_profile_id": "bp_490705123456789012",
"proxy_location": "RESIDENTIAL"
}
}
```
<Note>
`browser_profile_id` is supported for workflows only. It is not available for standalone tasks via `run_task`. You also cannot use both `browser_profile_id` and `browser_session_id` in the same request.
</Note>
---
## Tutorial: save and reuse browsing state
This walkthrough demonstrates the full profile lifecycle: create a workflow that saves browser state, capture that state as a profile, then reuse it in a second workflow. Each step shows the code and the actual API response.
<Steps>
<Step title="Create a workflow with persist_browser_session">
The workflow must have `persist_browser_session=true` so Skyvern archives the browser state after the run.
<CodeGroup>
```python Python
workflow = await client.create_workflow(
json_definition={
"title": "Visit Hacker News",
"persist_browser_session": True,
"workflow_definition": {
"parameters": [],
"blocks": [
{
"block_type": "navigation",
"label": "visit_hn",
"url": "https://news.ycombinator.com",
"navigation_goal": "Navigate to the Hacker News homepage and confirm it loaded"
}
]
}
}
)
print(workflow.workflow_permanent_id) # wpid_494674198088536840
print(workflow.persist_browser_session) # True
```
```typescript TypeScript
const workflow = await client.createWorkflow({
body: {
json_definition: {
title: "Visit Hacker News",
persist_browser_session: true,
workflow_definition: {
parameters: [],
blocks: [
{
block_type: "navigation",
label: "visit_hn",
url: "https://news.ycombinator.com",
navigation_goal: "Navigate to the Hacker News homepage and confirm it loaded"
}
]
}
}
}
});
console.log(workflow.workflow_permanent_id); // wpid_494674198088536840
```
```bash cURL
curl -s -X POST "https://api.skyvern.com/v1/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"json_definition": {
"title": "Visit Hacker News",
"persist_browser_session": true,
"workflow_definition": {
"parameters": [],
"blocks": [
{
"block_type": "navigation",
"label": "visit_hn",
"url": "https://news.ycombinator.com",
"navigation_goal": "Navigate to the Hacker News homepage and confirm it loaded"
}
]
}
}
}'
```
</CodeGroup>
```json Response
{
"workflow_permanent_id": "wpid_494674198088536840",
"persist_browser_session": true,
"title": "Visit Hacker News"
}
```
</Step>
<Step title="Run the workflow">
Run the workflow and wait for it to complete. Skyvern opens a browser, executes the navigation block, then archives the browser state in the background.
<CodeGroup>
```python Python
run = await client.run_workflow(
workflow_id=workflow.workflow_permanent_id,
wait_for_completion=True,
)
print(run.run_id) # wr_494674202383504144
print(run.status) # completed
```
```typescript TypeScript
const run = await client.runWorkflow({
body: { workflow_id: workflow.workflow_permanent_id },
waitForCompletion: true,
});
console.log(run.run_id); // wr_494674202383504144
console.log(run.status); // completed
```
```bash cURL
RUN=$(curl -s -X POST "https://api.skyvern.com/v1/run/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"workflow_id\": \"$WORKFLOW_ID\"}")
RUN_ID=$(echo "$RUN" | jq -r '.run_id')
# Poll until complete
while true; do
STATUS=$(curl -s "https://api.skyvern.com/v1/runs/$RUN_ID" \
-H "x-api-key: $SKYVERN_API_KEY" | jq -r '.status')
[ "$STATUS" != "created" ] && [ "$STATUS" != "queued" ] && [ "$STATUS" != "running" ] && break
sleep 5
done
```
</CodeGroup>
```json Response
{
"run_id": "wr_494674202383504144",
"status": "completed"
}
```
</Step>
<Step title="Create a profile from the completed run">
Archiving happens asynchronously after the run completes, so add retry logic. In practice the archive is usually ready within a few seconds.
<CodeGroup>
```python Python
for attempt in range(10):
try:
profile = await client.create_browser_profile(
name="hn-browsing-state",
workflow_run_id=run.run_id,
description="Hacker News cookies and browsing state",
)
print(profile.browser_profile_id) # bp_494674399951999772
break
except Exception as e:
if "persisted" in str(e).lower() and attempt < 9:
await asyncio.sleep(2)
continue
raise
```
```typescript TypeScript
let profile;
for (let attempt = 0; attempt < 10; attempt++) {
try {
profile = await client.createBrowserProfile({
name: "hn-browsing-state",
workflow_run_id: run.run_id,
description: "Hacker News cookies and browsing state",
});
console.log(profile.browser_profile_id); // bp_494674399951999772
break;
} catch (e) {
if (String(e).toLowerCase().includes("persisted") && attempt < 9) {
await new Promise((r) => setTimeout(r, 2000));
continue;
}
throw e;
}
}
```
```bash cURL
for i in {1..10}; do
PROFILE=$(curl -s -X POST "https://api.skyvern.com/v1/browser_profiles" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"name\": \"hn-browsing-state\",
\"workflow_run_id\": \"$RUN_ID\",
\"description\": \"Hacker News cookies and browsing state\"
}")
PROFILE_ID=$(echo "$PROFILE" | jq -r '.browser_profile_id // empty')
if [ -n "$PROFILE_ID" ]; then
echo "$PROFILE" | jq .
break
fi
sleep 2
done
```
</CodeGroup>
```json Response
{
"browser_profile_id": "bp_494674399951999772",
"organization_id": "o_475582633898688888",
"name": "hn-browsing-state",
"description": "Hacker News cookies and browsing state",
"created_at": "2026-02-12T01:09:18.048208",
"modified_at": "2026-02-12T01:09:18.048212",
"deleted_at": null
}
```
</Step>
<Step title="Verify the profile exists">
List all profiles or fetch one by ID to confirm it was saved.
<CodeGroup>
```python Python
# List all profiles
profiles = await client.list_browser_profiles()
print(len(profiles)) # 1
# Get a single profile
fetched = await client.get_browser_profile(profile_id=profile.browser_profile_id)
print(fetched.name) # hn-browsing-state
```
```typescript TypeScript
// List all profiles
const profiles = await client.listBrowserProfiles({});
console.log(profiles.length); // 1
// Get a single profile
const fetched = await client.getBrowserProfile(profile.browser_profile_id);
console.log(fetched.name); // hn-browsing-state
```
```bash cURL
# List all profiles
curl -s "https://api.skyvern.com/v1/browser_profiles" \
-H "x-api-key: $SKYVERN_API_KEY" | jq '.[].name'
# Get a single profile
curl -s "https://api.skyvern.com/v1/browser_profiles/$PROFILE_ID" \
-H "x-api-key: $SKYVERN_API_KEY" | jq .
```
</CodeGroup>
```json List response
[
{
"browser_profile_id": "bp_494674399951999772",
"name": "hn-browsing-state",
"created_at": "2026-02-12T01:09:18.048208"
}
]
```
</Step>
<Step title="Reuse the profile in a second workflow">
Pass `browser_profile_id` when running a workflow. Skyvern restores the saved cookies, localStorage, and session files before the first block runs. The second workflow starts with the browser state from step 2, no repeat navigation needed.
<CodeGroup>
```python Python
result = await client.run_workflow(
workflow_id=data_workflow.workflow_permanent_id,
browser_profile_id=profile.browser_profile_id,
wait_for_completion=True,
)
print(result.status) # completed
```
```typescript TypeScript
const result = await client.runWorkflow({
body: {
workflow_id: dataWorkflow.workflow_permanent_id,
browser_profile_id: profile.browser_profile_id,
},
waitForCompletion: true,
});
console.log(result.status); // completed
```
```bash cURL
curl -s -X POST "https://api.skyvern.com/v1/run/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"workflow_id\": \"$WORKFLOW2_ID\",
\"browser_profile_id\": \"$PROFILE_ID\"
}"
```
</CodeGroup>
```json Response
{
"run_id": "wr_494674434311738148",
"status": "created"
}
```
</Step>
<Step title="Delete the profile">
Clean up profiles you no longer need.
<CodeGroup>
```python Python
await client.delete_browser_profile(profile_id=profile.browser_profile_id)
# Confirm deletion
remaining = await client.list_browser_profiles()
print(len(remaining)) # 0
```
```typescript TypeScript
await client.deleteBrowserProfile(profile.browser_profile_id);
// Confirm deletion
const remaining = await client.listBrowserProfiles({});
console.log(remaining.length); // 0
```
```bash cURL
curl -s -X DELETE "https://api.skyvern.com/v1/browser_profiles/$PROFILE_ID" \
-H "x-api-key: $SKYVERN_API_KEY"
```
</CodeGroup>
</Step>
</Steps>
<Tip>
In a real scenario, step 1 would be a login workflow that authenticates with a site. The saved profile then lets all future workflows skip the login step entirely.
</Tip>
---
## Best practices
### Use descriptive names
Include the account, site, and purpose in the profile name so it is easy to identify later.
<CodeGroup>
```python Python
# Good: identifies account, site, and purpose
profile = await client.create_browser_profile(
name="prod-salesforce-admin",
description="Admin login for daily opportunity sync",
workflow_run_id=run_id,
)
# Bad: unclear what this is for
profile = await client.create_browser_profile(
name="profile1",
workflow_run_id=run_id,
)
```
```typescript TypeScript
// Good: identifies account, site, and purpose
const profile = await client.createBrowserProfile({
name: "prod-salesforce-admin",
description: "Admin login for daily opportunity sync",
workflow_run_id: runId,
});
// Bad: unclear what this is for
const badProfile = await client.createBrowserProfile({
name: "profile1",
workflow_run_id: runId,
});
```
</CodeGroup>
### Refresh profiles periodically
Session tokens and cookies expire. Re-run your login workflow and create fresh profiles before they go stale. Adding the date to the name makes it easy to track which profile is current.
<CodeGroup>
```python Python
from datetime import date
# Create dated profile after each successful login
profile = await client.create_browser_profile(
name=f"crm-login-{date.today()}",
workflow_run_id=new_login_run.run_id,
)
# Delete old profile
await client.delete_browser_profile(old_profile_id)
```
```typescript TypeScript
// Create dated profile after each successful login
const profile = await client.createBrowserProfile({
name: `crm-login-${new Date().toISOString().split("T")[0]}`,
workflow_run_id: newLoginRun.run_id,
});
// Delete old profile
await client.deleteBrowserProfile(oldProfileId);
```
```bash cURL
# Create dated profile after a successful login run
curl -X POST "https://api.skyvern.com/v1/browser_profiles" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"name\": \"crm-login-$(date +%Y-%m-%d)\",
\"workflow_run_id\": \"$NEW_RUN_ID\"
}"
# Delete old profile
curl -X DELETE "https://api.skyvern.com/v1/browser_profiles/$OLD_PROFILE_ID" \
-H "x-api-key: $SKYVERN_API_KEY"
```
</CodeGroup>
### Capture updated state after each run
To capture state changes during a run (like token refreshes), the workflow must have `persist_browser_session=true` in its definition. This lets you create a fresh profile from each completed run.
<CodeGroup>
```python Python
from datetime import date
# Step 1: Create workflow with persist_browser_session in the definition
workflow = await client.create_workflow(
json_definition={
"title": "Daily Sync",
"persist_browser_session": True, # Set here, not in run_workflow
"workflow_definition": {
"parameters": [],
"blocks": [...]
}
}
)
# Step 2: Run with an existing profile
result = await client.run_workflow(
workflow_id=workflow.workflow_permanent_id,
browser_profile_id="bp_current",
wait_for_completion=True,
)
# Step 3: Create updated profile from the completed run
if should_refresh_profile:
new_profile = await client.create_browser_profile(
name=f"daily-sync-{date.today()}",
workflow_run_id=result.run_id,
)
```
```typescript TypeScript
// Step 1: Create workflow with persist_browser_session in the definition
const workflow = await client.createWorkflow({
body: {
json_definition: {
title: "Daily Sync",
persist_browser_session: true, // Set here, not in runWorkflow
workflow_definition: {
parameters: [],
blocks: [/* ... */]
}
}
}
});
// Step 2: Run with an existing profile
const result = await client.runWorkflow({
body: {
workflow_id: workflow.workflow_permanent_id,
browser_profile_id: "bp_current",
},
waitForCompletion: true,
});
// Step 3: Create updated profile from the completed run
if (shouldRefreshProfile) {
const newProfile = await client.createBrowserProfile({
name: `daily-sync-${new Date().toISOString().split("T")[0]}`,
workflow_run_id: result.run_id,
});
}
```
</CodeGroup>
---
## Next steps
<CardGroup cols={2}>
<Card
title="Browser Sessions"
icon="browser"
href="/developers/optimization/browser-sessions"
>
Maintain live browser state for real-time interactions
</Card>
<Card
title="Cost Control"
icon="dollar-sign"
href="/developers/optimization/cost-control"
>
Optimize costs with max_steps and efficient prompts
</Card>
</CardGroup>
@@ -0,0 +1,726 @@
---
title: Browser Sessions
subtitle: Persist live browser state across multiple tasks and workflows
description: Create and manage live browser sessions that persist cookies, local storage, and page state between task or workflow runs. Use sessions for back-to-back tasks, human-in-the-loop approval, and real-time agents.
slug: developers/optimization/browser-sessions
keywords:
- create_browser_session
- persistent state
- cookies
- local storage
- timeout
- session chaining
- human-in-the-loop
- real-time agent
---
A **Browser Session** is a live browser instance that persists cookies, local storage, and page state between task or workflow runs. Think of it as keeping a browser tab open. Use sessions when you need back-to-back tasks to share state, human-in-the-loop approval, or real-time agents.
---
## Create a session
Start a session with optional configuration for timeout, proxy, browser type, and extensions.
<CodeGroup>
```python Python
import asyncio
from skyvern import Skyvern
async def main():
client = Skyvern(api_key="YOUR_API_KEY")
session = await client.create_browser_session(
timeout=60, # Max 60 minutes
proxy_location="RESIDENTIAL", # US residential proxy
browser_type="chrome", # Chrome or Edge
extensions=["ad-blocker"], # Optional extensions
)
print(f"Session ID: {session.browser_session_id}")
print(f"Status: {session.status}")
asyncio.run(main())
```
```typescript TypeScript
import { Skyvern } from "@skyvern/client";
async function main() {
const client = new Skyvern({
apiKey: process.env.SKYVERN_API_KEY!,
});
const session = await client.createBrowserSession({
timeout: 60,
proxy_location: "RESIDENTIAL",
browser_type: "chrome",
extensions: ["ad-blocker"],
});
console.log(`Session ID: ${session.browser_session_id}`);
console.log(`Status: ${session.status}`);
}
main();
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/browser_sessions" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"timeout": 60,
"proxy_location": "RESIDENTIAL",
"browser_type": "chrome",
"extensions": ["ad-blocker"]
}'
```
</CodeGroup>
**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `timeout` | integer | Session lifetime in minutes. Min: 5, Max: 1440 (24 hours). Default: `60` |
| `proxy_location` | string | Geographic proxy location (Cloud only). See [Proxy & Geolocation](/developers/going-to-production/proxy-geolocation) for available options |
| `browser_type` | string | Browser type: `chrome` or `msedge` |
| `extensions` | array | Extensions to install: `ad-blocker`, `captcha-solver` |
**Example response:**
```json
{
"browser_session_id": "pbs_490705123456789012",
"organization_id": "o_485917350850524254",
"status": "running",
"timeout": 60,
"browser_type": "chrome",
"extensions": ["ad-blocker"],
"vnc_streaming_supported": true,
"app_url": "https://app.skyvern.com/browser-session/pbs_490705123456789012",
"started_at": "2026-02-01T10:30:03.110Z",
"created_at": "2026-02-01T10:30:00.000Z",
"modified_at": "2026-02-01T10:30:03.251Z"
}
```
**Session statuses:**
| Status | Description |
|--------|-------------|
| `running` | Browser is live and accepting tasks. This is the status returned on creation. The browser launches within seconds. |
| `closed` | Session was closed manually or by timeout. No further tasks can run. |
<Warning>
Sessions close automatically when the timeout expires, **even if a task is still running**. The timeout countdown begins when the browser launches. Set timeouts with enough margin for your longest expected task.
</Warning>
---
## Run tasks with a session
Pass `browser_session_id` to `run_task` to execute tasks in an existing session. Each task continues from where the previous one left off: same page, same cookies, same form data.
<CodeGroup>
```python Python
import asyncio
from skyvern import Skyvern
async def main():
client = Skyvern(api_key="YOUR_API_KEY")
# Create session
session = await client.create_browser_session(timeout=30)
session_id = session.browser_session_id
try:
# Task 1: Login (wait for completion before continuing)
await client.run_task(
prompt="Login with username 'support@company.com'",
url="https://dashboard.example.com/login",
browser_session_id=session_id,
wait_for_completion=True,
)
# Task 2: Search (already logged in from Task 1)
result = await client.run_task(
prompt="Find customer with email 'customer@example.com'",
browser_session_id=session_id,
wait_for_completion=True,
)
print(f"Customer: {result.output}")
finally:
# Always close when done
await client.close_browser_session(browser_session_id=session_id)
asyncio.run(main())
```
```typescript TypeScript
import { Skyvern } from "@skyvern/client";
async function main() {
const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });
const session = await client.createBrowserSession({ timeout: 30 });
const sessionId = session.browser_session_id;
try {
// Task 1: Login (wait for completion)
await client.runTask({
body: {
prompt: "Login with username 'support@company.com'",
url: "https://dashboard.example.com/login",
browser_session_id: sessionId,
},
waitForCompletion: true,
});
// Task 2: Search (reuses login state)
const result = await client.runTask({
body: {
prompt: "Find customer with email 'customer@example.com'",
browser_session_id: sessionId,
},
waitForCompletion: true,
});
console.log(`Customer: ${JSON.stringify(result.output)}`);
} finally {
await client.closeBrowserSession(sessionId);
}
}
main();
```
```bash cURL
# Create session
SESSION_ID=$(curl -s -X POST "https://api.skyvern.com/v1/browser_sessions" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"timeout": 30}' | jq -r '.browser_session_id')
echo "Session: $SESSION_ID"
# Task 1: Login
RUN_ID=$(curl -s -X POST "https://api.skyvern.com/v1/run/tasks" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"prompt\": \"Login with username 'support@company.com'\",
\"url\": \"https://dashboard.example.com/login\",
\"browser_session_id\": \"$SESSION_ID\"
}" | jq -r '.run_id')
# Poll until complete
while true; do
STATUS=$(curl -s "https://api.skyvern.com/v1/runs/$RUN_ID" \
-H "x-api-key: $SKYVERN_API_KEY" | jq -r '.status')
[ "$STATUS" != "created" ] && [ "$STATUS" != "queued" ] && [ "$STATUS" != "running" ] && break
sleep 5
done
# Task 2: Search (reuses login state)
curl -s -X POST "https://api.skyvern.com/v1/run/tasks" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"prompt\": \"Find customer with email 'customer@example.com'\",
\"browser_session_id\": \"$SESSION_ID\"
}"
# Close session when done
curl -s -X POST "https://api.skyvern.com/v1/browser_sessions/$SESSION_ID/close" \
-H "x-api-key: $SKYVERN_API_KEY"
```
</CodeGroup>
---
## Run workflows with a session
Pass `browser_session_id` to `run_workflow` to execute a workflow in an existing session. This is useful when you need to run a predefined workflow but want it to continue from your current browser state.
<CodeGroup>
```python Python
import asyncio
from skyvern import Skyvern
async def main():
client = Skyvern(api_key="YOUR_API_KEY")
# Create session
session = await client.create_browser_session(timeout=60)
session_id = session.browser_session_id
try:
# First, login manually via a task
await client.run_task(
prompt="Login with username 'admin@company.com'",
url="https://app.example.com/login",
browser_session_id=session_id,
wait_for_completion=True,
)
# Then run a workflow in the same session (already logged in)
result = await client.run_workflow(
workflow_id="wpid_export_monthly_report",
browser_session_id=session_id,
wait_for_completion=True,
)
print(f"Workflow completed: {result.status}")
finally:
await client.close_browser_session(browser_session_id=session_id)
asyncio.run(main())
```
```typescript TypeScript
import { Skyvern } from "@skyvern/client";
async function main() {
const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });
const session = await client.createBrowserSession({ timeout: 60 });
const sessionId = session.browser_session_id;
try {
// First, login manually via a task
await client.runTask({
body: {
prompt: "Login with username 'admin@company.com'",
url: "https://app.example.com/login",
browser_session_id: sessionId,
},
waitForCompletion: true,
});
// Then run a workflow in the same session (already logged in)
const result = await client.runWorkflow({
body: {
workflow_id: "wpid_export_monthly_report",
browser_session_id: sessionId,
},
waitForCompletion: true,
});
console.log(`Workflow completed: ${result.status}`);
} finally {
await client.closeBrowserSession(sessionId);
}
}
main();
```
```bash cURL
# Create session
SESSION_ID=$(curl -s -X POST "https://api.skyvern.com/v1/browser_sessions" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"timeout": 60}' | jq -r '.browser_session_id')
# Login via a task
RUN_ID=$(curl -s -X POST "https://api.skyvern.com/v1/run/tasks" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"prompt\": \"Login with username 'admin@company.com'\",
\"url\": \"https://app.example.com/login\",
\"browser_session_id\": \"$SESSION_ID\"
}" | jq -r '.run_id')
# Poll until login completes
while true; do
STATUS=$(curl -s "https://api.skyvern.com/v1/runs/$RUN_ID" \
-H "x-api-key: $SKYVERN_API_KEY" | jq -r '.status')
[ "$STATUS" != "created" ] && [ "$STATUS" != "queued" ] && [ "$STATUS" != "running" ] && break
sleep 5
done
# Run workflow in the same session (already logged in)
curl -s -X POST "https://api.skyvern.com/v1/run/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"workflow_id\": \"wpid_export_monthly_report\",
\"browser_session_id\": \"$SESSION_ID\"
}"
# Close session when done
curl -s -X POST "https://api.skyvern.com/v1/browser_sessions/$SESSION_ID/close" \
-H "x-api-key: $SKYVERN_API_KEY"
```
</CodeGroup>
<Note>
You cannot use both `browser_session_id` and `browser_profile_id` in the same request. Choose one or the other.
</Note>
---
## Close a session
Close a session to release resources and stop billing. The browser shuts down immediately.
<CodeGroup>
```python Python
await client.close_browser_session(
browser_session_id="pbs_490705123456789012"
)
```
```typescript TypeScript
await client.closeBrowserSession("pbs_490705123456789012");
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/browser_sessions/pbs_490705123456789012/close" \
-H "x-api-key: $SKYVERN_API_KEY"
```
</CodeGroup>
<Warning>
**Always close sessions when done.** Active sessions continue billing even when idle. Use try/finally blocks to ensure cleanup.
</Warning>
<CodeGroup>
```python Python
try:
session = await client.create_browser_session(timeout=30)
session_id = session.browser_session_id
# Do work...
await client.run_task(
prompt="...",
browser_session_id=session_id,
wait_for_completion=True,
)
finally:
# Always close, even if task fails
await client.close_browser_session(browser_session_id=session_id)
```
```typescript TypeScript
const session = await client.createBrowserSession({ timeout: 30 });
const sessionId = session.browser_session_id;
try {
await client.runTask({
body: {
prompt: "...",
browser_session_id: sessionId,
},
waitForCompletion: true,
});
} finally {
// Always close, even if task fails
await client.closeBrowserSession(sessionId);
}
```
</CodeGroup>
---
## Example: Human-in-the-loop
A shopping bot that pauses for human approval before completing a purchase.
<CodeGroup>
```python Python
import asyncio
from skyvern import Skyvern
async def shopping_with_approval():
client = Skyvern(api_key="YOUR_API_KEY")
session = await client.create_browser_session(timeout=15)
session_id = session.browser_session_id
try:
# Step 1: Add to cart
await client.run_task(
prompt="Find wireless headphones under $100, add top result to cart",
url="https://shop.example.com",
browser_session_id=session_id,
wait_for_completion=True,
)
# Step 2: Wait for human approval
approval = input("Approve purchase? (yes/no): ")
if approval.lower() == "yes":
# Step 3: Checkout (cart persists from Step 1)
result = await client.run_task(
prompt="Complete checkout and confirm order",
browser_session_id=session_id,
wait_for_completion=True,
)
print(f"Order placed: {result.output}")
else:
print("Purchase cancelled")
finally:
await client.close_browser_session(browser_session_id=session_id)
asyncio.run(shopping_with_approval())
```
```typescript TypeScript
import { Skyvern } from "@skyvern/client";
import * as readline from "readline";
async function shoppingWithApproval() {
const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });
const session = await client.createBrowserSession({ timeout: 15 });
const sessionId = session.browser_session_id;
try {
// Step 1: Add to cart
await client.runTask({
body: {
prompt: "Find wireless headphones under $100, add top result to cart",
url: "https://shop.example.com",
browser_session_id: sessionId,
},
waitForCompletion: true,
});
// Step 2: Wait for human approval
const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
const approval = await new Promise<string>((resolve) =>
rl.question("Approve purchase? (yes/no): ", resolve)
);
rl.close();
if (approval.toLowerCase() === "yes") {
// Step 3: Checkout (cart persists from Step 1)
const result = await client.runTask({
body: {
prompt: "Complete checkout and confirm order",
browser_session_id: sessionId,
},
waitForCompletion: true,
});
console.log(`Order placed: ${JSON.stringify(result.output)}`);
} else {
console.log("Purchase cancelled");
}
} finally {
await client.closeBrowserSession(sessionId);
}
}
shoppingWithApproval();
```
</CodeGroup>
The browser maintains the cart contents during the approval pause. No state is lost.
---
## Best practices
### Set appropriate timeouts
Sessions bill while open, so match the timeout to your use case. A task typically completes in 30 to 90 seconds, so a 10-minute timeout covers most multi-step sequences with margin. Human-in-the-loop flows need longer timeouts to account for wait time.
<CodeGroup>
```python Python
# Quick multi-step task (2-3 tasks back to back)
session = await client.create_browser_session(timeout=10)
# Human-in-the-loop with wait time for approval
session = await client.create_browser_session(timeout=60)
# Long-running agent that monitors a dashboard
session = await client.create_browser_session(timeout=480) # 8 hours
```
```typescript TypeScript
// Quick multi-step task (2-3 tasks back to back)
const session1 = await client.createBrowserSession({ timeout: 10 });
// Human-in-the-loop with wait time for approval
const session2 = await client.createBrowserSession({ timeout: 60 });
// Long-running agent that monitors a dashboard
const session3 = await client.createBrowserSession({ timeout: 480 }); // 8 hours
```
```bash cURL
# Quick multi-step task (2-3 tasks back to back)
curl -s -X POST "https://api.skyvern.com/v1/browser_sessions" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"timeout": 10}'
# Human-in-the-loop with wait time for approval
curl -s -X POST "https://api.skyvern.com/v1/browser_sessions" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"timeout": 60}'
# Long-running agent that monitors a dashboard
curl -s -X POST "https://api.skyvern.com/v1/browser_sessions" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"timeout": 480}'
```
</CodeGroup>
### Use workflows for predetermined sequences
If your steps don't need pauses between them, a workflow runs them in a single browser instance without the overhead of creating and managing a session. Each task in a session incurs its own startup cost, while workflow blocks share one browser.
<CodeGroup>
```python Python
# Less efficient: multiple tasks in a session (each task has startup overhead)
session = await client.create_browser_session()
await client.run_task(prompt="Step 1", browser_session_id=session.browser_session_id, wait_for_completion=True)
await client.run_task(prompt="Step 2", browser_session_id=session.browser_session_id, wait_for_completion=True)
# More efficient: single workflow (blocks share one browser, no inter-task overhead)
await client.run_workflow(workflow_id="wpid_abc", wait_for_completion=True)
```
```typescript TypeScript
// Less efficient: multiple tasks in a session (each task has startup overhead)
const session = await client.createBrowserSession({});
await client.runTask({ body: { prompt: "Step 1", browser_session_id: session.browser_session_id }, waitForCompletion: true });
await client.runTask({ body: { prompt: "Step 2", browser_session_id: session.browser_session_id }, waitForCompletion: true });
// More efficient: single workflow (blocks share one browser, no inter-task overhead)
await client.runWorkflow({ body: { workflow_id: "wpid_abc" }, waitForCompletion: true });
```
</CodeGroup>
### Choose the right browser type
Chrome has the widest compatibility. Use Edge only when a site requires or detects it specifically.
<CodeGroup>
```python Python
# Chrome (default) - widest compatibility
session = await client.create_browser_session(browser_type="chrome")
# Edge - for sites that require or fingerprint Edge
session = await client.create_browser_session(browser_type="msedge")
```
```typescript TypeScript
// Chrome (default) - widest compatibility
const chromeSession = await client.createBrowserSession({ browser_type: "chrome" });
// Edge - for sites that require or fingerprint Edge
const edgeSession = await client.createBrowserSession({ browser_type: "msedge" });
```
```bash cURL
# Chrome (default) - widest compatibility
curl -s -X POST "https://api.skyvern.com/v1/browser_sessions" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"browser_type": "chrome"}'
# Edge - for sites that require or fingerprint Edge
curl -s -X POST "https://api.skyvern.com/v1/browser_sessions" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"browser_type": "msedge"}'
```
</CodeGroup>
### Use extensions strategically
Extensions add startup time, so only enable them when needed. The ad-blocker removes overlay ads that can interfere with automation. The captcha-solver handles CAPTCHAs automatically but is only available on Cloud.
<CodeGroup>
```python Python
# Block ads that overlay content and interfere with clicks
session = await client.create_browser_session(extensions=["ad-blocker"])
# Auto-solve captchas (Cloud only)
session = await client.create_browser_session(extensions=["captcha-solver"])
```
```typescript TypeScript
// Block ads that overlay content and interfere with clicks
const adBlockSession = await client.createBrowserSession({ extensions: ["ad-blocker"] });
// Auto-solve captchas (Cloud only)
const captchaSession = await client.createBrowserSession({ extensions: ["captcha-solver"] });
```
```bash cURL
# Block ads that overlay content and interfere with clicks
curl -s -X POST "https://api.skyvern.com/v1/browser_sessions" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"extensions": ["ad-blocker"]}'
# Auto-solve captchas (Cloud only)
curl -s -X POST "https://api.skyvern.com/v1/browser_sessions" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"extensions": ["captcha-solver"]}'
```
</CodeGroup>
---
## Sessions vs Profiles
Skyvern also offers [Browser Profiles](/developers/optimization/browser-profiles), saved snapshots of browser state (cookies, storage, session files) that you can reuse across days or weeks. Choose based on your use case:
| Aspect | Browser Session | Browser Profile |
|--------|----------------|-----------------|
| **What it is** | Live browser instance | Saved snapshot of browser state |
| **Lifetime** | Minutes to hours | Days to months |
| **State** | Current page, cookies, open connections | Cookies, storage, session files |
| **Billing** | Charged while open | No cost when not in use |
| **Best for** | Back-to-back tasks, human-in-the-loop, real-time agents | Repeated logins, scheduled workflows, shared auth state |
<Tip>
You can create a [Browser Profile](/developers/optimization/browser-profiles) from a completed session to save its authenticated state for future reuse.
</Tip>
---
## Next steps
<CardGroup cols={2}>
<Card
title="Connect Your Local Browser"
icon="laptop"
href="/developers/optimization/browser-tunneling"
>
Let Skyvern Cloud use your local browser with your existing logins
</Card>
<Card
title="Browser Profiles"
icon="floppy-disk"
href="/developers/optimization/browser-profiles"
>
Save session state for reuse across days
</Card>
<Card
title="Cost Control"
icon="dollar-sign"
href="/developers/optimization/cost-control"
>
Optimize costs with max_steps and efficient prompts
</Card>
</CardGroup>
@@ -0,0 +1,267 @@
---
title: Connect Skyvern to Your Local Browser
subtitle: Run automations using your existing cookies, logins, and extensions
description: Use skyvern browser serve to let Skyvern Cloud control a Chrome browser on your local machine, reusing your existing cookies, sessions, extensions, and saved passwords through a secure tunnel.
slug: developers/optimization/browser-tunneling
keywords:
- browser session
- task
- CLI
- authentication
- login
- proxy
- Playwright
---
Want Skyvern Cloud to automate a site where you're already logged in? With `skyvern browser serve`, Skyvern Cloud can control a Chrome browser running on your machine, using your existing cookies, sessions, extensions, and saved passwords.
**Common use cases:**
- Automate sites where you're already authenticated (no need to re-login)
- Reach internal tools behind a VPN or firewall
- Use browser extensions you've already installed (ad blockers, auth tools, etc.)
- Keep all browser data on your own machine
---
## Quick start
One command starts Chrome on your machine and creates a tunnel so Skyvern Cloud can connect:
```bash
skyvern browser serve --tunnel
```
That's it. The CLI launches Chrome, starts a local proxy server, and opens an ngrok tunnel. You'll see a tunnel URL in the output; pass it as `browser_address` when running tasks.
<Note>
The `--tunnel` flag requires [ngrok](https://ngrok.com/download) to be installed and authenticated. Run `ngrok authtoken <your-token>` once to set it up.
</Note>
### Step-by-step (manual tunnel)
If you prefer to manage the tunnel yourself:
```bash
# 1. Start the browser server
skyvern browser serve
# 2. In a separate terminal, create a tunnel
ngrok http 9222
# 3. Copy the ngrok URL and use it as browser_address in your task
```
---
## Run a task on your local browser
Once the tunnel is running, pass the tunnel URL as `browser_address`:
<CodeGroup>
```python Python
import asyncio
from skyvern import Skyvern
async def main():
client = Skyvern(api_key="YOUR_API_KEY")
result = await client.run_task(
prompt="Download the latest invoice from my account",
browser_address="wss://abc123.ngrok-free.dev",
)
print(f"Status: {result.status}")
print(f"Output: {result.output}")
asyncio.run(main())
```
```typescript TypeScript
import { Skyvern } from "@skyvern/client";
async function main() {
const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });
const result = await client.runTask({
body: {
prompt: "Download the latest invoice from my account",
browser_address: "wss://abc123.ngrok-free.dev",
},
waitForCompletion: true,
});
console.log(`Status: ${result.status}`);
console.log(`Output: ${JSON.stringify(result.output)}`);
}
main();
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Download the latest invoice from my account",
"browser_address": "wss://abc123.ngrok-free.dev"
}'
```
</CodeGroup>
---
## How it works
```
┌──────────────────────────────────────────────────────┐
│ Your machine │
│ │
│ ┌────────────┐ CDP (internal) ┌──────────────┐ │
│ │ Chrome │◄─────────────────►│ Unified │ │
│ │ (port │ port 10222 │ Server │ │
│ │ 10222) │ │ (port 9222) │ │
│ └────────────┘ └──────┬───────┘ │
│ │ │
└──────────────────────────────────────────┼───────────┘
│
ngrok / tunnel│
│
┌──────▼───────┐
│ Skyvern Cloud│
└──────────────┘
```
`skyvern browser serve`:
1. **Launches Chrome** with CDP (Chrome DevTools Protocol) enabled on an internal port
2. **Starts a proxy server** on the exposed port (default `9222`) that forwards CDP traffic to Chrome
3. **Optionally creates a tunnel** (`--tunnel`) so Skyvern Cloud can reach it from the internet
---
## CLI options
| Option | Default | Description |
|---|---|---|
| `--port` | `9222` | Port for the proxy server. Chrome uses `port + 1000` internally. |
| `--profile-dir` | `~/.skyvern/chrome-profile` | Chrome user data directory. Point this at an existing profile to reuse cookies and logins. |
| `--download-dir` | `~/.skyvern/downloads/{browser_id}` | Directory for browser downloads. |
| `--api-key` | (none) | API key for authenticating incoming requests. See [Security](#security). |
| `--headless` | `false` | Run Chrome in headless mode (no visible window). |
| `--chrome-path` | (auto-detect) | Path to Chrome/Chromium executable. |
| `--tunnel` | `false` | Automatically start an ngrok tunnel. Requires `ngrok` installed. |
| `--json` | `false` | Output connection info as JSON (for scripting). Cannot combine with `--tunnel`. |
The `--api-key` option can also be set via the `SKYVERN_BROWSER_SERVE_API_KEY` environment variable.
### Examples
```bash
# Use a specific Chrome profile (reuse your existing logins)
skyvern browser serve --profile-dir ~/Library/Application\ Support/Google/Chrome/Default
# Run headless with auto-tunnel
skyvern browser serve --headless --tunnel
# Custom port with API key authentication
skyvern browser serve --port 8222 --api-key "my-secret-key"
# Output connection info as JSON (useful for scripting)
skyvern browser serve --json
```
---
## Security
<Warning>
**Read this section before exposing your browser to the internet.**
When you run `skyvern browser serve` without `--api-key` and expose it via a tunnel, **anyone with the tunnel URL has full remote control of your Chrome browser**. This includes access to all logged-in sessions, cookies, saved passwords, and anything visible in the browser.
</Warning>
### API key authentication
Use your Skyvern API key (from [Settings](https://app.skyvern.com/settings)) with the `--api-key` flag to require authentication on every incoming request:
```bash
skyvern browser serve --api-key "your-skyvern-api-key"
```
Or set it via environment variable:
```bash
export SKYVERN_BROWSER_SERVE_API_KEY="your-skyvern-api-key"
skyvern browser serve
```
When enabled, all requests without a valid `x-api-key` header receive a `401 Unauthorized` response. Skyvern Cloud automatically sends the correct API key when connecting.
### Additional security measures
The built-in API key provides basic protection. For additional security such as IP allowlisting, mTLS, or VPN-based access, contact **support@skyvern.com**.
---
## When to use this vs other options
| Approach | When to use |
|----------|-------------|
| **Connect to your local browser** (`skyvern browser serve`) | You want Skyvern Cloud to use your local browser with your existing sessions |
| **[Browser Sessions](/developers/optimization/browser-sessions)** | You want Skyvern Cloud to manage the browser entirely in the cloud |
| **[Browser Profiles](/developers/optimization/browser-profiles)** | You want to save and reuse cookies/storage state across cloud sessions |
| **[CDP Connect](/developers/self-hosted/browser#cdp-connect-external-chrome)** (self-hosted) | You're running Skyvern locally and want to connect to an existing Chrome instance |
---
## Troubleshooting
<AccordionGroup>
<Accordion title="ngrok not found">
Install ngrok from [ngrok.com/download](https://ngrok.com/download) and authenticate it:
```bash
ngrok authtoken <your-token>
```
</Accordion>
<Accordion title="Chrome not found">
Use `--chrome-path` to specify the path to your Chrome executable:
```bash
# macOS
skyvern browser serve --chrome-path "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
# Linux
skyvern browser serve --chrome-path /usr/bin/google-chrome
# Windows
skyvern browser serve --chrome-path "C:\Program Files\Google\Chrome\Application\chrome.exe"
```
</Accordion>
<Accordion title="Port already in use">
Another process is using port 9222. Either stop that process or use a different port:
```bash
skyvern browser serve --port 8222
```
</Accordion>
<Accordion title="Tunnel connection drops">
ngrok free tier tunnels have connection limits. For production use, consider an ngrok paid plan or contact support@skyvern.com for alternative tunnel options.
</Accordion>
</AccordionGroup>
---
## Next steps
<CardGroup cols={2}>
<Card title="Browser Sessions" icon="window" href="/developers/optimization/browser-sessions">
Use cloud-managed browser sessions for multi-step tasks
</Card>
<Card title="Browser Profiles" icon="floppy-disk" href="/developers/optimization/browser-profiles">
Save and reuse authenticated browser state
</Card>
</CardGroup>
@@ -0,0 +1,301 @@
---
title: Cost Control
subtitle: Limit steps and optimize prompts to manage costs
description: Control Skyvern costs using max_steps limits, code generation for repeatable tasks, cheaper engine tiers, and prompt optimization techniques to reduce step count and credit usage.
slug: developers/optimization/cost-control
keywords:
- max_steps
- credits
- code generation
- engine tier
- prompt optimization
- step count
- budget
---
Skyvern Cloud uses a **credit-based billing model**. Each plan includes a monthly credit allowance that determines how many actions you can run.
| Plan | Price | Actions Included |
|------|-------|------------------|
| Free | $0 | ~170 |
| Hobby | $29 | ~1,200 |
| Pro | $149 | ~6,200 |
| Enterprise | Custom | Unlimited |
Use `max_steps` to limit steps per run and prevent runaway costs.
---
## Limit steps with max_steps
Set `max_steps` to cap the worst-case cost of any run. If a task gets stuck in a loop or hits repeated failures, `max_steps` stops it before it burns through your budget. The run terminates with `status: "timed_out"` when it hits the limit.
### For tasks
Pass `max_steps` in the request body.
<CodeGroup>
```python Python
from skyvern import Skyvern
client = Skyvern(api_key="YOUR_API_KEY")
result = await client.run_task(
prompt="Extract the top 3 products",
url="https://example.com/products",
max_steps=15,
wait_for_completion=True,
)
print(f"Steps taken: {result.step_count}")
```
```typescript TypeScript
import { Skyvern } from "@skyvern/client";
const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });
const result = await client.runTask({
body: {
prompt: "Extract the top 3 products",
url: "https://example.com/products",
max_steps: 15,
},
waitForCompletion: true,
});
console.log(`Steps taken: ${result.step_count}`);
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Extract the top 3 products",
"url": "https://example.com/products",
"max_steps": 15
}'
```
</CodeGroup>
### For workflows
Pass `max_steps_override` as a parameter (Python) or `x-max-steps-override` header (TypeScript/cURL). This limits total steps across all blocks.
<CodeGroup>
```python Python
from skyvern import Skyvern
client = Skyvern(api_key="YOUR_API_KEY")
result = await client.run_workflow(
workflow_id="wf_data_extraction",
max_steps_override=30,
wait_for_completion=True,
)
print(f"Steps taken: {result.step_count}")
```
```typescript TypeScript
import { Skyvern } from "@skyvern/client";
const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });
const result = await client.runWorkflow({
"x-max-steps-override": 30,
body: { workflow_id: "wf_data_extraction" },
waitForCompletion: true,
});
console.log(`Steps taken: ${result.step_count}`);
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "x-max-steps-override: 30" \
-H "Content-Type: application/json" \
-d '{"workflow_id": "wf_data_extraction"}'
```
</CodeGroup>
<Info>
If runs consistently time out, increase `max_steps` or simplify the task. If `step_count` is much lower than `max_steps`, reduce the limit.
</Info>
---
## Use code generation for repeatable tasks
On Skyvern Cloud, the default **Skyvern 2.0 with Code** engine records the actions the AI takes and generates reusable code from them. Subsequent runs execute the generated code instead of the AI agent, skipping LLM inference and screenshot analysis entirely. This makes them faster, deterministic, and significantly cheaper.
1. Run your task with the default engine. Skyvern generates code from the recorded actions.
2. Subsequent runs execute the cached code directly, no AI reasoning required.
3. If the code doesn't handle an edge case, adjust your prompt and re-run to regenerate. Skyvern also falls back to the AI agent automatically if the cached code fails.
You can control this with the `run_with` parameter. Set it to `"code"` to use cached code, or `"agent"` to force AI reasoning.
<CodeGroup>
```python Python
from skyvern import Skyvern
client = Skyvern(api_key="YOUR_API_KEY")
# First run: AI agent executes and generates code
result = await client.run_task(
prompt="Extract the top 3 products",
url="https://example.com/products",
wait_for_completion=True,
)
# Subsequent runs: execute cached code instead of AI
result = await client.run_task(
prompt="Extract the top 3 products",
url="https://example.com/products",
run_with="code",
wait_for_completion=True,
)
```
```typescript TypeScript
import { Skyvern } from "@skyvern/client";
const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });
// First run: AI agent executes and generates code
const result = await client.runTask({
body: {
prompt: "Extract the top 3 products",
url: "https://example.com/products",
},
waitForCompletion: true,
});
// Subsequent runs: execute cached code instead of AI
const codeResult = await client.runTask({
body: {
prompt: "Extract the top 3 products",
url: "https://example.com/products",
run_with: "code",
},
waitForCompletion: true,
});
```
```bash cURL
# First run: AI agent executes and generates code
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Extract the top 3 products",
"url": "https://example.com/products"
}'
# Subsequent runs: execute cached code instead of AI
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Extract the top 3 products",
"url": "https://example.com/products",
"run_with": "code"
}'
```
</CodeGroup>
<Tip>
Set `publish_workflow: true` to save the generated workflow so you can re-trigger it later or [schedule it on a recurring cron](/cloud/building-workflows/scheduling).
</Tip>
---
## Choose a cheaper engine
Not every task needs the most powerful engine. Use a lighter engine for simple, single-objective work.
| Engine | Cost | Best for |
|--------|------|----------|
| `skyvern-2.0` | Highest | Complex, multi-step tasks that require flexibility |
| `skyvern-1.0` | Lower | Single-objective tasks like form fills or single-page extraction |
<CodeGroup>
```python Python
from skyvern import Skyvern
client = Skyvern(api_key="YOUR_API_KEY")
result = await client.run_task(
prompt="Fill out the contact form",
url="https://example.com/contact",
engine="skyvern-1.0",
wait_for_completion=True,
)
```
```typescript TypeScript
import { Skyvern } from "@skyvern/client";
const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });
const result = await client.runTask({
body: {
prompt: "Fill out the contact form",
url: "https://example.com/contact",
engine: "skyvern-1.0",
},
waitForCompletion: true,
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/tasks" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Fill out the contact form",
"url": "https://example.com/contact",
"engine": "skyvern-1.0"
}'
```
</CodeGroup>
For self-hosted deployments, you can also swap the underlying LLM to a cheaper model (e.g., Gemini 2.5 Flash instead of a pro-tier model) via the `LLM_KEY` environment variable. See [LLM configuration](/developers/self-hosted/llm-configuration) for details.
---
## Write better prompts
Small prompt changes can cut step count significantly.
- **Be specific about the goal and completion criteria.** "Extract the price, title, and rating of the first 3 products" finishes faster than "look at the products page."
- **Avoid open-ended exploration.** Prompts like "find interesting data" or "look around" cause the agent to wander.
- **Use `data_extraction_schema`** to constrain what fields the AI extracts. This prevents it from spending steps parsing irrelevant content.
- **Provide `url`** to start on the correct page instead of making the agent search for it.
- **Use [browser profiles](/developers/optimization/browser-profiles)** to skip login steps on repeated runs.
---
## Monitor usage
- Check `step_count` in run responses to understand actual consumption per task.
- Use `get_run_timeline()` to inspect individual steps and identify waste (loops, unnecessary navigation, retries).
---
## Next steps
<CardGroup cols={2}>
<Card
title="Browser Sessions"
icon="browser"
href="/developers/optimization/browser-sessions"
>
Maintain live browser state between calls
</Card>
<Card
title="Browser Profiles"
icon="floppy-disk"
href="/developers/optimization/browser-profiles"
>
Save authenticated state for reuse across days
</Card>
</CardGroup>
+444
View File
@@ -0,0 +1,444 @@
---
title: Browser Configuration
subtitle: Configure browser modes, display settings, and external Chrome connections
description: Configure Skyvern's browser modes including headful, headless, local Chrome, and CDP connect. Set display resolution, viewport size, and connect to external Chrome instances for self-hosted deployments.
slug: developers/self-hosted/browser
keywords:
- headless
- headful
- CDP
- Chrome DevTools Protocol
- display resolution
- viewport
- external Chrome
- BROWSER_TYPE
---
Skyvern uses Playwright with Chromium to execute browser automations.
## Browser modes
The `BROWSER_TYPE` setting controls how Skyvern runs the browser.
- **[Headful](#headful-default)**: visible browser window (default)
- **[Headless](#headless)**: no display, runs in the background
- **[Use Your Own Chrome](#use-your-own-chrome)**: runs the installed Chrome app with your logged-in profile
- **[CDP Connect](#cdp-connect-external-chrome)**: connects to an already-running Chrome instance
### Headful (default)
```bash .env
BROWSER_TYPE=chromium-headful
```
The browser runs with a visible window. In Docker, this displays on a virtual framebuffer (Xvfb).
### Headless
```bash .env
BROWSER_TYPE=chromium-headless
```
The browser runs without any display.
<Note>
Some websites detect and block headless browsers. If you encounter issues with bot detection, try headful mode with a virtual display.
</Note>
### Use Your Own Chrome
```bash .env
BROWSER_TYPE=cdp-connect
CHROME_EXECUTABLE_PATH=/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
```
Skyvern launches the Chrome app installed on your machine and connects to it automatically. Your existing Chrome profile (cookies, saved logins, extensions) is copied over so automations run in a browser environment that matches your real one.
Useful for:
- Running automations with your saved logins and cookies
- Using your installed Chrome extensions
- Avoiding bot detection by using a real Chrome installation
### CDP Connect (External Chrome)
```bash .env
BROWSER_TYPE=cdp-connect
BROWSER_REMOTE_DEBUGGING_URL=http://host.docker.internal:9222/
BROWSER_CDP_CONNECT_TIMEOUT_MS=120000
```
Connect to an existing Chrome instance running with remote debugging enabled. Useful for:
- Using your existing browser profile with saved logins
- Debugging with Chrome DevTools
- Running automations on a browser with specific extensions
<Note>
Docker Compose self-host installs default `BROWSER_STREAMING_MODE` to `cdp`.
Existing installs that already set this variable in `.env` keep their value.
To opt out of CDP livestreaming, set `BROWSER_STREAMING_MODE=vnc` in `.env`.
</Note>
---
## Setting up Use Your Own Chrome
Set `CHROME_EXECUTABLE_PATH` to your Chrome installation path and Skyvern handles the rest. No need to manually start Chrome with debugging flags.
### Step 1: Find your Chrome path
<CodeGroup>
```bash macOS
/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
```
```powershell Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe"
```
```bash Linux
# Usually one of:
/usr/bin/google-chrome
/usr/bin/chromium
/usr/bin/chromium-browser
```
</CodeGroup>
### Step 2: Configure Skyvern
<CodeGroup>
```bash macOS .env
BROWSER_TYPE=cdp-connect
CHROME_EXECUTABLE_PATH=/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
```
```bash Windows .env
BROWSER_TYPE=cdp-connect
CHROME_EXECUTABLE_PATH="C:\Program Files\Google\Chrome\Application\chrome.exe"
```
```bash Linux .env
BROWSER_TYPE=cdp-connect
CHROME_EXECUTABLE_PATH=/usr/bin/google-chrome
```
</CodeGroup>
When Skyvern starts, it will:
1. Copy your Chrome profile to a working directory (`./tmp/user_data_dir`)
2. Launch Chrome with remote debugging on port 9222
3. Connect via CDP automatically
<Warning>
All existing Chrome windows must be closed before Skyvern can launch Chrome with remote debugging. If Chrome is already running, Skyvern will return an error.
</Warning>
<Note>
If port 9222 is already in use (e.g., from a previous session), Skyvern will connect to the existing instance instead of launching a new one.
</Note>
---
## Setting up CDP Connect
CDP (Chrome DevTools Protocol) lets Skyvern control an external Chrome browser instead of launching its own.
### Step 1: Enable Chrome remote debugging
For an already-running Chrome profile, prefer Chrome's built-in remote debugging
toggle:
1. Open `chrome://inspect/#remote-debugging` in Chrome.
2. Enable remote debugging for this browser instance.
3. Keep Chrome open while Skyvern connects.
This path keeps you on your existing Chrome profile. Skyvern will first try to
auto-discover a local debugging server, then let you paste a direct
`ws://.../devtools/browser/...` URL if Chrome exposes only a WebSocket endpoint.
#### Docker-reachable isolated profile fallback
When Skyvern runs in Docker, Chrome's built-in listener may bind to host
loopback only. If the container cannot reach it, start a separate Chrome profile
with a Docker-reachable CDP endpoint:
<CodeGroup>
```bash macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
--remote-debugging-port=9222 \
--remote-debugging-address=0.0.0.0 \
--user-data-dir="$HOME/chrome-cdp-profile" \
--no-first-run \
--no-default-browser-check
```
```powershell Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" `
--remote-debugging-port=9222 `
--remote-debugging-address=0.0.0.0 `
--user-data-dir="C:\chrome-cdp-profile" `
--no-first-run `
--no-default-browser-check
```
```bash Linux
google-chrome \
--remote-debugging-port=9222 \
--remote-debugging-address=0.0.0.0 \
--user-data-dir="$HOME/chrome-cdp-profile" \
--no-first-run \
--no-default-browser-check
```
</CodeGroup>
The `--user-data-dir` flag creates a separate profile for Skyvern, preserving
your main Chrome profile. Since [Chrome 136](https://developer.chrome.com/blog/remote-debugging-port),
`--remote-debugging-port` is ignored for the default Chrome data directory, so
only use these flags with a non-standard user data directory.
#### Windows Docker Desktop with `chrome://inspect`
Chrome's `chrome://inspect/#remote-debugging` toggle can bind its debugging
server to host loopback only. Docker Desktop cannot connect to that listener
directly through `host.docker.internal`. Skyvern includes a Windows helper that
bridges Docker to Chrome and writes the exact WebSocket URL from Chrome's
`DevToolsActivePort` file.
Open Chrome, go to `chrome://inspect/#remote-debugging`, enable remote
debugging, then run this from an Administrator PowerShell in the Skyvern repo:
```powershell Windows
.\scripts\windows_chrome_inspect_cdp.ps1 -UpdateEnv
docker compose up -d --force-recreate skyvern
```
The helper creates a Windows port proxy from `0.0.0.0:9223` to Chrome's
loopback debugging port, adds a matching firewall rule, reads the full browser
WebSocket path, and writes:
```bash .env
BROWSER_TYPE=cdp-connect
BROWSER_REMOTE_DEBUGGING_URL=ws://host.docker.internal:9223/devtools/browser/<id>
BROWSER_REMOTE_DEBUGGING_HOST_HEADER=127.0.0.1:<chrome-port>
BROWSER_STREAMING_MODE=cdp
BROWSER_CDP_CONNECT_TIMEOUT_MS=120000
```
Chrome may prompt you to allow the remote debugging connection the first time
Skyvern connects. Click **Allow** and retry the browser session if the first
attempt times out.
### Step 2: Configure Skyvern
```bash .env
BROWSER_TYPE=cdp-connect
BROWSER_REMOTE_DEBUGGING_URL=http://host.docker.internal:9222/
BROWSER_CDP_CONNECT_TIMEOUT_MS=120000
```
Use the URL that matches the remote debugging path you chose. For a classic
HTTP CDP endpoint, use the host and port. For a `chrome://inspect` flow that
only exposes a browser WebSocket, use the full direct
`ws://.../devtools/browser/<id>` URL.
When running Skyvern in Docker:
| Host OS | URL |
|---------|-----|
| macOS/Windows | `http://host.docker.internal:9222/` |
| Linux | `http://172.17.0.1:9222/` |
If Docker Desktop reaches Chrome but Chrome rejects the `host.docker.internal`
host name, Skyvern retries with the Docker host gateway IPv4 address. You can
also set `BROWSER_REMOTE_DEBUGGING_URL` directly to that IPv4 address.
If Windows Defender Firewall blocks the connection from Docker, allow inbound
TCP traffic on port 9222:
```powershell Windows
New-NetFirewallRule -DisplayName "Chrome Remote Debug 9222" -Direction Inbound -LocalPort 9222 -Protocol TCP -Action Allow
```
### Step 3: Verify connection
For a classic HTTP CDP endpoint, test that Chrome is listening on port 9222:
```bash
curl http://localhost:9222/json/version
```
```powershell Windows
Invoke-RestMethod http://127.0.0.1:9222/json/version
```
You should see Chrome's version information and a `webSocketDebuggerUrl`.
If you used the Windows `chrome://inspect` helper, the configured URL is a
direct `ws://.../devtools/browser/<id>` endpoint. In that mode, verify by
starting a Skyvern browser session after restarting the backend.
<Note>
If `/json/version` does not return Chrome version information from inside the
Skyvern container, verify Chrome is listening on `0.0.0.0:9222` or `::9222` and
that Windows Firewall allows inbound traffic on port 9222.
</Note>
<Warning>
CDP mode exposes Chrome to network access. The examples use
`--remote-debugging-address=0.0.0.0` so Docker can reach Chrome on the host.
Only use this in trusted environments. If Skyvern runs on the same host outside
Docker, bind to `127.0.0.1` instead.
</Warning>
---
## Display settings
Configure how the browser appears to websites. These settings affect geolocation detection and content rendering.
### Locale and timezone
```bash .env
# Optional, unset by default. Set to match your target region.
BROWSER_LOCALE=en-US
BROWSER_TIMEZONE=America/New_York
```
Set these to match your target audience or the expected user location. Mismatched locale/timezone can trigger bot detection on some sites.
Common combinations:
| Region | BROWSER_LOCALE | BROWSER_TIMEZONE |
|--------|----------------|------------------|
| US East | `en-US` | `America/New_York` |
| US West | `en-US` | `America/Los_Angeles` |
| UK | `en-GB` | `Europe/London` |
| Germany | `de-DE` | `Europe/Berlin` |
| Japan | `ja-JP` | `Asia/Tokyo` |
### Viewport size
```bash .env
BROWSER_WIDTH=1920
BROWSER_HEIGHT=1080
```
The default 1920x1080 works for most sites.
---
## Timeout settings
Control how long Skyvern waits for various browser operations.
```bash .env
# Time to wait for individual actions (clicks, typing)
BROWSER_ACTION_TIMEOUT_MS=5000
# Time to wait for screenshots to capture
BROWSER_SCREENSHOT_TIMEOUT_MS=20000
# Time to wait for page loads
BROWSER_LOADING_TIMEOUT_MS=60000
# Time to wait for DOM tree analysis
BROWSER_SCRAPING_BUILDING_ELEMENT_TREE_TIMEOUT_MS=60000
```
### When to adjust timeouts
| Symptom | Adjustment |
|---------|------------|
| Actions fail on slow sites | Increase `BROWSER_ACTION_TIMEOUT_MS` |
| Screenshots timeout on complex pages | Increase `BROWSER_SCREENSHOT_TIMEOUT_MS` |
| Page load timeouts | Increase `BROWSER_LOADING_TIMEOUT_MS` |
| DOM analysis fails on large pages | Increase `BROWSER_SCRAPING_BUILDING_ELEMENT_TREE_TIMEOUT_MS` |
---
## Advanced settings
### Browser logging
```bash .env
BROWSER_LOGS_ENABLED=true
```
When enabled, browser console logs are captured in artifacts. Useful for debugging JavaScript errors on target sites.
### Maximum pages
```bash .env
BROWSER_MAX_PAGES_NUMBER=10
```
Limits the number of browser tabs Skyvern can open simultaneously. Increase if your workflows navigate multiple pages in parallel; decrease to reduce memory usage.
### Chrome policies
```bash .env
BROWSER_POLICY_FILE=/etc/chromium/policies/managed/policies.json
```
Path to a Chrome policy file for enterprise configurations.
### Video recording path
```bash .env
VIDEO_PATH=./videos
```
Directory where browser session recordings are saved. Recordings are useful for debugging but consume disk space.
---
## Memory considerations
Browser instances are memory-intensive. These are approximate guidelines. Actual usage depends on page complexity and browser settings.
| Concurrent tasks | Recommended RAM |
|------------------|-----------------|
| 1-2 | 4GB |
| 3-5 | 8GB |
| 6-10 | 16GB |
| 10+ | 32GB+ |
If you experience out-of-memory errors:
1. Reduce `BROWSER_MAX_PAGES_NUMBER`
2. Use a smaller viewport (`BROWSER_WIDTH`, `BROWSER_HEIGHT`)
3. Run in headless mode (`BROWSER_TYPE=chromium-headless`)
4. Limit concurrent task execution
---
## Scaling browsers
The default Docker Compose setup runs one browser instance inside the Skyvern container. For higher concurrency:
### Option 1: Vertical scaling
Add more RAM to your server and increase `MAX_STEPS_PER_RUN` and `BROWSER_MAX_PAGES_NUMBER`.
### Option 2: Horizontal scaling
Deploy multiple Skyvern instances behind a load balancer. Each instance runs its own browser. See [Kubernetes Deployment](/developers/self-hosted/kubernetes) for orchestrated scaling.
### Option 3: External browser pool
Use a browser pool service like Browserless or your own Playwright grid, then connect via CDP:
```bash .env
BROWSER_TYPE=cdp-connect
BROWSER_REMOTE_DEBUGGING_URL=http://browserless:3000/
```
---
## Next steps
<CardGroup cols={2}>
<Card title="Proxy Setup" icon="shield" href="/developers/self-hosted/proxy">
Configure proxies to avoid bot detection
</Card>
<Card title="Storage Configuration" icon="hard-drive" href="/developers/self-hosted/storage">
Store recordings and artifacts in S3 or Azure Blob
</Card>
</CardGroup>
+404
View File
@@ -0,0 +1,404 @@
---
title: Docker Setup
subtitle: Get Skyvern running in 10 minutes with Docker Compose
description: Deploy Skyvern using Docker Compose with the API server, embedded browser, PostgreSQL database, and web UI. Includes LLM provider configuration and first-run setup.
slug: developers/self-hosted/docker
keywords:
- Docker Compose
- docker-compose.yml
- PostgreSQL
- environment variables
- first-run
- setup
- .env
---
This guide walks you through deploying Skyvern using Docker Compose. By the end, you'll have a working Skyvern instance with the API server, browser, database, and web UI running on your machine.
## Prerequisites
- Docker and Docker Compose v2 installed ([Get Docker](https://docs.docker.com/get-docker/)). All commands use `docker compose` (with a space). If you have an older installation, replace with `docker-compose`.
- 4GB+ RAM available
- An LLM API key (OpenAI, Anthropic, Azure, Gemini, or Bedrock)
## Quick start
### 1. Clone the repository
```bash
git clone https://github.com/Skyvern-AI/skyvern.git
cd skyvern
```
### 2. Configure environment variables
Copy the example environment file and configure your LLM provider:
```bash
cp .env.example .env
```
Open `.env` and set your LLM provider. Here's an example for OpenAI:
```bash .env
ENABLE_OPENAI=true
OPENAI_API_KEY=sk-your-api-key-here
LLM_KEY=OPENAI_GPT5_5
```
For other providers, see [LLM Configuration](/developers/self-hosted/llm-configuration).
### 3. Configure the frontend
Copy the frontend environment file:
```bash
cp skyvern-frontend/.env.example skyvern-frontend/.env
```
The default values work for local development. Docker Compose mounts the generated local credentials into the UI container, so you can leave `VITE_SKYVERN_API_KEY` as `YOUR_API_KEY` for the first startup.
### 4. Start the services
```bash
docker compose up -d
```
This pulls the images and starts three services:
- **postgres**: Database on port 5432 (internal only)
- **skyvern**: API server on port 8000
- **skyvern-ui**: Web interface on port 8080
First startup takes 1-2 minutes as it runs database migrations and creates your organization.
### 5. Get your API key
Wait for all services to be healthy before continuing:
```bash
docker compose ps
```
All three services should show `healthy` in the STATUS column. The `skyvern` container runs database migrations and generates credentials on first startup. This takes 1-2 minutes.
Once healthy, retrieve your API key:
```bash
cat .skyvern/credentials.toml
```
This file is auto-generated by Skyvern on first startup. The credentials inside are standard Skyvern API keys.
You'll see output like:
```toml
[skyvern]
configs = [
{env = "local", host = "http://skyvern:8000/api/v1", orgs = [{name="Skyvern", cred="eyJhbGciOiJIUzI1..."}]}
]
```
The `host` value uses the Docker-internal hostname `skyvern`. From your machine, use `http://localhost:8000` instead. You only need the `cred` value. This is your API key.
### 6. Verify the installation
Open [http://localhost:8080](http://localhost:8080) in your browser. You should see the Skyvern dashboard.
Test the API by listing workflows (should return an empty array on fresh install):
```bash
curl -s http://localhost:8000/v1/workflows \
-H "x-api-key: YOUR_API_KEY_HERE"
```
<Note>
The API accepts requests on both `/v1/` and `/api/v1/`. The frontend uses `/api/v1` for backward compatibility. New integrations should use `/v1/`.
</Note>
---
## Understanding the services
The Docker Compose file defines three services that work together:
```mermaid
flowchart LR
UI[skyvern-ui<br/>:8080] --> API[skyvern<br/>:8000]
API --> DB[(postgres<br/>:5432)]
API --> Browser[Browser<br/>internal]
API --> LLM[Your LLM<br/>Provider]
```
| Service | Image | Ports | Purpose |
|---------|-------|-------|---------|
| `postgres` | postgres:14-alpine | 5432 (internal) | Stores tasks, workflows, credentials, and run history |
| `skyvern` | public.ecr.aws/skyvern/skyvern | 8000, 9222 | API server + embedded browser |
| `skyvern-ui` | public.ecr.aws/skyvern/skyvern-ui | 8080, 9090 | Web dashboard and artifact server |
The `skyvern` container includes Playwright with Chromium. The browser runs inside the same container as the API server. No separate browser service is needed.
### Data volumes
Docker Compose mounts several directories for persistent storage:
| Local path | Container path | Contents |
|------------|----------------|----------|
| `./postgres-data` | `/var/lib/postgresql/data` | Database files |
| `./artifacts` | `/data/artifacts` | Extracted data, screenshots |
| `./videos` | `/data/videos` | Browser session recordings |
| `./har` | `/data/har` | HTTP Archive files for debugging |
| `./log` | `/data/log` | Application logs |
| `./.skyvern` | `/app/.skyvern` | Generated API credentials |
---
## Environment variables reference
The `.env` file controls the Skyvern server. Here are the most important variables grouped by purpose.
### Environment files
`docker-compose.yml` uses TWO sources for service environment:
1. **Inline `environment:` block** — compose-network values that depend on the docker network topology. Examples: `DATABASE_STRING=postgresql+psycopg://skyvern:skyvern@postgres:5432/skyvern` (the `postgres` hostname only resolves inside the compose network), `BROWSER_TYPE`, `BROWSER_STREAMING_MODE`, `ENABLE_CODE_BLOCK`.
2. **`env_file: .env`** — user secrets (LLM API keys, etc.).
**Do not move `DATABASE_STRING` from compose into `.env`.** The `.env.example` shipped with the repo uses a `localhost` host that points at the backend container itself when used inside compose — moving that value into `.env` will break the database connection.
If you have an existing `.env` from a pre-1.0.32 `skyvern quickstart` run, it may contain a leftover `DATABASE_STRING=postgresql+psycopg://skyvern@localhost/skyvern` line. Remove it:
```bash
sed -i.bak '/^DATABASE_STRING.*localhost/d' .env
```
### LLM Configuration
Configure at least one LLM provider. See [LLM Configuration](/developers/self-hosted/llm-configuration) for all providers.
```bash
# OpenAI
ENABLE_OPENAI=true
OPENAI_API_KEY=sk-...
LLM_KEY=OPENAI_GPT5_5
# Or Anthropic
ENABLE_ANTHROPIC=true
ANTHROPIC_API_KEY=sk-ant-...
LLM_KEY=ANTHROPIC_CLAUDE4.7_OPUS
```
### Browser settings
```bash
# Browser mode: chromium-headful (visible) or chromium-headless (no display)
BROWSER_TYPE=chromium-headful
# Browser livestreaming mode: cdp (default local screencast) or vnc
BROWSER_STREAMING_MODE=cdp
# Timeout for individual browser actions (milliseconds)
BROWSER_ACTION_TIMEOUT_MS=5000
# Where to save recordings
VIDEO_PATH=./videos
```
### Task execution
```bash
# Maximum steps before a task times out
MAX_STEPS_PER_RUN=10
# Server port
PORT=8000
# Log verbosity: DEBUG, INFO, WARNING, ERROR
LOG_LEVEL=INFO
```
### Database
The database connection is set in `docker-compose.yml`, not `.env`:
```yaml
environment:
- DATABASE_STRING=postgresql+psycopg://skyvern:skyvern@postgres:5432/skyvern
```
To use an external database, update this connection string and remove the `postgres` service.
---
## Common operations
### View logs
```bash
# All services
docker compose logs -f
# Specific service
docker compose logs -f skyvern
```
### Restart after configuration changes
```bash
docker compose restart skyvern
```
### Stop all services
```bash
docker compose down
```
### Update to latest version
```bash
docker compose pull
docker compose up -d
```
### Reset everything (including database)
<Warning>
This deletes all data including task history, credentials, and recordings.
</Warning>
```bash
docker compose down -v
rm -rf postgres-data artifacts videos har log .skyvern
docker compose up -d
```
---
## Exposing to the network
By default, Skyvern only accepts connections from localhost. To expose it on your network:
### Option 1: Bind to all interfaces
Edit `docker-compose.yml` to change the port bindings:
```yaml
services:
skyvern:
ports:
- "0.0.0.0:8000:8000" # Accept connections from any IP
```
### Option 2: Use a reverse proxy
For production deployments, put Skyvern behind nginx or Traefik:
```
your-domain.com → nginx → localhost:8080 (UI)
api.your-domain.com → nginx → localhost:8000 (API)
```
Update the frontend environment to use your domain:
```bash skyvern-frontend/.env
VITE_API_BASE_URL=https://api.your-domain.com/api/v1
VITE_WSS_BASE_URL=wss://api.your-domain.com/api/v1
VITE_ARTIFACT_API_BASE_URL=https://artifacts.your-domain.com
```
<Warning>
If exposing Skyvern to the internet, add authentication at the reverse proxy layer or use a VPN.
</Warning>
---
## Troubleshooting
<Accordion title="Container exits immediately">
Check the logs for the failing service:
```bash
docker compose logs skyvern
```
Common causes:
- Missing or invalid LLM API key: look for LLM-related errors in logs
- Database connection failed: check if `postgres` service is healthy with `docker compose ps`
</Accordion>
<Accordion title='API returns "Invalid credentials" (403)'>
The API key is missing, malformed, or doesn't match the organization. Verify:
1. The `x-api-key` header is included in your request
2. The key matches exactly what's in `.skyvern/credentials.toml`
3. No extra whitespace or newlines in the key
```bash
# Correct format
curl -H "x-api-key: eyJhbGciOiJIUzI1..." http://localhost:8000/v1/workflows
```
</Accordion>
<Accordion title='API returns "Could not validate credentials" (403)'>
The API key format is invalid (JWT decode failed). This usually means:
- The key was truncated or corrupted during copy-paste
- You're using an API key from a different Skyvern installation
Regenerate credentials by resetting the installation:
```bash
rm -rf .skyvern
docker compose restart skyvern
cat .skyvern/credentials.toml # Get new key
```
</Accordion>
<Accordion title="UI shows blank page or connection errors">
Check that `skyvern-frontend/.env` has the correct values:
```bash
VITE_API_BASE_URL=http://localhost:8000/api/v1
VITE_WSS_BASE_URL=ws://localhost:8000/api/v1
VITE_SKYVERN_API_KEY=<your-key-from-credentials.toml>
```
After updating, restart the UI:
```bash
docker compose restart skyvern-ui
```
</Accordion>
<Accordion title='Task fails with "Unknown browser type"'>
The `BROWSER_TYPE` environment variable has an invalid value. Valid options:
- `chromium-headful`: Browser with visible window (default)
- `chromium-headless`: No visible window
- `cdp-connect`: Connect to external Chrome
</Accordion>
<Accordion title='Task fails with "Context window exceeded"'>
The page content is too large for the LLM. Try:
- Simplifying your prompt
- Starting from a more specific URL
- Using a model with a larger context window
</Accordion>
---
## Next steps
<CardGroup cols={2}>
<Card title="LLM Configuration" icon="microchip" href="/developers/self-hosted/llm-configuration">
Configure OpenAI, Anthropic, Azure, Ollama, and other providers
</Card>
<Card title="Browser Configuration" icon="window" href="/developers/self-hosted/browser">
Customize browser settings, locales, and connect to external Chrome
</Card>
<Card title="Storage Configuration" icon="hard-drive" href="/developers/self-hosted/storage">
Store artifacts in S3 or Azure Blob instead of local disk
</Card>
<Card title="Proxy Setup" icon="shield" href="/developers/self-hosted/proxy">
Configure proxies to avoid bot detection
</Card>
</CardGroup>
+451
View File
@@ -0,0 +1,451 @@
---
title: Kubernetes Deployment
subtitle: Deploy Skyvern at scale with Kubernetes manifests
description: Deploy Skyvern on Kubernetes for production environments with horizontal scaling and high availability. Includes manifests for the API server, frontend, PostgreSQL, and ingress configuration.
slug: developers/self-hosted/kubernetes
keywords:
- Kubernetes
- Helm
- manifests
- horizontal scaling
- high availability
- ingress
- PostgreSQL
- production
---
This guide walks through deploying Skyvern on Kubernetes for production environments. Use this when you need horizontal scaling, high availability, or integration with existing Kubernetes infrastructure.
<Warning>
Do not expose this deployment to the public internet without adding authentication at the ingress layer.
</Warning>
## Prerequisites
- A running Kubernetes cluster (1.19+)
- `kubectl` configured to access your cluster
- An ingress controller (the manifests use Traefik, but any controller works)
- An LLM API key (OpenAI, Anthropic, Azure, etc.)
## Architecture overview
The Kubernetes deployment creates three services:
```mermaid
flowchart LR
subgraph Kubernetes Cluster
Ingress[Ingress] --> FE[Frontend<br/>:8080]
Ingress --> BE[Backend<br/>:8000]
Ingress --> Art[Artifacts<br/>:9090]
BE --> DB[(PostgreSQL<br/>:5432)]
BE --> Browser[Browser<br/>embedded]
FE --> Art
end
BE --> LLM[LLM Provider]
```
| Component | Service | Purpose |
|-----------|---------|---------|
| Backend | `skyvern-backend` | API server + embedded browser |
| Frontend | `skyvern-frontend` | Web UI + artifact server |
| PostgreSQL | `postgres` | Database for tasks, workflows, credentials |
---
## Quick start
### 1. Clone the repository
```bash
git clone https://github.com/Skyvern-AI/skyvern.git
cd skyvern/kubernetes-deployment
```
### 2. Configure backend secrets
Edit `backend/backend-secrets.yaml` with your LLM provider credentials:
```yaml backend/backend-secrets.yaml
apiVersion: v1
kind: Secret
metadata:
name: skyvern-backend-env
namespace: skyvern
type: Opaque
stringData:
ENV: local
# LLM Configuration - set your provider
ENABLE_OPENAI: "true"
OPENAI_API_KEY: "sk-your-api-key-here"
LLM_KEY: "OPENAI_GPT5_5"
# Database - points to the PostgreSQL service
DATABASE_STRING: "postgresql+psycopg://skyvern:skyvern@postgres/skyvern"
# Browser settings
BROWSER_TYPE: "chromium-headless"
BROWSER_ACTION_TIMEOUT_MS: "5000"
MAX_STEPS_PER_RUN: "10"
# Server
PORT: "8000"
LOG_LEVEL: "INFO"
```
For other LLM providers, see [LLM Configuration](/developers/self-hosted/llm-configuration).
### 3. Configure frontend secrets
Edit `frontend/frontend-secrets.yaml`:
```yaml frontend/frontend-secrets.yaml
apiVersion: v1
kind: Secret
metadata:
name: skyvern-frontend-env
namespace: skyvern
type: Opaque
stringData:
VITE_API_BASE_URL: "http://skyvern.example.com/api/v1"
VITE_WSS_BASE_URL: "ws://skyvern.example.com/api/v1"
VITE_ARTIFACT_API_BASE_URL: "http://skyvern.example.com/artifacts"
VITE_SKYVERN_API_KEY: "" # Leave empty for initial deploy
```
Replace `skyvern.example.com` with your actual domain.
### 4. Configure ingress
Edit `ingress.yaml` with your domain and TLS settings:
```yaml ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: skyvern-ingress
namespace: skyvern
annotations:
# Adjust for your ingress controller
traefik.ingress.kubernetes.io/router.entrypoints: websecure
spec:
ingressClassName: traefik # Change to nginx, kong, etc.
rules:
- host: skyvern.example.com # Your domain
http:
paths:
- path: /api
pathType: Prefix
backend:
service:
name: skyvern-backend
port:
number: 8000
- path: /artifacts
pathType: Prefix
backend:
service:
name: skyvern-frontend
port:
number: 9090
- path: /
pathType: Prefix
backend:
service:
name: skyvern-frontend
port:
number: 8080
```
### 5. Deploy
Run the deployment script:
```bash
chmod +x k8s-deploy.sh
./k8s-deploy.sh
```
This applies manifests in order:
1. Namespace
2. PostgreSQL (secrets, storage, deployment, service)
3. Backend (secrets, deployment, service)
4. Frontend (secrets, deployment, service)
5. Ingress
### 6. Verify deployment
Check that all pods are running:
```bash
kubectl get pods -n skyvern
```
Expected output:
```
NAME READY STATUS RESTARTS AGE
postgres-xxx 1/1 Running 0 2m
skyvern-backend-xxx 1/1 Running 0 1m
skyvern-frontend-xxx 1/1 Running 0 30s
```
The backend pod takes 1-2 minutes to become ready as it runs database migrations.
### 7. Get your API key
Wait for the backend pod to show `1/1` in the `READY` column of `kubectl get pods -n skyvern` before running this command. The API key file is generated during startup and won't exist until the pod is ready.
```bash
kubectl exec -n skyvern deployment/skyvern-backend -- cat /app/.skyvern/credentials.toml
```
Copy the `cred` value and update `frontend/frontend-secrets.yaml`:
```yaml
VITE_SKYVERN_API_KEY: "eyJhbGciOiJIUzI1..."
```
Reapply the frontend secrets and restart:
```bash
kubectl apply -f frontend/frontend-secrets.yaml -n skyvern
kubectl rollout restart deployment/skyvern-frontend -n skyvern
```
### 8. Access the UI
Navigate to your configured domain (e.g., `https://skyvern.example.com`). You should see the Skyvern dashboard.
---
## Manifest structure
```
kubernetes-deployment/
├── namespace.yaml # Creates 'skyvern' namespace
├── k8s-deploy.sh # Deployment script
├── ingress.yaml # Ingress configuration
├── backend/
│ ├── backend-secrets.yaml # Environment variables
│ ├── backend-deployment.yaml # Pod spec
│ └── backend-service.yaml # ClusterIP service
├── frontend/
│ ├── frontend-secrets.yaml # Environment variables
│ ├── frontend-deployment.yaml # Pod spec
│ └── frontend-service.yaml # ClusterIP service
└── postgres/
├── postgres-secrets.yaml # Database credentials
├── postgres-storage.yaml # PersistentVolumeClaim
├── postgres-deployment.yaml # Pod spec
└── postgres-service.yaml # ClusterIP service
```
---
## Storage configuration
By default, the manifests use `hostPath` volumes. This works for single-node clusters but isn't suitable for multi-node production deployments.
### Using PersistentVolumeClaims
For production, replace `hostPath` with PVCs. Edit `backend/backend-deployment.yaml`:
```yaml
volumes:
- name: artifacts
persistentVolumeClaim:
claimName: skyvern-artifacts-pvc
- name: videos
persistentVolumeClaim:
claimName: skyvern-videos-pvc
```
Create the PVCs:
```yaml skyvern-storage.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: skyvern-artifacts-pvc
namespace: skyvern
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 50Gi
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: skyvern-videos-pvc
namespace: skyvern
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 100Gi
```
### Using S3 or Azure Blob
For cloud storage, configure the backend environment variables instead of mounting volumes. See [Storage Configuration](/developers/self-hosted/storage).
---
## Scaling
### Horizontal scaling
To run multiple backend instances, increase the replica count:
```yaml backend/backend-deployment.yaml
spec:
replicas: 3 # Run 3 backend pods
```
Each pod runs its own browser instance. Tasks are distributed across pods.
<Note>
When scaling horizontally, ensure your storage backend supports concurrent access (S3, Azure Blob, or ReadWriteMany PVCs). Local storage with ReadWriteOnce PVCs won't work across multiple pods.
</Note>
### Resource limits
Add resource limits to prevent pods from consuming excessive resources:
```yaml
containers:
- name: skyvern-backend
resources:
requests:
memory: "2Gi"
cpu: "500m"
limits:
memory: "4Gi"
cpu: "2000m"
```
Browser instances need significant memory. Start with 2GB minimum per pod.
---
## TLS configuration
To enable HTTPS, uncomment the TLS section in `ingress.yaml`:
```yaml
spec:
tls:
- hosts:
- skyvern.example.com
secretName: skyvern-tls-secret
```
Create the TLS secret:
```bash
kubectl create secret tls skyvern-tls-secret \
--cert=path/to/tls.crt \
--key=path/to/tls.key \
-n skyvern
```
Or use cert-manager for automatic certificate management.
Update frontend secrets to use `https` and `wss`:
```yaml
VITE_API_BASE_URL: "https://skyvern.example.com/api/v1"
VITE_WSS_BASE_URL: "wss://skyvern.example.com/api/v1"
```
---
## Using an external database
For production, consider using a managed PostgreSQL service (RDS, Cloud SQL, Azure Database).
1. Remove the `postgres/` manifests from the deployment
2. Update `backend/backend-secrets.yaml`:
```yaml
DATABASE_STRING: "postgresql+psycopg://user:password@your-db-host:5432/skyvern"
```
---
## Troubleshooting
### Pods stuck in Pending
Check for resource constraints:
```bash
kubectl describe pod -n skyvern <pod-name>
```
Common causes:
- Insufficient node resources
- PersistentVolume not available
- Image pull errors
### Backend crashes on startup
Check the logs:
```bash
kubectl logs -n skyvern deployment/skyvern-backend
```
Common causes:
- Invalid LLM API key
- Database connection failed
- Missing environment variables
### Frontend shows "Unauthorized"
The API key in frontend secrets doesn't match the generated key. Re-copy it from the backend pod.
### Ingress not routing correctly
Verify your ingress controller is running and the ingress resource is configured:
```bash
kubectl get ingress -n skyvern
kubectl describe ingress skyvern-ingress -n skyvern
```
---
## Cleanup
To remove the entire deployment:
```bash
kubectl delete namespace skyvern
```
This removes all resources in the `skyvern` namespace.
To clean up host storage (if using hostPath):
```bash
rm -rf /data/artifacts /data/videos /data/har /data/log /app/.skyvern
```
---
## Next steps
<CardGroup cols={2}>
<Card title="Storage Configuration" icon="hard-drive" href="/developers/self-hosted/storage">
Configure S3 or Azure Blob for artifact storage
</Card>
<Card title="LLM Configuration" icon="microchip" href="/developers/self-hosted/llm-configuration">
Configure additional LLM providers
</Card>
</CardGroup>
@@ -0,0 +1,616 @@
---
title: LLM Configuration
subtitle: Connect your preferred language model provider
description: Configure LLM providers for self-hosted Skyvern including OpenAI, Anthropic, Azure OpenAI, Google Gemini, AWS Bedrock, Ollama, and OpenAI-compatible endpoints via LiteLLM.
slug: developers/self-hosted/llm-configuration
keywords:
- OpenAI
- Anthropic
- Azure OpenAI
- Google Gemini
- AWS Bedrock
- Ollama
- LiteLLM
- LLM_KEY
- SECONDARY_LLM_KEY
---
Skyvern uses LLMs to analyze screenshots and decide what actions to take. You'll need to configure at least one LLM provider before running tasks.
## How Skyvern uses LLMs
Skyvern makes multiple LLM calls per task step:
1. **Screenshot analysis**: Identify interactive elements on the page
2. **Action planning**: Decide what to click, type, or extract
3. **Result extraction**: Parse data from the page into structured output
A task that runs for 10 steps makes roughly 30+ LLM calls. Choose your provider and model tier with this in mind.
For most deployments, configure a single provider using `LLM_KEY`. Skyvern also supports a `SECONDARY_LLM_KEY` for lighter tasks to reduce costs.
---
## Quick Start Recommendations
**Best models for production (2026):**
| Provider | Primary Model | Secondary Model | Notes |
|----------|--------------|-----------------|-------|
| **Anthropic** | `ANTHROPIC_CLAUDE4.7_OPUS` | `ANTHROPIC_CLAUDE4.6_SONNET` | Most capable |
| **OpenAI** | `OPENAI_GPT5_5` | `OPENAI_GPT5_4` | Latest |
| **Google** | `GEMINI_3_PRO` | `GEMINI_3.0_FLASH` | Latest |
| **AWS Bedrock** | `BEDROCK_ANTHROPIC_CLAUDE4.7_OPUS_INFERENCE_PROFILE` | `BEDROCK_ANTHROPIC_CLAUDE4.6_SONNET_INFERENCE_PROFILE` | Latest Claude |
---
## OpenAI
The most common choice. Requires an API key from [platform.openai.com](https://platform.openai.com/).
```bash .env
ENABLE_OPENAI=true
OPENAI_API_KEY=sk-...
LLM_KEY=OPENAI_GPT5_5
```
### Available models
| LLM_KEY | Notes |
|---------|-------|
| **GPT-5.5** | |
| `OPENAI_GPT5_5` | Latest flagship, recommended for complex tasks |
| **GPT-5 Series** | |
| `OPENAI_GPT5_4` | |
| `OPENAI_GPT5` | |
| `OPENAI_GPT5_MINI` | |
| `OPENAI_GPT5_MINI_FLEX` | Flex service tier, 15min timeout |
| `OPENAI_GPT5_NANO` | |
| `OPENAI_GPT5_1` | |
| `OPENAI_GPT5_2` | |
| **GPT-4 Series** | |
| `OPENAI_GPT4O` | |
| `OPENAI_GPT4O_MINI` | |
| `OPENAI_GPT4_1` | |
| `OPENAI_GPT4_1_MINI` | |
| `OPENAI_GPT4_1_NANO` | |
| `OPENAI_GPT4_5` | |
| `OPENAI_GPT4_TURBO` | Legacy |
| `OPENAI_GPT4V` | Legacy alias |
| **O-Series (Reasoning)** | |
| `OPENAI_O4_MINI` | Vision support |
| `OPENAI_O3` | Vision support |
| `OPENAI_O3_MINI` | No vision |
### Optional settings
```bash .env
# Use a custom API endpoint (for proxies or compatible services)
OPENAI_API_BASE=https://your-proxy.com/v1
# Specify organization ID
OPENAI_ORGANIZATION=org-...
```
---
## Anthropic
Claude models from [anthropic.com](https://www.anthropic.com/).
```bash .env
ENABLE_ANTHROPIC=true
ANTHROPIC_API_KEY=sk-ant-...
LLM_KEY=ANTHROPIC_CLAUDE4.7_OPUS
```
### Available models
| LLM_KEY | Notes |
|---------|-------|
| **Claude 4.7** | |
| `ANTHROPIC_CLAUDE4.7_OPUS` | Latest, most capable |
| **Claude 4.6** | |
| `ANTHROPIC_CLAUDE4.6_OPUS` | |
| `ANTHROPIC_CLAUDE4.6_SONNET` | Recommended for secondary use |
| **Claude 4.5** | |
| `ANTHROPIC_CLAUDE4.5_OPUS` | |
| `ANTHROPIC_CLAUDE4.5_SONNET` | |
| `ANTHROPIC_CLAUDE4.5_HAIKU` | Fastest |
| **Claude 4** | |
| `ANTHROPIC_CLAUDE4_OPUS` | |
| `ANTHROPIC_CLAUDE4_SONNET` | |
| **Claude 3.7** | |
| `ANTHROPIC_CLAUDE3.7_SONNET` | |
| **Claude 3.5** | |
| `ANTHROPIC_CLAUDE3.5_SONNET` | |
| `ANTHROPIC_CLAUDE3.5_HAIKU` | |
| **Claude 3 (Legacy)** | |
| `ANTHROPIC_CLAUDE3_OPUS` | |
| `ANTHROPIC_CLAUDE3_SONNET` | |
| `ANTHROPIC_CLAUDE3_HAIKU` | |
---
## Azure OpenAI
Microsoft-hosted OpenAI models. Requires an Azure subscription with OpenAI service provisioned.
```bash .env
ENABLE_AZURE=true
LLM_KEY=AZURE_OPENAI
AZURE_DEPLOYMENT=your-deployment-name
AZURE_API_KEY=your-azure-api-key
AZURE_API_BASE=https://your-resource.openai.azure.com/
AZURE_API_VERSION=2024-08-01-preview
```
### Setup steps
1. Create an Azure OpenAI resource in the [Azure Portal](https://portal.azure.com)
2. Open the Azure AI Foundry portal from your resource's overview page
3. Go to **Shared Resources** → **Deployments**
4. Click **Deploy Model** → **Deploy Base Model** → select GPT-4o or GPT-4
5. Note the **Deployment Name**. Use this for `AZURE_DEPLOYMENT`
6. Copy your API key and endpoint from the Azure Portal
<Note>
The `AZURE_DEPLOYMENT` is the name you chose when deploying the model, not the model name itself.
</Note>
---
## Google Gemini
Skyvern supports Gemini through two paths: the **Gemini API** (simpler, uses an API key) and **Vertex AI** (enterprise, uses a GCP service account).
### Gemini API
The quickest way to use Gemini. Get an API key from [Google AI Studio](https://aistudio.google.com/).
```bash .env
ENABLE_GEMINI=true
GEMINI_API_KEY=your-gemini-api-key
LLM_KEY=GEMINI_2.5_PRO
```
#### Available Gemini API models
| LLM_KEY | Notes |
|---------|-------|
| **Gemini 3** | |
| `GEMINI_3_PRO` | Recommended for primary use |
| `GEMINI_3.0_FLASH` | Recommended for secondary use |
| `GEMINI_3.1_FLASH_LITE` | Fastest, most cost-efficient |
| **Gemini 2.5** | |
| `GEMINI_2.5_PRO` | |
| `GEMINI_2.5_PRO_PREVIEW` | |
| `GEMINI_2.5_PRO_EXP_03_25` | Experimental |
| `GEMINI_2.5_FLASH` | |
| `GEMINI_2.5_FLASH_PREVIEW` | |
| **Gemini 2.0** | |
| `GEMINI_FLASH_2_0` | |
| `GEMINI_FLASH_2_0_LITE` | |
| **Gemini 1.5 Legacy** | |
| `GEMINI_PRO` | |
| `GEMINI_FLASH` | |
### Vertex AI
For enterprise deployments through [Vertex AI](https://cloud.google.com/vertex-ai). Requires a GCP project with Vertex AI enabled.
```bash .env
ENABLE_VERTEX_AI=true
LLM_KEY=VERTEX_GEMINI_3_PRO
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
GCP_PROJECT_ID=your-gcp-project-id
VERTEX_LOCATION=us-central1
```
<Note>
If you're migrating from an older Skyvern version, `VERTEX_LOCATION` replaces the previous `GCP_REGION` variable. Update your `.env` accordingly.
</Note>
**Vertex AI setup steps:**
1. Create a [GCP project](https://console.cloud.google.com/) with billing enabled
2. Enable the **Vertex AI API** in your project
3. Create a service account with the **Vertex AI User** role
4. Download the service account JSON key file
5. Set `GOOGLE_APPLICATION_CREDENTIALS` to the path of that file
<Note>
For global endpoint access, set `VERTEX_LOCATION=global` and ensure `VERTEX_PROJECT_ID` is set. Not all models support the global endpoint.
</Note>
#### Available Vertex AI models
| LLM_KEY | Notes |
|---------|-------|
| **Gemini 3** | |
| `VERTEX_GEMINI_3_PRO` | Recommended for primary use |
| `VERTEX_GEMINI_3.0_FLASH` | Recommended for secondary use |
| `VERTEX_GEMINI_3.1_FLASH_LITE` | Fastest, most cost-efficient |
| **Gemini 2.5** | |
| `VERTEX_GEMINI_2.5_PRO` | |
| `VERTEX_GEMINI_2.5_PRO_PREVIEW` | |
| `VERTEX_GEMINI_2.5_FLASH` | |
| `VERTEX_GEMINI_2.5_FLASH_LITE` | |
| `VERTEX_GEMINI_2.5_FLASH_PREVIEW` | |
| **Gemini 2.0** | |
| `VERTEX_GEMINI_FLASH_2_0` | |
| **Gemini 1.5 Legacy** | |
| `VERTEX_GEMINI_PRO` | |
| `VERTEX_GEMINI_FLASH` | |
---
## Amazon Bedrock
Run Anthropic Claude through your AWS account.
```bash .env
ENABLE_BEDROCK=true
LLM_KEY=BEDROCK_ANTHROPIC_CLAUDE4.7_OPUS_INFERENCE_PROFILE
AWS_REGION=us-west-2
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
```
### Setup steps
1. Create an IAM user with `AmazonBedrockFullAccess` policy
2. Generate access keys for the IAM user
3. In the [Bedrock console](https://console.aws.amazon.com/bedrock/), go to **Model Access**
4. Enable access to Claude Opus 4.7
### Available models
| LLM_KEY | Notes |
|---------|-------|
| **Amazon Nova (AWS Native)** | |
| `BEDROCK_AMAZON_NOVA_PRO` | |
| `BEDROCK_AMAZON_NOVA_LITE` | |
| **Claude 4.7** | |
| `BEDROCK_ANTHROPIC_CLAUDE4.7_OPUS_INFERENCE_PROFILE` | Cross-region, latest |
| **Claude 4.6** | |
| `BEDROCK_ANTHROPIC_CLAUDE4.6_OPUS_INFERENCE_PROFILE` | Cross-region |
| `BEDROCK_ANTHROPIC_CLAUDE4.6_SONNET_INFERENCE_PROFILE` | Cross-region |
| **Claude 4.5** | |
| `BEDROCK_ANTHROPIC_CLAUDE4.5_OPUS_INFERENCE_PROFILE` | Cross-region |
| `BEDROCK_ANTHROPIC_CLAUDE4.5_SONNET_INFERENCE_PROFILE` | Cross-region |
| **Claude 4** | |
| `BEDROCK_ANTHROPIC_CLAUDE4_OPUS_INFERENCE_PROFILE` | Cross-region |
| `BEDROCK_ANTHROPIC_CLAUDE4_SONNET_INFERENCE_PROFILE` | Cross-region |
| **Claude 3.7** | |
| `BEDROCK_ANTHROPIC_CLAUDE3.7_SONNET_INFERENCE_PROFILE` | Cross-region |
| **Claude 3.5** | |
| `BEDROCK_ANTHROPIC_CLAUDE3.5_SONNET` | v2 |
| `BEDROCK_ANTHROPIC_CLAUDE3.5_SONNET_V1` | |
| `BEDROCK_ANTHROPIC_CLAUDE3.5_SONNET_INFERENCE_PROFILE` | Cross-region |
| `BEDROCK_ANTHROPIC_CLAUDE3.5_HAIKU` | |
| **Claude 3 (Legacy)** | |
| `BEDROCK_ANTHROPIC_CLAUDE3_OPUS` | |
| `BEDROCK_ANTHROPIC_CLAUDE3_SONNET` | |
| `BEDROCK_ANTHROPIC_CLAUDE3_HAIKU` | |
<Note>
Bedrock inference profile keys (`*_INFERENCE_PROFILE`) use cross-region inference and require `AWS_REGION` only. No access keys needed if running on an IAM-authenticated instance.
</Note>
---
## MiniMax
[MiniMax](https://www.minimax.io/) models with vision support.
```bash .env
ENABLE_MINIMAX=true
MINIMAX_API_KEY=your-minimax-api-key
LLM_KEY=MINIMAX_M2_5
```
### Available models
| LLM_KEY | Notes |
|---------|-------|
| `MINIMAX_M2_5` | |
| `MINIMAX_M2_5_HIGHSPEED` | Faster variant |
### Optional settings
```bash .env
# Use a custom API endpoint
MINIMAX_API_BASE=https://api.minimax.io/v1
```
---
## VolcEngine (ByteDance Doubao)
[VolcEngine](https://www.volcengine.com/) provides access to ByteDance's Doubao models with vision support.
```bash .env
ENABLE_VOLCENGINE=true
VOLCENGINE_API_KEY=your-volcengine-api-key
LLM_KEY=VOLCENGINE_DOUBAO_SEED_1_6
```
### Available models
| LLM_KEY | Notes |
|---------|-------|
| `VOLCENGINE_DOUBAO_SEED_1_6` | Recommended for general use |
| `VOLCENGINE_DOUBAO_SEED_1_6_FLASH` | Faster variant |
| `VOLCENGINE_DOUBAO_1_5_THINKING_VISION_PRO` | Reasoning model |
### Optional settings
```bash .env
# Use a custom API endpoint
VOLCENGINE_API_BASE=https://ark.cn-beijing.volces.com/api/v3
```
---
## Novita
[Novita AI](https://novita.ai/) provides access to DeepSeek, Llama, and other open-source models.
```bash .env
ENABLE_NOVITA=true
NOVITA_API_KEY=your-novita-api-key
LLM_KEY=NOVITA_LLAMA_3_2_11B_VISION
```
### Available models
| LLM_KEY | Notes |
|---------|-------|
| **DeepSeek** | |
| `NOVITA_DEEPSEEK_R1` | Reasoning model |
| `NOVITA_DEEPSEEK_V3` | |
| **Llama 3.3** | |
| `NOVITA_LLAMA_3_3_70B` | |
| **Llama 3.2** | |
| `NOVITA_LLAMA_3_2_11B_VISION` | Vision support |
| `NOVITA_LLAMA_3_2_3B` | |
| `NOVITA_LLAMA_3_2_1B` | |
| **Llama 3.1** | |
| `NOVITA_LLAMA_3_1_405B` | |
| `NOVITA_LLAMA_3_1_70B` | |
| `NOVITA_LLAMA_3_1_8B` | |
| **Llama 3** | |
| `NOVITA_LLAMA_3_70B` | |
| `NOVITA_LLAMA_3_8B` | |
---
## Moonshot
[Moonshot AI](https://www.moonshot.cn/) provides the Kimi series models with long context support.
```bash .env
ENABLE_MOONSHOT=true
MOONSHOT_API_KEY=your-moonshot-api-key
LLM_KEY=MOONSHOT_KIMI_K2
```
### Available models
| LLM_KEY | Notes |
|---------|-------|
| `MOONSHOT_KIMI_K2` | |
### Optional settings
```bash .env
# Use a custom API endpoint
MOONSHOT_API_BASE=https://api.moonshot.cn/v1
```
---
## Inception
[Inception AI](https://inception.ai/) provides the Mercury series models.
```bash .env
ENABLE_INCEPTION=true
INCEPTION_API_KEY=your-inception-api-key
LLM_KEY=INCEPTION_MERCURY_2
```
### Available models
| LLM_KEY | Notes |
|---------|-------|
| `INCEPTION_MERCURY_2` | |
### Optional settings
```bash .env
# Use a custom API endpoint
INCEPTION_API_BASE=https://api.inception.ai/v1
```
---
## Ollama (Local Models)
Run open-source models locally with [Ollama](https://ollama.ai/). No API costs, but requires sufficient local compute.
```bash .env
ENABLE_OLLAMA=true
LLM_KEY=OLLAMA
OLLAMA_MODEL=gemma4
OLLAMA_SERVER_URL=http://host.docker.internal:11434
OLLAMA_SUPPORTS_VISION=false
```
### Setup steps
1. [Install Ollama](https://ollama.ai/download)
2. Pull a model: `ollama pull gemma4`
3. Start Ollama: `ollama serve`
4. Configure Skyvern to connect
<Warning>
Most Ollama models don't support vision. Set `OLLAMA_SUPPORTS_VISION=false`. Without vision, Skyvern relies on DOM analysis instead of screenshot analysis, which may reduce accuracy on complex pages.
</Warning>
### Docker networking
When running Skyvern in Docker and Ollama on the host:
| Host OS | OLLAMA_SERVER_URL |
|---------|-------------------|
| macOS/Windows | `http://host.docker.internal:11434` |
| Linux | `http://172.17.0.1:11434` (Docker bridge IP) |
---
## OpenAI-Compatible Endpoints
Connect to any service that implements the OpenAI API format, including LiteLLM, LocalAI, vLLM, and text-generation-inference.
```bash .env
ENABLE_OPENAI_COMPATIBLE=true
OPENAI_COMPATIBLE_MODEL_NAME=gemma4
OPENAI_COMPATIBLE_API_KEY=sk-test
OPENAI_COMPATIBLE_API_BASE=http://localhost:4000/v1
LLM_KEY=OPENAI_COMPATIBLE
```
This is useful for:
- Running local models with a unified API
- Using LiteLLM as a proxy to switch between providers
- Connecting to self-hosted inference servers
---
## OpenRouter
Access multiple models through a single API at [openrouter.ai](https://openrouter.ai/).
```bash .env
ENABLE_OPENROUTER=true
LLM_KEY=OPENROUTER
OPENROUTER_API_KEY=sk-or-...
OPENROUTER_MODEL=mistralai/mistral-small-3.1-24b-instruct
```
---
## Groq
Inference on open-source models at [groq.com](https://groq.com/).
```bash .env
ENABLE_GROQ=true
LLM_KEY=GROQ
GROQ_API_KEY=gsk_...
GROQ_MODEL=llama-3.1-8b-instant
```
<Note>
Groq specializes in fast inference for open-source models. Response times are typically much faster than other providers, but model selection is limited.
</Note>
---
## Using multiple models
### Primary and secondary models
Configure a cheaper model for lightweight operations:
```bash .env
# Main model for complex decisions
LLM_KEY=ANTHROPIC_CLAUDE4.7_OPUS
# or: OPENAI_GPT5_5
# or: GEMINI_3_PRO
# Faster model for simple tasks like dropdown selection
SECONDARY_LLM_KEY=ANTHROPIC_CLAUDE4.6_SONNET
# or: OPENAI_GPT5_4
# or: GEMINI_3.0_FLASH
```
<Tip>
**Recommended primary models (latest):**
- **Anthropic Claude 4.7 Opus** (`ANTHROPIC_CLAUDE4.7_OPUS`) - Most capable
- **OpenAI GPT-5.5** (`OPENAI_GPT5_5`) - Latest
- **Google Gemini 3 Pro** (`GEMINI_3_PRO`) - Latest
**Recommended secondary models (latest):**
- **Claude 4.6 Sonnet** (`ANTHROPIC_CLAUDE4.6_SONNET`) - Balanced
- **GPT-5.4** (`OPENAI_GPT5_4`) - Fast reasoning
- **Gemini 3.0 Flash** (`GEMINI_3.0_FLASH`) - Faster Gemini 3
</Tip>
### Task-specific models
For fine-grained control, you can override models for specific operations:
```bash .env
# Model for data extraction from pages (defaults to LLM_KEY if not set)
EXTRACTION_LLM_KEY=ANTHROPIC_CLAUDE4.5_SONNET
# Model for generating code/scripts in code blocks (defaults to LLM_KEY if not set)
SCRIPT_GENERATION_LLM_KEY=OPENAI_GPT5
```
Most deployments don't need task-specific models. Start with `LLM_KEY` and `SECONDARY_LLM_KEY`.
---
## Troubleshooting
### "To enable svg shape conversion, please set the Secondary LLM key"
Some operations require a secondary model. Set `SECONDARY_LLM_KEY` in your environment:
```bash .env
SECONDARY_LLM_KEY=OPENAI_GPT5_4
```
### "Context window exceeded"
The page content is too large for the model's context window. Options:
- Use a model with larger context support (GPT-5.5, Gemini 2.5 Pro, or Claude 4.7 Opus)
- Simplify your prompt to require less page analysis
- Start from a more specific URL with less content
### "LLM caller not found"
The configured `LLM_KEY` doesn't match any enabled provider. Verify:
1. The provider is enabled (`ENABLE_OPENAI=true`, etc.)
2. The `LLM_KEY` value matches a supported model name exactly
3. Model names are case-sensitive: `OPENAI_GPT5_5` not `openai_gpt5_5`
### Container logs show authentication errors
Check your API key configuration:
- Ensure the key is set correctly without extra whitespace
- Verify the key hasn't expired or been revoked
- For Azure, ensure `AZURE_API_BASE` includes the full URL with `https://`
### Slow response times
LLM calls typically take 2-10 seconds. Longer times may indicate:
- Network latency to the provider
- Rate limiting (the provider may be throttling requests)
- For Ollama, insufficient local compute resources
---
## Next steps
<CardGroup cols={2}>
<Card title="Browser Configuration" icon="window" href="/developers/self-hosted/browser">
Configure browser modes, locales, and display settings
</Card>
<Card title="Docker Setup" icon="docker" href="/developers/self-hosted/docker">
Return to the main Docker setup guide
</Card>
</CardGroup>
+116
View File
@@ -0,0 +1,116 @@
---
title: Self-Hosted Overview
subtitle: Run Skyvern on your own infrastructure
description: Deploy Skyvern on your own infrastructure with Docker or Kubernetes. Configure LLM providers, browsers, proxies, and storage.
slug: developers/self-hosted/overview
keywords:
- self-hosted
- on-premise
- infrastructure
- deployment
- architecture
- components
- requirements
---
Self-hosted Skyvern runs entirely on your infrastructure: your servers, your browsers, your LLM API keys. This guide helps you decide if self-hosting fits your needs and which deployment method to choose.
## Architecture
Self-hosted Skyvern has four components running on your infrastructure:
```mermaid
flowchart LR
subgraph Your Infrastructure
API[Skyvern API Server<br/>+ Embedded Browser]
UI[Skyvern Web UI]
DB[(PostgreSQL)]
end
LLM[LLM Provider]
Sites[Target Websites]
UI <--> API
API <--> DB
API <--> LLM
API <--> Sites
```
| Component | Role |
|-----------|------|
| **Skyvern API Server** | Orchestrates tasks, processes LLM responses, stores results. Includes an embedded Playwright-managed Chromium browser that executes web automation. |
| **Skyvern Web UI** | Browser-based dashboard for building workflows, running tasks, viewing recordings, and managing credentials. Docker Compose starts it alongside the API server. |
| **PostgreSQL** | Stores task history, workflows, credentials, and organization data |
| **LLM Provider** | Analyzes screenshots and determines actions. You provide the API key (OpenAI, Anthropic, Azure OpenAI, Google Vertex AI, Amazon Bedrock, Groq, OpenRouter, or local via Ollama) |
### How a task executes
Skyvern runs a perception-action loop for each task step:
1. **Screenshot**: The browser captures the current page state
2. **Analyze**: The screenshot is sent to your LLM, which identifies interactive elements and decides the next action
3. **Execute**: Skyvern performs the action in the browser (click, type, scroll, extract data)
4. **Repeat**: Steps 1-3 loop until the task goal is met or the step limit (`MAX_STEPS_PER_RUN`) is reached
This loop is why LLM choice and browser configuration are the two most impactful self-hosting decisions. They affect every task step.
## What changes from Cloud
| You gain | You manage |
|----------|------------|
| Full data control: browser sessions and results stay on your network | Infrastructure: servers, scaling, uptime |
| Any LLM provider, including local models via Ollama | LLM API costs: pay your provider directly |
| No per-task pricing | Proxies: bring your own provider |
| Full access to browser configuration and extensions | Software updates: pull new Docker images manually |
| Deploy in air-gapped or restricted networks | Database backups and maintenance |
<Note>
The most significant operational difference is **proxies**. Skyvern Cloud routes browser traffic through managed residential proxies to avoid bot detection. Self-hosted deployments need you to configure your own proxy provider.
</Note>
## Prerequisites
Before deploying, ensure you have:
<Steps>
<Step title="Docker and Docker Compose">
Required for containerized deployment. [Install Docker](https://docs.docker.com/get-docker/)
</Step>
<Step title="4GB+ RAM">
Browser instances are memory-intensive. Production deployments benefit from 8GB+.
</Step>
<Step title="LLM API key">
From OpenAI, Anthropic, Azure OpenAI, Google Gemini, or AWS Bedrock. Alternatively, run local models with Ollama.
</Step>
<Step title="Proxy provider (recommended)">
For automating external websites at scale. Not required for internal tools or development.
</Step>
</Steps>
PostgreSQL 14+ is included in the Docker Compose setup. If you prefer an external database, configure `DATABASE_STRING` to point to your own instance.
For local server commands from PyPI, install the server extra: `pip install "skyvern[server]"`. The lightweight `pip install skyvern` package is for Skyvern Cloud / remote API SDK usage and does not include the local server stack. Guided quickstart and migrations currently require Docker Compose or a source checkout.
For a full self-hosted deployment with the web UI, use Docker Compose. The Compose stack starts the API server, browser runtime, Postgres, and the Skyvern web UI together.
For the source-checkout `pip install ".[server]"` path (Option A in the README), the default is a SQLite database at `~/.skyvern/data.db` — zero-config for local dev. To opt into Postgres for that path, run `skyvern quickstart --database-string=postgresql+psycopg://user:pass@host:5432/dbname`.
## Choose your deployment method
| Method | Best for |
|--------|----------|
| **Docker Compose** | Getting started, small teams, single-server deployments |
| **Kubernetes** | Production at scale, teams with existing K8s infrastructure, high availability requirements |
Most teams start with Docker Compose. It's the fastest path to a working deployment. Move to Kubernetes when you need horizontal scaling or want to integrate with existing orchestration infrastructure.
## Next steps
<CardGroup cols={2}>
<Card title="Docker Setup" icon="docker" href="/developers/self-hosted/docker">
Get Skyvern running in 10 minutes with Docker Compose
</Card>
<Card title="Kubernetes Deployment" icon="dharmachakra" href="/developers/self-hosted/kubernetes">
Deploy to production with Kubernetes manifests
</Card>
</CardGroup>
+245
View File
@@ -0,0 +1,245 @@
---
title: Proxy Setup
subtitle: Configure proxies to avoid bot detection
description: Configure residential, ISP, or datacenter proxies for self-hosted Skyvern deployments to avoid bot detection, bypass geo-restrictions, and prevent rate limiting on target websites.
slug: developers/self-hosted/proxy
keywords:
- residential proxy
- ISP proxy
- datacenter proxy
- rate limiting
- geo-restriction
- PROXY_URL
- configuration
---
Many websites block requests from datacenter IPs or detect automated browser patterns. Skyvern Cloud includes managed residential proxies that handle this automatically. Self-hosted deployments require you to configure your own proxy provider.
## Why you need proxies
Without proxies, your browser automation traffic originates from your server's IP address. This causes issues when:
- **Target sites block datacenter IPs**: Many sites automatically block traffic from known hosting providers (AWS, GCP, Azure)
- **Rate limiting**: Repeated requests from one IP trigger rate limits
- **Geo-restrictions**: Sites serve different content based on location
- **Bot detection**: Some sites fingerprint datacenter traffic patterns
<Note>
If you're automating internal tools or sites that don't have bot detection, you may not need proxies at all. Test without proxies first.
</Note>
---
## Proxy types
### Residential proxies
Traffic appears to come from real home internet connections. Most expensive but least likely to be blocked. Recommended for browser automation. Start here unless cost is a primary concern.
**Providers:**
- [Bright Data](https://brightdata.com/)
- [Oxylabs](https://oxylabs.io/)
- [Smartproxy](https://smartproxy.com/)
- [IPRoyal](https://iproyal.com/)
### ISP proxies
Static IPs from internet service providers. Good balance between cost and detection avoidance.
### Datacenter proxies
IPs from cloud providers. Cheapest but most likely to be blocked.
### Rotating vs. static
See [Rotating proxies vs. sticky sessions](#rotating-proxies-vs-sticky-sessions) for guidance on which to use.
---
## Configuration
Skyvern supports proxy configuration at the browser level through Playwright.
### Environment variable approach
Set proxy configuration in your `.env` file:
```bash .env
ENABLE_PROXY=true
# Single proxy
HOSTED_PROXY_POOL=http://user:pass@proxy.example.com:8080
# Multiple proxies: Skyvern randomly selects one per browser session
HOSTED_PROXY_POOL=http://user:pass@proxy1.example.com:8080,http://user:pass@proxy2.example.com:8080
```
<Note>
Skyvern Cloud supports a `proxy_location` parameter on task requests for geographic targeting (e.g., `RESIDENTIAL_US`). This feature is not available in self-hosted deployments. All tasks use the proxy configured in `HOSTED_PROXY_POOL`.
</Note>
---
## Setting up a proxy provider
### Step 1: Choose a provider
For browser automation, residential proxies work best. See [proxy types](#proxy-types) above.
### Step 2: Configure Skyvern
Add your proxy to the environment:
```bash .env
ENABLE_PROXY=true
HOSTED_PROXY_POOL=http://username:password@proxy.provider.com:8080
```
### Step 3: Test the connection
Run a simple task that checks your IP:
```bash
curl -s http://localhost:8000/v1/tasks \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "What is the IP address shown on this page?",
"url": "https://whatismyipaddress.com"
}'
```
The task result should show an IP from your proxy provider, not your server's IP.
---
## Proxy authentication methods
### Basic auth (most common)
Include credentials in the URL:
```bash
http://username:password@proxy.example.com:8080
```
### IP whitelist
Some providers allow you to whitelist your server's IP instead of using credentials:
1. Get your server's public IP: `curl ifconfig.me`
2. Add it to your proxy provider's whitelist
3. Use the proxy without credentials:
```bash
http://proxy.example.com:8080
```
---
## Geographic targeting
If your proxy provider supports geographic targeting, configure it in your proxy URL. The exact format depends on the provider.
### Bright Data example
```bash
# Target US residential
http://user-country-us:pass@proxy.brightdata.com:8080
# Target specific US state
http://user-country-us-state-california:pass@proxy.brightdata.com:8080
```
### Oxylabs example
```bash
# Target UK
http://user-country-gb:pass@proxy.oxylabs.io:8080
```
Check your provider's documentation for the exact format.
---
## Rotating proxies vs. sticky sessions
### Rotating (new IP per request)
Good for:
- High-volume scraping
- Avoiding per-IP rate limits
- Tasks that don't need session persistence
### Sticky sessions (same IP for duration)
Good for:
- Multi-step automations where the site tracks your session
- Login flows
- Sites that block IP changes mid-session
Most providers support sticky sessions via a session ID parameter:
```bash
# Bright Data sticky session
http://user-session-abc123:pass@proxy.brightdata.com:8080
```
---
## Troubleshooting
### "Connection refused" or timeout errors
- Verify your proxy endpoint and credentials are correct
- Check if your server can reach the proxy: `curl -x http://user:pass@proxy:port http://example.com`
- Ensure your provider hasn't blocked your IP
### Target site still blocking requests
- Try a different proxy location
- Use residential instead of datacenter proxies
- Enable sticky sessions if the site tracks session changes
- Verify the proxy is actually being used (check the IP)
### Slow performance
- Proxy overhead adds 100-500ms per request
- Choose a proxy location geographically close to the target site
- Use datacenter proxies for sites that allow them (faster than residential)
### High proxy costs
Residential proxy bandwidth is expensive. To reduce costs:
- Disable video recording (reduces bandwidth)
- Use datacenter proxies for sites that allow them
- Cache resources where possible
- Minimize unnecessary page loads
---
## Running without proxies
For internal tools or development, proxies aren't always necessary:
```bash .env
ENABLE_PROXY=false
```
Your browser traffic will originate directly from your server's IP. This works well for:
- Internal applications
- Development and testing
- Sites that don't block datacenter traffic
---
## Next steps
<CardGroup cols={2}>
<Card title="Storage Configuration" icon="hard-drive" href="/developers/self-hosted/storage">
Store recordings and artifacts in S3 or Azure Blob
</Card>
<Card title="Kubernetes Deployment" icon="dharmachakra" href="/developers/self-hosted/kubernetes">
Deploy Skyvern at scale with Kubernetes
</Card>
</CardGroup>
+364
View File
@@ -0,0 +1,364 @@
---
title: Storage Configuration
subtitle: Configure where Skyvern stores artifacts and recordings
description: Configure Skyvern artifact storage using local filesystem, AWS S3, or Azure Blob Storage. Covers screenshots, browser recordings, HAR files, and extracted data storage for self-hosted deployments.
slug: developers/self-hosted/storage
keywords:
- AWS S3
- Azure Blob Storage
- local filesystem
- artifact storage
- ARTIFACT_STORAGE_TYPE
- bucket
- container
---
Skyvern generates several types of artifacts during task execution: screenshots, browser recordings, HAR files, and extracted data. By default, these are stored on the local filesystem. For production deployments, you can configure S3 or Azure Blob Storage.
## Storage types
Skyvern supports three storage backends:
| Type | `SKYVERN_STORAGE_TYPE` | Best for |
|------|------------------------|----------|
| Local filesystem | `local` | Development, single-server deployments |
| AWS S3 | `s3` | Production on AWS, multi-server deployments |
| Azure Blob | `azureblob` | Production on Azure |
---
## Local storage (default)
By default, Skyvern stores all artifacts in a local directory.
```bash .env
SKYVERN_STORAGE_TYPE=local
ARTIFACT_STORAGE_PATH=/data/artifacts
VIDEO_PATH=/data/videos
HAR_PATH=/data/har
LOG_PATH=/data/log
```
### Docker volume mounts
When using Docker Compose, these paths are mounted from your host:
```yaml docker-compose.yml
volumes:
- ./artifacts:/data/artifacts
- ./videos:/data/videos
- ./har:/data/har
- ./log:/data/log
```
### Limitations
Local storage works well for single-server deployments but has limitations:
- Not accessible across multiple servers
- No automatic backup or redundancy
- Requires manual cleanup to manage disk space
---
## AWS S3
Store artifacts in S3 for durability, scalability, and access from multiple servers.
### Configuration
```bash .env
SKYVERN_STORAGE_TYPE=s3
AWS_REGION=us-east-1
AWS_S3_BUCKET_ARTIFACTS=your-skyvern-artifacts
AWS_S3_BUCKET_SCREENSHOTS=your-skyvern-screenshots
AWS_S3_BUCKET_BROWSER_SESSIONS=your-skyvern-browser-sessions
AWS_S3_BUCKET_UPLOADS=your-skyvern-uploads
# Pre-signed URL expiration (seconds) - default 24 hours
PRESIGNED_URL_EXPIRATION=86400
# Maximum upload file size (bytes) - default 10MB
MAX_UPLOAD_FILE_SIZE=10485760
```
### Authentication
Skyvern uses the standard AWS credential chain. Configure credentials using one of these methods:
**Environment variables:**
```bash .env
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
```
**IAM role (recommended for EC2/ECS/EKS):**
Attach an IAM role with S3 permissions to your instance or pod. No credentials needed in environment.
**AWS profile:**
```bash .env
AWS_PROFILE=your-profile-name
```
### Required IAM permissions
Create an IAM policy with these permissions:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::your-skyvern-artifacts",
"arn:aws:s3:::your-skyvern-artifacts/*",
"arn:aws:s3:::your-skyvern-screenshots",
"arn:aws:s3:::your-skyvern-screenshots/*",
"arn:aws:s3:::your-skyvern-browser-sessions",
"arn:aws:s3:::your-skyvern-browser-sessions/*",
"arn:aws:s3:::your-skyvern-uploads",
"arn:aws:s3:::your-skyvern-uploads/*"
]
}
]
}
```
### Creating the buckets
Create the S3 buckets in your AWS account:
```bash
aws s3 mb s3://your-skyvern-artifacts --region us-east-1
aws s3 mb s3://your-skyvern-screenshots --region us-east-1
aws s3 mb s3://your-skyvern-browser-sessions --region us-east-1
aws s3 mb s3://your-skyvern-uploads --region us-east-1
```
<Note>
Bucket names must be globally unique across all AWS accounts. Add a unique prefix or suffix (e.g., your company name or a random string).
</Note>
### Bucket configuration recommendations
**Lifecycle rules:** Configure automatic deletion of old artifacts to control costs.
```bash
aws s3api put-bucket-lifecycle-configuration \
--bucket your-skyvern-artifacts \
--lifecycle-configuration '{
"Rules": [
{
"ID": "DeleteOldArtifacts",
"Status": "Enabled",
"Filter": {},
"Expiration": {
"Days": 30
}
}
]
}'
```
**Encryption:** Enable server-side encryption for data at rest.
**Access logging:** Enable access logging for audit trails.
---
## Azure Blob Storage
Store artifacts in Azure Blob Storage for Azure-based deployments.
### Configuration
```bash .env
SKYVERN_STORAGE_TYPE=azureblob
AZURE_STORAGE_ACCOUNT_NAME=yourstorageaccount
AZURE_STORAGE_ACCOUNT_KEY=your-storage-account-key
AZURE_STORAGE_CONTAINER_ARTIFACTS=skyvern-artifacts
AZURE_STORAGE_CONTAINER_SCREENSHOTS=skyvern-screenshots
AZURE_STORAGE_CONTAINER_BROWSER_SESSIONS=skyvern-browser-sessions
AZURE_STORAGE_CONTAINER_UPLOADS=skyvern-uploads
# Pre-signed URL expiration (seconds) - default 24 hours
PRESIGNED_URL_EXPIRATION=86400
# Maximum upload file size (bytes) - default 10MB
MAX_UPLOAD_FILE_SIZE=10485760
```
### Creating the storage account and containers
Using Azure CLI:
```bash
# Create resource group
az group create --name skyvern-rg --location eastus
# Create storage account
az storage account create \
--name yourstorageaccount \
--resource-group skyvern-rg \
--location eastus \
--sku Standard_LRS
# Get the account key
az storage account keys list \
--account-name yourstorageaccount \
--resource-group skyvern-rg \
--query '[0].value' -o tsv
# Create containers
az storage container create --name skyvern-artifacts --account-name yourstorageaccount
az storage container create --name skyvern-screenshots --account-name yourstorageaccount
az storage container create --name skyvern-browser-sessions --account-name yourstorageaccount
az storage container create --name skyvern-uploads --account-name yourstorageaccount
```
### Using Managed Identity (recommended)
For Azure VMs or AKS, use Managed Identity instead of storage account keys:
1. Enable Managed Identity on your VM or AKS cluster
2. Grant the identity "Storage Blob Data Contributor" role on the storage account
3. Omit `AZURE_STORAGE_ACCOUNT_KEY` from your configuration
---
## What gets stored where
| Artifact type | S3 bucket / Azure container | Contents |
|---------------|---------------------------|----------|
| Artifacts | `*-artifacts` | Extracted data, HTML snapshots, logs |
| Screenshots | `*-screenshots` | Page screenshots at each step |
| Browser Sessions | `*-browser-sessions` | Saved browser state for profiles |
| Uploads | `*-uploads` | User-uploaded files for workflows |
Videos (recordings) are currently always stored locally in `VIDEO_PATH` regardless of storage type.
---
## Pre-signed URLs
When artifacts are stored in S3 or Azure Blob, Skyvern generates pre-signed URLs for access. These URLs:
- Expire after `PRESIGNED_URL_EXPIRATION` seconds (default: 24 hours)
- Allow direct download without additional authentication
- Are included in task responses (`recording_url`, `screenshot_urls`)
Adjust the expiration based on your needs:
```bash .env
# 1 hour
PRESIGNED_URL_EXPIRATION=3600
# 7 days
PRESIGNED_URL_EXPIRATION=604800
```
---
## Migrating from local to cloud storage
To migrate existing artifacts from local storage to S3 or Azure:
### S3
```bash
# Sync local artifacts to S3
aws s3 sync ./artifacts s3://your-skyvern-artifacts/
# Update configuration
# SKYVERN_STORAGE_TYPE=s3
# ...
# Restart Skyvern
docker compose restart skyvern
```
### Azure
```bash
# Install azcopy
# https://docs.microsoft.com/en-us/azure/storage/common/storage-use-azcopy-v10
# Sync local artifacts to Azure
azcopy copy './artifacts/*' 'https://yourstorageaccount.blob.core.windows.net/skyvern-artifacts' --recursive
# Update configuration and restart
```
<Warning>
After migration, new artifacts will be stored in cloud storage, but existing local artifacts won't be automatically moved. The sync is a one-time operation.
</Warning>
---
## Disk space management
### Local storage
Monitor disk usage and clean up old artifacts periodically:
```bash
# Check disk usage
du -sh ./artifacts ./videos ./har ./log
# Remove artifacts older than 30 days
find ./artifacts -type f -mtime +30 -delete
find ./videos -type f -mtime +30 -delete
```
### Cloud storage
Use lifecycle policies to automatically delete old objects:
**S3:** Configure lifecycle rules to expire objects after N days.
**Azure:** Configure lifecycle management policies in the Azure portal or via CLI.
---
## Troubleshooting
### "Access Denied" errors
- Verify your credentials are correct
- Check IAM permissions include all required actions
- Ensure the buckets/containers exist
- For S3, verify the AWS region matches your bucket location
### Pre-signed URLs not working
- Check that `PRESIGNED_URL_EXPIRATION` hasn't elapsed
- Verify bucket policy allows public access to pre-signed URLs
- For S3, ensure the bucket isn't blocking public access if needed
### Artifacts not appearing
- Check Skyvern logs for storage errors: `docker compose logs skyvern | grep -i storage`
- Verify the storage type is correctly set: `SKYVERN_STORAGE_TYPE`
- Ensure network connectivity to the storage endpoint
---
## Next steps
<CardGroup cols={2}>
<Card title="Docker Setup" icon="docker" href="/developers/self-hosted/docker">
Return to the Docker setup guide
</Card>
<Card title="Kubernetes Deployment" icon="dharmachakra" href="/developers/self-hosted/kubernetes">
Deploy Skyvern at scale
</Card>
</CardGroup>
+865
View File
@@ -0,0 +1,865 @@
{
"$schema": "https://mintlify.com/docs.json",
"theme": "palm",
"name": "Skyvern",
"colors": {
"primary": "#4A6CF7",
"light": "#7B93FA",
"dark": "#1B2559"
},
"appearance": {
"default": "light"
},
"background": {
"color": {
"light": "#F8F5EF",
"dark": "#1C1917"
}
},
"fonts": {
"heading": {
"family": "Inter",
"weight": 600
},
"body": {
"family": "Inter",
"weight": 400
}
},
"logo": {
"light": "/images/skyvern_logo_blackbg.png",
"dark": "/logo/dark.png",
"href": "https://skyvern.com"
},
"favicon": "/favicon.png",
"search": {
"prompt": "Search Skyvern docs..."
},
"navigation": {
"tabs": [
{
"tab": "Home",
"pages": [
"index",
"nav/cloud-ui",
"nav/developers",
"nav/cookbooks",
"nav/changelog",
"nav/api-reference",
"nav/sdk-reference"
]
},
{
"tab": "Cloud UI",
"groups": [
{
"group": "Getting Started",
"pages": [
"cloud/getting-started/introduction",
"cloud/getting-started/core-concepts",
"cloud/getting-started/ai-agents-quickstart",
"cloud/getting-started/overview",
"cloud/getting-started/mcp"
]
},
{
"group": "Building Workflows",
"pages": [
"cloud/building-workflows/build-a-workflow",
"cloud/building-workflows/manage-workflows",
"cloud/building-workflows/add-parameters",
"cloud/building-workflows/run-a-workflow",
"cloud/building-workflows/scheduling",
"cloud/building-workflows/run-from-code"
]
},
{
"group": "Workflow Blocks",
"pages": ["cloud/building-workflows/configure-blocks"]
},
{
"group": "Running Tasks",
"pages": [
"cloud/getting-started/run-your-first-task",
"cloud/getting-started/run-a-task",
"cloud/getting-started/monitor-a-run",
"cloud/getting-started/run-from-code"
]
},
{
"group": "Re-using Browsers",
"pages": [
"cloud/browser-management/browser-sessions",
"cloud/browser-management/browser-profiles"
]
},
{
"group": "Viewing Results",
"pages": [
"cloud/viewing-results/run-history",
"cloud/viewing-results/run-details",
"cloud/viewing-results/downloading-artifacts"
]
},
{
"group": "Managing Credentials",
"pages": [
"cloud/managing-credentials/credentials-overview",
"cloud/managing-credentials/password-credentials",
"cloud/managing-credentials/credit-card-credentials",
"cloud/managing-credentials/totp-setup",
"cloud/managing-credentials/external-providers"
]
},
{
"group": "Integrations",
"pages": [
"integrations/zapier",
"integrations/make",
"integrations/n8n",
"integrations/workato"
]
},
{
"group": "Account & Settings",
"pages": [
"cloud/account-settings/api-keys",
"cloud/account-settings/billing-usage",
"cloud/account-settings/organization-settings",
"cloud/account-settings/profile-settings"
]
}
]
},
{
"tab": "Developers",
"groups": [
{
"group": "Getting Started",
"pages": [
"developers/getting-started/introduction",
"developers/getting-started/core-concepts",
"developers/getting-started/quickstart",
"developers/getting-started/ai-agents-quickstart",
"developers/getting-started/mcp",
"integrations/cli"
]
},
{
"group": "Core Features",
"pages": [
"developers/features/captcha-and-bot-bypass",
"developers/features/browser-sessions",
"developers/features/proxy-and-geo-targeting",
"developers/features/authentication-and-2fa",
"developers/features/code-caching"
]
},
{
"group": "Browser Automation",
"pages": [
"developers/browser-automations/overview",
"developers/browser-automations/extract-structured-data",
"developers/browser-automations/work-with-files",
"developers/browser-automations/handle-browsers"
]
},
{
"group": "Workflow Blocks",
"pages": ["developers/browser-automations/actions-reference"]
},
{
"group": "Handling Authentication",
"pages": [
"developers/credentials/store-credentials",
"developers/credentials/handle-2fa",
"developers/credentials/troubleshooting-login"
]
},
{
"group": "Optimization",
"pages": [
"developers/optimization/browser-sessions",
"developers/optimization/browser-profiles",
"developers/optimization/cost-control"
]
},
{
"group": "Going to Production",
"pages": [
"developers/going-to-production/webhooks",
"developers/going-to-production/proxy-geolocation",
"developers/going-to-production/error-handling",
"developers/going-to-production/reliability-tips"
]
},
{
"group": "Debugging",
"pages": [
"developers/debugging/using-artifacts",
"developers/debugging/troubleshooting-guide",
"developers/debugging/observability-with-laminar",
"developers/debugging/faq"
]
},
{
"group": "Self-Hosted Deployment",
"pages": [
"developers/self-hosted/overview",
"developers/self-hosted/docker",
"developers/self-hosted/llm-configuration",
"developers/self-hosted/browser",
"developers/self-hosted/proxy",
"developers/self-hosted/kubernetes",
"developers/self-hosted/storage",
"integrations/local-llms"
]
}
]
},
{
"tab": "Cookbooks",
"pages": [
"cookbooks/overview",
"cookbooks/bulk-invoice-downloader",
"cookbooks/job-application-filler",
"cookbooks/healthcare-portal-data"
]
},
{
"tab": "Changelog",
"pages": ["changelog"]
},
{
"tab": "API Reference",
"openapi": "api-reference/openapi.json"
},
{
"tab": "SDK Reference",
"groups": [
{
"group": "SDK",
"pages": [
"sdk-reference/overview",
"sdk-reference/error-handling",
"sdk-reference/complete-reference"
]
},
{
"group": "Browser Automation",
"pages": [
{
"group": "Page",
"pages": [
"sdk-reference/browser-automation/act",
"sdk-reference/browser-automation/extract",
"sdk-reference/browser-automation/validate",
"sdk-reference/browser-automation/prompt",
"sdk-reference/browser-automation/locator",
"sdk-reference/browser-automation/click",
"sdk-reference/browser-automation/fill",
"sdk-reference/browser-automation/select-option",
"sdk-reference/browser-automation/type",
"sdk-reference/browser-automation/hover",
"sdk-reference/browser-automation/scroll",
"sdk-reference/browser-automation/upload-file",
"sdk-reference/browser-automation/fill-form",
"sdk-reference/browser-automation/fill-multipage-form",
"sdk-reference/browser-automation/fill-from-mapping",
"sdk-reference/browser-automation/extract-form-fields",
"sdk-reference/browser-automation/validate-mapping",
"sdk-reference/browser-automation/fill-autocomplete",
"sdk-reference/browser-automation/frame-switch",
"sdk-reference/browser-automation/frame-main",
"sdk-reference/browser-automation/frame-list"
]
},
{
"group": "Agent",
"pages": [
"sdk-reference/browser-automation/agent-run-task",
"sdk-reference/browser-automation/agent-login",
"sdk-reference/browser-automation/agent-download-files",
"sdk-reference/browser-automation/agent-run-workflow"
]
},
{
"group": "Browser",
"pages": [
"sdk-reference/browser-automation/launch-cloud-browser",
"sdk-reference/browser-automation/use-cloud-browser",
"sdk-reference/browser-automation/connect-to-cloud-browser-session",
"sdk-reference/browser-automation/connect-to-browser-over-cdp",
"sdk-reference/browser-automation/launch-local-browser",
"sdk-reference/browser-automation/get-working-page",
"sdk-reference/browser-automation/new-page",
"sdk-reference/browser-automation/get-page-for",
"sdk-reference/browser-automation/close"
]
},
"sdk-reference/browser-automation/complete-example"
]
},
{
"group": "Tasks",
"pages": [
"sdk-reference/tasks/run-task",
"sdk-reference/tasks/get-run",
"sdk-reference/tasks/cancel-run",
"sdk-reference/tasks/get-run-timeline",
"sdk-reference/tasks/get-run-artifacts",
"sdk-reference/tasks/get-artifact",
"sdk-reference/tasks/get-runs-v2",
"sdk-reference/tasks/retry-run-webhook"
]
},
{
"group": "Workflows",
"pages": [
"sdk-reference/workflows/run-workflow",
"sdk-reference/workflows/create-workflow",
"sdk-reference/workflows/get-workflow",
"sdk-reference/workflows/get-workflows",
"sdk-reference/workflows/get-workflow-versions",
"sdk-reference/workflows/update-workflow",
"sdk-reference/workflows/delete-workflow",
"sdk-reference/workflows/get-workflow-runs",
"sdk-reference/workflows/update-workflow-folder"
]
},
{
"group": "Browser Sessions",
"pages": [
"sdk-reference/browser-sessions/create-browser-session",
"sdk-reference/browser-sessions/get-browser-session",
"sdk-reference/browser-sessions/get-browser-sessions",
"sdk-reference/browser-sessions/close-browser-session"
]
},
{
"group": "Browser Profiles",
"pages": [
"sdk-reference/browser-profiles/create-browser-profile",
"sdk-reference/browser-profiles/list-browser-profiles",
"sdk-reference/browser-profiles/get-browser-profile",
"sdk-reference/browser-profiles/delete-browser-profile"
]
},
{
"group": "Credentials",
"pages": [
"sdk-reference/credentials/create-credential",
"sdk-reference/credentials/get-credential",
"sdk-reference/credentials/get-credentials",
"sdk-reference/credentials/update-credential",
"sdk-reference/credentials/delete-credential",
"sdk-reference/credentials/send-totp-code"
]
},
{
"group": "Helpers",
"pages": [
"sdk-reference/helpers/login",
"sdk-reference/helpers/download-files",
"sdk-reference/helpers/upload-file"
]
}
]
}
]
},
"navbar": {
"links": [
{
"label": "Talk to us",
"href": "https://www.skyvern.com/contact"
}
],
"primary": {
"type": "button",
"label": "Get Started",
"href": "https://app.skyvern.com/"
}
},
"footer": {
"socials": {
"github": "https://github.com/Skyvern-AI/skyvern",
"discord": "https://discord.gg/skyvern",
"twitter": "https://twitter.com/skyvernai"
}
},
"contextual": {
"options": ["copy", "view", "claude", "chatgpt", "cursor", "vscode", "mcp"]
},
"seo": {
"indexing": "navigable"
},
"css": "/style.css",
"api": {
"baseUrl": "https://api.skyvern.com",
"auth": {
"method": "key",
"name": "x-api-key"
},
"playground": {
"display": "interactive"
}
},
"errors": {
"404": {
"redirect": false,
"title": "Page not found",
"description": "This page doesn't exist. Try the [documentation home](/) or use search to find what you need."
}
},
"redirects": [
{
"source": "/going-to-production/captcha-bot-detection",
"destination": "/developers/features/captcha-and-bot-bypass"
},
{
"source": "/sdk-reference/browser-automation/find",
"destination": "/sdk-reference/browser-automation/locator"
},
{
"source": "/sdk-reference/tasks",
"destination": "/sdk-reference/tasks/run-task"
},
{
"source": "/sdk-reference/workflows",
"destination": "/sdk-reference/workflows/run-workflow"
},
{
"source": "/sdk-reference/browser-sessions",
"destination": "/sdk-reference/browser-sessions/create-browser-session"
},
{
"source": "/sdk-reference/browser-profiles",
"destination": "/sdk-reference/browser-profiles/create-browser-profile"
},
{
"source": "/sdk-reference/credentials",
"destination": "/sdk-reference/credentials/create-credential"
},
{
"source": "/sdk-reference/helpers",
"destination": "/sdk-reference/helpers/login"
},
{
"source": "/sdk-reference/browser-automation",
"destination": "/sdk-reference/browser-automation/launch-cloud-browser"
},
{
"source": "/ts-sdk-reference/overview",
"destination": "/sdk-reference/overview"
},
{
"source": "/ts-sdk-reference/tasks",
"destination": "/sdk-reference/tasks/run-task"
},
{
"source": "/ts-sdk-reference/workflows",
"destination": "/sdk-reference/workflows/run-workflow"
},
{
"source": "/ts-sdk-reference/browser-sessions",
"destination": "/sdk-reference/browser-sessions/create-browser-session"
},
{
"source": "/ts-sdk-reference/browser-profiles",
"destination": "/sdk-reference/browser-profiles/create-browser-profile"
},
{
"source": "/ts-sdk-reference/credentials",
"destination": "/sdk-reference/credentials/create-credential"
},
{
"source": "/ts-sdk-reference/helpers",
"destination": "/sdk-reference/helpers/login"
},
{
"source": "/ts-sdk-reference/browser-automation",
"destination": "/sdk-reference/browser-automation/launch-cloud-browser"
},
{
"source": "/ts-sdk-reference/error-handling",
"destination": "/sdk-reference/error-handling"
},
{
"source": "/ts-sdk-reference/complete-reference",
"destination": "/sdk-reference/complete-reference"
},
{
"source": "/introduction",
"destination": "/developers/getting-started/quickstart"
},
{
"source": "/getting-started/skyvern-in-action",
"destination": "/developers/getting-started/core-concepts"
},
{
"source": "/getting-started/prompting-guide",
"destination": "/developers/debugging/troubleshooting-guide"
},
{
"source": "/running-tasks/run-tasks",
"destination": "/cloud/getting-started/run-from-code"
},
{
"source": "/running-tasks/visualizing-results",
"destination": "/developers/debugging/using-artifacts"
},
{
"source": "/running-tasks/cancel-runs",
"destination": "/cloud/getting-started/run-from-code"
},
{
"source": "/running-tasks/webhooks-faq",
"destination": "/developers/going-to-production/webhooks"
},
{
"source": "/running-tasks/connect-local-browser",
"destination": "/developers/self-hosted/browser"
},
{
"source": "/running-tasks/proxy-location",
"destination": "/developers/going-to-production/proxy-geolocation"
},
{
"source": "/running-tasks/advanced-features",
"destination": "/sdk-reference/tasks/run-task"
},
{
"source": "/running-tasks/api-spec",
"destination": "/cloud/getting-started/run-from-code"
},
{
"source": "/running-automations/run-a-task",
"destination": "/cloud/getting-started/run-from-code"
},
{
"source": "/running-automations/task-parameters",
"destination": "/sdk-reference/tasks/run-task"
},
{
"source": "/running-automations/extract-structured-data",
"destination": "/developers/browser-automations/extract-structured-data"
},
{
"source": "/workflows/manage-workflows",
"destination": "/cloud/building-workflows/manage-workflows"
},
{
"source": "/workflows/workflow-blocks-details",
"destination": "/cloud/building-workflows/configure-blocks"
},
{
"source": "/workflows/workflow-parameters",
"destination": "/cloud/building-workflows/add-parameters"
},
{
"source": "/workflows/run-workflows",
"destination": "/cloud/building-workflows/run-a-workflow"
},
{
"source": "/workflows/consistent-workflows",
"destination": "/developers/going-to-production/reliability-tips"
},
{
"source": "/workflows/running-workflows",
"destination": "/cloud/building-workflows/run-a-workflow"
},
{
"source": "/workflows/introduction",
"destination": "/cloud/building-workflows/build-a-workflow"
},
{
"source": "/workflows/workflow-blocks",
"destination": "/cloud/building-workflows/configure-blocks"
},
{
"source": "/workflows/creating-workflows",
"destination": "/cloud/building-workflows/build-a-workflow"
},
{
"source": "/workflows/getting-workflows",
"destination": "/cloud/building-workflows/run-a-workflow"
},
{
"source": "/workflows/what-is-a-parameter",
"destination": "/cloud/building-workflows/add-parameters"
},
{
"source": "/multi-step-automations/overview",
"destination": "/developers/browser-automations/overview"
},
{
"source": "/multi-step-automations/actions-reference",
"destination": "/developers/browser-automations/actions-reference"
},
{
"source": "/multi-step-automations/extract-structured-data",
"destination": "/developers/browser-automations/extract-structured-data"
},
{
"source": "/multi-step-automations/work-with-files",
"destination": "/developers/browser-automations/work-with-files"
},
{
"source": "/multi-step-automations/handle-browsers",
"destination": "/developers/browser-automations/handle-browsers"
},
{
"source": "/multi-step-automations/build-a-workflow",
"destination": "/developers/browser-automations/overview"
},
{
"source": "/multi-step-automations/workflow-blocks-reference",
"destination": "/developers/browser-automations/actions-reference"
},
{
"source": "/multi-step-automations/file-operations",
"destination": "/developers/browser-automations/work-with-files"
},
{
"source": "/multi-step-automations/workflow-parameters",
"destination": "/cloud/building-workflows/add-parameters"
},
{
"source": "/multi-step-automations/scheduling-workflows",
"destination": "/cloud/building-workflows/scheduling"
},
{
"source": "/credentials/introduction",
"destination": "/cloud/managing-credentials/credentials-overview"
},
{
"source": "/credentials/passwords",
"destination": "/cloud/managing-credentials/password-credentials"
},
{
"source": "/credentials/credit-cards",
"destination": "/cloud/managing-credentials/credit-card-credentials"
},
{
"source": "/credentials/totp",
"destination": "/cloud/managing-credentials/totp-setup"
},
{
"source": "/credentials/bitwarden",
"destination": "/cloud/managing-credentials/external-providers"
},
{
"source": "/credentials/custom-credential-service",
"destination": "/cloud/managing-credentials/external-providers"
},
{
"source": "/browser-sessions/introduction",
"destination": "/developers/optimization/browser-sessions"
},
{
"source": "/browser-sessions/browser-profiles",
"destination": "/developers/optimization/browser-profiles"
},
{
"source": "/observability/overview",
"destination": "/developers/debugging/using-artifacts"
},
{
"source": "/integrations/make.com",
"destination": "/integrations/make"
},
{
"source": "/integrations/ollama-litellm",
"destination": "/integrations/local-llms"
},
{
"source": "/integrations/mcp-server",
"destination": "/developers/getting-started/mcp"
},
{
"source": "/home/integrations/mcp-server",
"destination": "/developers/getting-started/mcp"
},
{
"source": "/integrations/mcp",
"destination": "/developers/getting-started/mcp"
},
{
"source": "/going-to-production/mcp",
"destination": "/developers/getting-started/mcp"
},
{
"source": "/api-reference/api-reference/agent/run-task",
"destination": "/api-reference/agent/run-a-task"
},
{
"source": "/api-reference/api-reference/agent/get-run",
"destination": "/api-reference/agent/get-a-run-by-id"
},
{
"source": "/api-reference/api-reference/agent/cancel-run",
"destination": "/api-reference/agent/cancel-a-run-by-id"
},
{
"source": "/api-reference/api-reference/agent/retry-run-webhook",
"destination": "/api-reference/agent/retry-run-webhook"
},
{
"source": "/api-reference/api-reference/agent/login",
"destination": "/api-reference/agent/login-task"
},
{
"source": "/api-reference/api-reference/agent/get-run-timeline",
"destination": "/api-reference/agent/get-run-timeline"
},
{
"source": "/api-reference/api-reference/workflows/get-workflows",
"destination": "/api-reference/workflows/get-workflows"
},
{
"source": "/api-reference/api-reference/workflows/create-workflow",
"destination": "/api-reference/workflows/create-a-new-workflow"
},
{
"source": "/api-reference/api-reference/workflows/get-workflow",
"destination": "/api-reference/workflows/get-workflows"
},
{
"source": "/api-reference/api-reference/workflows/get-workflow-versions",
"destination": "/api-reference/workflows/get-workflows"
},
{
"source": "/api-reference/api-reference/workflows/update-workflow",
"destination": "/api-reference/workflows/update-a-workflow"
},
{
"source": "/api-reference/api-reference/workflows/delete-workflow",
"destination": "/api-reference/workflows/delete-a-workflow"
},
{
"source": "/api-reference/api-reference/workflow-runs/run-workflow",
"destination": "/api-reference/workflows/run-a-workflow"
},
{
"source": "/api-reference/api-reference/workflow-runs/get-workflow-runs",
"destination": "/api-reference/workflows/get-workflows"
},
{
"source": "/api-reference/api-reference/workflow-runs/get-run",
"destination": "/api-reference/agent/get-a-run-by-id"
},
{
"source": "/api-reference/api-reference/workflow-runs/cancel-run",
"destination": "/api-reference/agent/cancel-a-run-by-id"
},
{
"source": "/api-reference/api-reference/workflow-runs/retry-run-webhook",
"destination": "/api-reference/agent/retry-run-webhook"
},
{
"source": "/api-reference/api-reference/workflow-runs/get-run-timeline",
"destination": "/api-reference/agent/get-run-timeline"
},
{
"source": "/api-reference/api-reference/browser-sessions/create-browser-session",
"destination": "/api-reference/browser-sessions/create-a-session"
},
{
"source": "/api-reference/api-reference/browser-sessions/get-browser-session",
"destination": "/api-reference/browser-sessions/get-a-session"
},
{
"source": "/api-reference/api-reference/browser-sessions/close-browser-session",
"destination": "/api-reference/browser-sessions/close-a-session"
},
{
"source": "/api-reference/api-reference/browser-sessions/get-browser-sessions",
"destination": "/api-reference/browser-sessions/get-active-browser-sessions"
},
{
"source": "/api-reference/api-reference/browser-profiles/create-browser-profile",
"destination": "/api-reference/browser-profiles/create-a-browser-profile"
},
{
"source": "/api-reference/api-reference/browser-profiles/list-browser-profiles",
"destination": "/api-reference/browser-profiles/list-browser-profiles"
},
{
"source": "/api-reference/api-reference/browser-profiles/get-browser-profile",
"destination": "/api-reference/browser-profiles/get-browser-profile"
},
{
"source": "/api-reference/api-reference/browser-profiles/delete-browser-profile",
"destination": "/api-reference/browser-profiles/delete-browser-profile"
},
{
"source": "/api-reference/api-reference/credentials/create-credential",
"destination": "/api-reference/credentials/create-credential"
},
{
"source": "/api-reference/api-reference/credentials/get-credential",
"destination": "/api-reference/credentials/get-credential-by-id"
},
{
"source": "/api-reference/api-reference/credentials/update-credential",
"destination": "/api-reference/credentials/create-credential"
},
{
"source": "/api-reference/api-reference/credentials/delete-credential",
"destination": "/api-reference/credentials/delete-credential"
},
{
"source": "/api-reference/api-reference/credentials/get-credentials",
"destination": "/api-reference/credentials/get-all-credentials"
},
{
"source": "/api-reference/api-reference/credentials/send-totp-code",
"destination": "/api-reference/credentials/send-totp-code"
},
{
"source": "/api-reference/api-reference/artifacts/get-run-artifacts",
"destination": "/api-reference/artifacts/get-artifacts-for-a-run"
},
{
"source": "/api-reference/api-reference/artifacts/get-artifact-content-v-1-artifacts-artifact-id-content-get",
"destination": "/api-reference/artifacts/get-an-artifact"
},
{
"source": "/api-reference/api-reference/files/upload-file",
"destination": "/api-reference/files/upload-file"
},
{
"source": "/getting-started/:slug*",
"destination": "/developers/getting-started/:slug*"
},
{
"source": "/credentials/:slug*",
"destination": "/developers/credentials/:slug*"
},
{
"source": "/debugging/:slug*",
"destination": "/developers/debugging/:slug*"
},
{
"source": "/going-to-production/:slug*",
"destination": "/developers/going-to-production/:slug*"
},
{
"source": "/optimization/:slug*",
"destination": "/developers/optimization/:slug*"
},
{
"source": "/self-hosted/:slug*",
"destination": "/developers/self-hosted/:slug*"
},
{
"source": "/features/:slug*",
"destination": "/developers/features/:slug*"
},
{
"source": "/browser-automations/:slug*",
"destination": "/developers/browser-automations/:slug*"
}
]
}
BIN
View File
Binary file not shown.

After

Width:  |  Height:  |  Size: 52 KiB

+4
View File
@@ -0,0 +1,4 @@
<svg width="32" height="32" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg">
<rect width="32" height="32" rx="6" fill="#6366F1"/>
<text x="8" y="23" font-family="system-ui, sans-serif" font-size="18" font-weight="700" fill="white">S</text>
</svg>

After

Width:  |  Height:  |  Size: 258 B

File diff suppressed because it is too large Load Diff
Binary file not shown.

After

Width:  |  Height:  |  Size: 371 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 71 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.2 MiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 12 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 39 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 37 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 56 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 29 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 142 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 139 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 24 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 46 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 88 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 156 KiB

Binary file not shown.
Binary file not shown.
Binary file not shown.

After

Width:  |  Height:  |  Size: 979 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.3 MiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.2 MiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 81 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 92 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 96 KiB

Some files were not shown because too many files have changed in this diff Show More