Skip to content

Automate browser based workflows with AI

docs: Major revamp to Developers and SDK Reference Tabs, Added Documentation for Page/Agent/Browser Methods (#5571)

Kunal Mishrae376b8a7e987
diff --git a/docs/api-reference/openapi.json b/docs/api-reference/openapi.json
index 9b36ca8f9..36255184f 100644
--- a/docs/api-reference/openapi.json
+++ b/docs/api-reference/openapi.json
@@ -2414,555 +2414,6 @@
}
}
}
- },
- "/v1/schedules": {
- "get": {
- "tags": [
- "Schedules"
- ],
- "summary": "List all schedules for the organization",
- "operationId": "schedules_list_all",
- "parameters": [
- {
- "name": "page",
- "in": "query",
- "required": false,
- "schema": {
- "type": "integer",
- "minimum": 1,
- "default": 1,
- "title": "Page"
- }
- },
- {
- "name": "page_size",
- "in": "query",
- "required": false,
- "schema": {
- "type": "integer",
- "maximum": 100,
- "minimum": 1,
- "default": 10,
- "title": "Page Size"
- }
- },
- {
- "name": "status",
- "in": "query",
- "required": false,
- "schema": {
- "enum": [
- "active",
- "paused"
- ],
- "type": "string",
- "nullable": true,
- "description": "Filter by status: 'active' or 'paused'",
- "title": "Status"
- },
- "description": "Filter by status: 'active' or 'paused'"
- },
- {
- "name": "search",
- "in": "query",
- "required": false,
- "schema": {
- "type": "string",
- "nullable": true,
- "description": "Search by workflow title or schedule name",
- "title": "Search"
- },
- "description": "Search by workflow title or schedule name"
- },
- {
- "name": "x-api-key",
- "in": "header",
- "required": false,
- "schema": {
- "type": "string",
- "nullable": true,
- "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.",
- "title": "X-Api-Key"
- },
- "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings."
- }
- ],
- "responses": {
- "200": {
- "description": "Successful Response",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/OrganizationScheduleListResponse"
- }
- }
- }
- },
- "422": {
- "description": "Validation Error",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/HTTPValidationError"
- }
- }
- }
- }
- },
- "x-fern-sdk-group-name": "agent",
- "x-fern-sdk-method-name": "list_organization_schedules"
- }
- },
- "/v1/workflows/{workflow_permanent_id}/schedules": {
- "post": {
- "tags": [
- "Schedules"
- ],
- "summary": "Create a schedule for a workflow",
- "operationId": "schedules_create",
- "parameters": [
- {
- "name": "workflow_permanent_id",
- "in": "path",
- "required": true,
- "schema": {
- "type": "string",
- "title": "Workflow Permanent Id"
- }
- },
- {
- "name": "x-api-key",
- "in": "header",
- "required": false,
- "schema": {
- "type": "string",
- "nullable": true,
- "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.",
- "title": "X-Api-Key"
- },
- "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings."
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/WorkflowScheduleUpsertRequest"
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "Successful Response",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/WorkflowScheduleResponse"
- }
- }
- }
- },
- "422": {
- "description": "Validation Error",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/HTTPValidationError"
- }
- }
- }
- }
- },
- "x-fern-sdk-group-name": "agent",
- "x-fern-sdk-method-name": "create_workflow_schedule"
- },
- "get": {
- "tags": [
- "Schedules"
- ],
- "summary": "List schedules for a workflow",
- "operationId": "schedules_list",
- "parameters": [
- {
- "name": "workflow_permanent_id",
- "in": "path",
- "required": true,
- "schema": {
- "type": "string",
- "title": "Workflow Permanent Id"
- }
- },
- {
- "name": "x-api-key",
- "in": "header",
- "required": false,
- "schema": {
- "type": "string",
- "nullable": true,
- "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.",
- "title": "X-Api-Key"
- },
- "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings."
- }
- ],
- "responses": {
- "200": {
- "description": "Successful Response",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/WorkflowScheduleListResponse"
- }
- }
- }
- },
- "422": {
- "description": "Validation Error",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/HTTPValidationError"
- }
- }
- }
- }
- },
- "x-fern-sdk-group-name": "agent",
- "x-fern-sdk-method-name": "list_workflow_schedules"
- }
- },
- "/v1/workflows/{workflow_permanent_id}/schedules/{workflow_schedule_id}": {
- "get": {
- "tags": [
- "Schedules"
- ],
- "summary": "Get a schedule by ID",
- "operationId": "schedules_get",
- "parameters": [
- {
- "name": "workflow_permanent_id",
- "in": "path",
- "required": true,
- "schema": {
- "type": "string",
- "title": "Workflow Permanent Id"
- }
- },
- {
- "name": "workflow_schedule_id",
- "in": "path",
- "required": true,
- "schema": {
- "type": "string",
- "title": "Workflow Schedule Id"
- }
- },
- {
- "name": "x-api-key",
- "in": "header",
- "required": false,
- "schema": {
- "type": "string",
- "nullable": true,
- "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.",
- "title": "X-Api-Key"
- },
- "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings."
- }
- ],
- "responses": {
- "200": {
- "description": "Successful Response",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/WorkflowScheduleResponse"
- }
- }
- }
- },
- "422": {
- "description": "Validation Error",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/HTTPValidationError"
- }
- }
- }
- }
- },
- "x-fern-sdk-group-name": "agent",
- "x-fern-sdk-method-name": "get_workflow_schedule"
- },
- "put": {
- "tags": [
- "Schedules"
- ],
- "summary": "Update a schedule",
- "operationId": "schedules_update",
- "parameters": [
- {
- "name": "workflow_permanent_id",
- "in": "path",
- "required": true,
- "schema": {
- "type": "string",
- "title": "Workflow Permanent Id"
- }
- },
- {
- "name": "workflow_schedule_id",
- "in": "path",
- "required": true,
- "schema": {
- "type": "string",
- "title": "Workflow Schedule Id"
- }
- },
- {
- "name": "x-api-key",
- "in": "header",
- "required": false,
- "schema": {
- "type": "string",
- "nullable": true,
- "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.",
- "title": "X-Api-Key"
- },
- "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings."
- }
- ],
- "requestBody": {
- "required": true,
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/WorkflowScheduleUpsertRequest"
- }
- }
- }
- },
- "responses": {
- "200": {
- "description": "Successful Response",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/WorkflowScheduleResponse"
- }
- }
- }
- },
- "422": {
- "description": "Validation Error",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/HTTPValidationError"
- }
- }
- }
- }
- },
- "x-fern-sdk-group-name": "agent",
- "x-fern-sdk-method-name": "update_workflow_schedule"
- },
- "delete": {
- "tags": [
- "Schedules"
- ],
- "summary": "Delete a schedule",
- "operationId": "schedules_delete",
- "parameters": [
- {
- "name": "workflow_permanent_id",
- "in": "path",
- "required": true,
- "schema": {
- "type": "string",
- "title": "Workflow Permanent Id"
- }
- },
- {
- "name": "workflow_schedule_id",
- "in": "path",
- "required": true,
- "schema": {
- "type": "string",
- "title": "Workflow Schedule Id"
- }
- },
- {
- "name": "x-api-key",
- "in": "header",
- "required": false,
- "schema": {
- "type": "string",
- "nullable": true,
- "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.",
- "title": "X-Api-Key"
- },
- "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings."
- }
- ],
- "responses": {
- "200": {
- "description": "Successful Response",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/DeleteScheduleResponse"
- }
- }
- }
- },
- "422": {
- "description": "Validation Error",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/HTTPValidationError"
- }
- }
- }
- }
- },
- "x-fern-sdk-group-name": "agent",
- "x-fern-sdk-method-name": "delete_workflow_schedule_route"
- }
- },
- "/v1/workflows/{workflow_permanent_id}/schedules/{workflow_schedule_id}/enable": {
- "post": {
- "tags": [
- "Schedules"
- ],
- "summary": "Enable a schedule",
- "operationId": "schedules_enable",
- "parameters": [
- {
- "name": "workflow_permanent_id",
- "in": "path",
- "required": true,
- "schema": {
- "type": "string",
- "title": "Workflow Permanent Id"
- }
- },
- {
- "name": "workflow_schedule_id",
- "in": "path",
- "required": true,
- "schema": {
- "type": "string",
- "title": "Workflow Schedule Id"
- }
- },
- {
- "name": "x-api-key",
- "in": "header",
- "required": false,
- "schema": {
- "type": "string",
- "nullable": true,
- "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.",
- "title": "X-Api-Key"
- },
- "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings."
- }
- ],
- "responses": {
- "200": {
- "description": "Successful Response",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/WorkflowScheduleResponse"
- }
- }
- }
- },
- "422": {
- "description": "Validation Error",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/HTTPValidationError"
- }
- }
- }
- }
- },
- "x-fern-sdk-group-name": "agent",
- "x-fern-sdk-method-name": "enable_workflow_schedule"
- }
- },
- "/v1/workflows/{workflow_permanent_id}/schedules/{workflow_schedule_id}/disable": {
- "post": {
- "tags": [
- "Schedules"
- ],
- "summary": "Disable a schedule",
- "operationId": "schedules_disable",
- "parameters": [
- {
- "name": "workflow_permanent_id",
- "in": "path",
- "required": true,
- "schema": {
- "type": "string",
- "title": "Workflow Permanent Id"
- }
- },
- {
- "name": "workflow_schedule_id",
- "in": "path",
- "required": true,
- "schema": {
- "type": "string",
- "title": "Workflow Schedule Id"
- }
- },
- {
- "name": "x-api-key",
- "in": "header",
- "required": false,
- "schema": {
- "type": "string",
- "nullable": true,
- "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.",
- "title": "X-Api-Key"
- },
- "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings."
- }
- ],
- "responses": {
- "200": {
- "description": "Successful Response",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/WorkflowScheduleResponse"
- }
- }
- }
- },
- "422": {
- "description": "Validation Error",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "#/components/schemas/HTTPValidationError"
- }
- }
- }
- }
- },
- "x-fern-sdk-group-name": "agent",
- "x-fern-sdk-method-name": "disable_workflow_schedule"
- }
}
},
"components": {
@@ -4512,8 +3963,8 @@
"properties": {
"file": {
"type": "string",
- "title": "File",
- "format": "binary"
+ "format": "binary",
+ "title": "File"
}
},
"type": "object",
@@ -10999,8 +10450,8 @@
},
"engine": {
"$ref": "#/components/schemas/RunEngine",
- "description": "\nThe engine that powers the agent task. The default value is `skyvern-1.0`, which is good for simple tasks like filling a form, or searching for information on Google. `skyvern-2.0` is the latest Skyvern agent that performs well with complex and multi-step tasks. The `openai-cua` engine uses OpenAI's CUA model. The `anthropic-cua` uses Anthropic's Claude Sonnet 3.7 model with the computer use tool.\n",
- "default": "skyvern-1.0"
+ "description": "\nThe engine that powers the agent task. The default value is `skyvern-2.0`, the latest Skyvern agent that performs pretty well with complex and multi-step tasks. `skyvern-1.0` is good for simple tasks like filling a form, or searching for information on Google. The `openai-cua` engine uses OpenAI's CUA model. The `anthropic-cua` uses Anthropic's Claude Sonnet 3.7 model with the computer use tool.\n",
+ "default": "skyvern-2.0"
},
"title": {
"type": "string",
@@ -14264,280 +13715,6 @@
"azure_vault"
],
"title": "CredentialType"
- },
- "DeleteScheduleResponse": {
- "properties": {
- "ok": {
- "type": "boolean",
- "title": "Ok"
- }
- },
- "type": "object",
- "required": [
- "ok"
- ],
- "title": "DeleteScheduleResponse"
- },
- "OrganizationScheduleItem": {
- "properties": {
- "workflow_schedule_id": {
- "type": "string",
- "title": "Workflow Schedule Id"
- },
- "organization_id": {
- "type": "string",
- "title": "Organization Id"
- },
- "workflow_permanent_id": {
- "type": "string",
- "title": "Workflow Permanent Id"
- },
- "workflow_title": {
- "type": "string",
- "title": "Workflow Title"
- },
- "cron_expression": {
- "type": "string",
- "title": "Cron Expression"
- },
- "timezone": {
- "type": "string",
- "title": "Timezone"
- },
- "enabled": {
- "type": "boolean",
- "title": "Enabled"
- },
- "parameters": {
- "additionalProperties": true,
- "type": "object",
- "nullable": true,
- "title": "Parameters"
- },
- "name": {
- "type": "string",
- "nullable": true,
- "title": "Name"
- },
- "description": {
- "type": "string",
- "nullable": true,
- "title": "Description"
- },
- "next_run": {
- "type": "string",
- "format": "date-time",
- "nullable": true,
- "title": "Next Run"
- },
- "created_at": {
- "type": "string",
- "format": "date-time",
- "title": "Created At"
- },
- "modified_at": {
- "type": "string",
- "format": "date-time",
- "title": "Modified At"
- }
- },
- "type": "object",
- "required": [
- "workflow_schedule_id",
- "organization_id",
- "workflow_permanent_id",
- "workflow_title",
- "cron_expression",
- "timezone",
- "enabled",
- "created_at",
- "modified_at"
- ],
- "title": "OrganizationScheduleItem",
- "description": "Compact schedule projection for the org-wide list endpoint."
- },
- "OrganizationScheduleListResponse": {
- "properties": {
- "schedules": {
- "items": {
- "$ref": "#/components/schemas/OrganizationScheduleItem"
- },
- "type": "array",
- "title": "Schedules"
- },
- "total_count": {
- "type": "integer",
- "title": "Total Count"
- },
- "page": {
- "type": "integer",
- "title": "Page"
- },
- "page_size": {
- "type": "integer",
- "title": "Page Size"
- }
- },
- "type": "object",
- "required": [
- "schedules",
- "total_count",
- "page",
- "page_size"
- ],
- "title": "OrganizationScheduleListResponse"
- },
- "WorkflowSchedule": {
- "properties": {
- "workflow_schedule_id": {
- "type": "string",
- "title": "Workflow Schedule Id"
- },
- "organization_id": {
- "type": "string",
- "title": "Organization Id"
- },
- "workflow_permanent_id": {
- "type": "string",
- "title": "Workflow Permanent Id"
- },
- "cron_expression": {
- "type": "string",
- "title": "Cron Expression"
- },
- "timezone": {
- "type": "string",
- "title": "Timezone"
- },
- "enabled": {
- "type": "boolean",
- "title": "Enabled"
- },
- "parameters": {
- "additionalProperties": true,
- "type": "object",
- "nullable": true,
- "title": "Parameters"
- },
- "temporal_schedule_id": {
- "type": "string",
- "nullable": true,
- "title": "Temporal Schedule Id"
- },
- "name": {
- "type": "string",
- "nullable": true,
- "title": "Name"
- },
- "description": {
- "type": "string",
- "nullable": true,
- "title": "Description"
- },
- "created_at": {
- "type": "string",
- "format": "date-time",
- "title": "Created At"
- },
- "modified_at": {
- "type": "string",
- "format": "date-time",
- "title": "Modified At"
- },
- "deleted_at": {
- "type": "string",
- "format": "date-time",
- "nullable": true,
- "title": "Deleted At"
- }
- },
- "type": "object",
- "required": [
- "workflow_schedule_id",
- "organization_id",
- "workflow_permanent_id",
- "cron_expression",
- "timezone",
- "enabled",
- "created_at",
- "modified_at"
- ],
- "title": "WorkflowSchedule"
- },
- "WorkflowScheduleListResponse": {
- "properties": {
- "schedules": {
- "items": {
- "$ref": "#/components/schemas/WorkflowSchedule"
- },
- "type": "array",
- "title": "Schedules"
- }
- },
- "type": "object",
- "required": [
- "schedules"
- ],
- "title": "WorkflowScheduleListResponse"
- },
- "WorkflowScheduleResponse": {
- "properties": {
- "schedule": {
- "$ref": "#/components/schemas/WorkflowSchedule"
- },
- "next_runs": {
- "items": {
- "type": "string",
- "format": "date-time"
- },
- "type": "array",
- "title": "Next Runs"
- }
- },
- "type": "object",
- "required": [
- "schedule"
- ],
- "title": "WorkflowScheduleResponse"
- },
- "WorkflowScheduleUpsertRequest": {
- "properties": {
- "cron_expression": {
- "type": "string",
- "title": "Cron Expression"
- },
- "timezone": {
- "type": "string",
- "title": "Timezone"
- },
- "enabled": {
- "type": "boolean",
- "title": "Enabled",
- "default": true
- },
- "parameters": {
- "additionalProperties": true,
- "type": "object",
- "nullable": true,
- "title": "Parameters"
- },
- "name": {
- "type": "string",
- "nullable": true,
- "title": "Name"
- },
- "description": {
- "type": "string",
- "nullable": true,
- "title": "Description"
- }
- },
- "type": "object",
- "required": [
- "cron_expression",
- "timezone"
- ],
- "title": "WorkflowScheduleUpsertRequest"
}
}
},
@@ -14552,4 +13729,4 @@
"url": "http://localhost:8000"
}
]
-}
+}
\ No newline at end of file
diff --git a/docs/browser-automations/actions-reference.mdx b/docs/browser-automations/actions-reference.mdx
new file mode 100644
index 000000000..bd3311373
--- /dev/null
+++ b/docs/browser-automations/actions-reference.mdx
@@ -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: 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="[email protected]") # selector
+await page.fill(prompt="Fill '[email protected]' in the email field") # AI
+await page.fill("#email", value="[email protected]", prompt="Fill email") # both
+```
+
+```typescript
+await page.fill("#email", "[email protected]") // selector
+await page.fill({ prompt: "Fill '[email protected]' in the email field" }) // AI
+await page.fill("#email", "[email protected]", { 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](/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](/going-to-production/webhooks). |
+| `totp_identifier` | `str` / `string` | No | Identifier for push-based TOTP. See [Handle 2FA](/credentials/handle-2fa). |
+| `totp_url` | `str` / `string` | No | Endpoint Skyvern calls to pull TOTP codes. See [Handle 2FA](/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](/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": "[email protected]", "role": "Engineer"},
+)
+
+# With a custom prompt to guide the AI
+await page.fill_form(
+ data={"name": "John Doe", "email": "[email protected]"},
+ 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": "[email protected]", "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: "[email protected]"}, # 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)
diff --git a/docs/running-automations/extract-structured-data.mdx b/docs/browser-automations/extract-structured-data.mdx
similarity index 62%
rename from docs/running-automations/extract-structured-data.mdx
rename to docs/browser-automations/extract-structured-data.mdx
index fd8991da4..32bc34d73 100644
--- a/docs/running-automations/extract-structured-data.mdx
+++ b/docs/browser-automations/extract-structured-data.mdx
@@ -1,8 +1,8 @@
---
title: Extract Structured Data
-subtitle: Get consistent, typed output from your tasks
+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: running-automations/extract-structured-data
+slug: browser-automations/extract-structured-data
keywords:
- JSON Schema
- extraction schema
@@ -15,262 +15,109 @@ keywords:
- boolean
---
-export const FIELD_TYPES = [
- { value: "string", label: "String" },
- { value: "number", label: "Number" },
- { value: "integer", label: "Integer" },
- { value: "boolean", label: "Boolean" },
-]
-
-export const SchemaBuilder = () => {
- const [schemaType, setSchemaType] = useState("single")
- const [arrayName, setArrayName] = useState("items")
- const [fields, setFields] = useState([
- { id: "1", name: "title", type: "string", description: "The title" },
- ])
- const [outputFormat, setOutputFormat] = useState("python")
- const [copied, setCopied] = useState(false)
-
- const addField = () => {
- setFields([...fields, { id: String(Date.now()), name: "", type: "string", description: "" }])
- }
-
- const removeField = (id) => {
- if (fields.length > 1) setFields(fields.filter((f) => f.id !== id))
- }
-
- const updateField = (id, key, value) => {
- setFields(fields.map((f) => (f.id === id ? { ...f, [key]: value } : f)))
- }
-
- const duplicateNames = useMemo(() => {
- const names = fields.map((f) => f.name).filter((n) => n.trim() !== "")
- const counts = {}
- for (const n of names) {
- counts[n] = (counts[n] || 0) + 1
- }
- return new Set(Object.keys(counts).filter((n) => counts[n] > 1))
- }, [fields])
-
- const schema = useMemo(() => {
- const properties = {}
- fields.forEach((field) => {
- if (field.name) {
- properties[field.name] = {
- type: field.type,
- description: field.description || `The ${field.name}`,
- }
- }
- })
- if (schemaType === "array") {
- return {
- type: "object",
- properties: {
- [arrayName]: {
- type: "array",
- description: "List of extracted items",
- items: { type: "object", properties },
- },
- },
- }
- }
- return { type: "object", properties }
- }, [fields, schemaType, arrayName])
-
- const formattedOutput = useMemo(() => {
- const jsonStr = JSON.stringify(schema, null, 2)
- if (outputFormat === "python") {
- return `data_extraction_schema=${jsonStr.replace(/: null/g, ": None").replace(/: true/g, ": True").replace(/: false/g, ": False")}`
- }
- if (outputFormat === "typescript") {
- return `data_extraction_schema: ${jsonStr}`
- }
- return `"data_extraction_schema": ${jsonStr}`
- }, [schema, outputFormat])
+import { FIELD_TYPES, SchemaBuilder } from "/snippets/schema-builder.mdx";
- const copyToClipboard = async () => {
- await navigator.clipboard.writeText(formattedOutput)
- setCopied(true)
- setTimeout(() => setCopied(false), 2000)
- }
-
- return (
- <div className="p-5 border rounded-lg mt-4 mb-4 not-prose" style={{ backgroundColor: "#f8fafc" }}>
- <div className="mb-5">
- <label className="block font-semibold mb-2 text-sm">What are you extracting?</label>
- <div className="flex gap-3">
- {[
- { value: "single", label: "Single object", desc: "Extract one item with multiple fields" },
- { value: "array", label: "List of items", desc: "Extract multiple items with the same structure" },
- ].map((type) => (
- <button
- key={type.value}
- onClick={() => setSchemaType(type.value)}
- className={`flex-1 p-3 rounded-md text-left border-2 ${schemaType === type.value ? "border-indigo-500 bg-indigo-50" : "border-gray-200 bg-white"}`}
- >
- <div className="font-medium text-sm">{type.label}</div>
- <div className="text-xs text-gray-500 mt-1">{type.desc}</div>
- </button>
- ))}
- </div>
- </div>
-
- {schemaType === "array" && (
- <div className="mb-5">
- <label className="block text-xs font-medium mb-1 text-gray-700">Array field name</label>
- <input
- type="text"
- value={arrayName}
- onChange={(e) => setArrayName(e.target.value)}
- className="w-full p-2 border rounded-md text-sm"
- placeholder="items"
- />
- </div>
- )}
-
- <div className="mb-4">
- <label className="block font-semibold mb-2 text-sm">Fields to extract</label>
- <div className="flex flex-col gap-2">
- {fields.map((field) => (
- <div key={field.id} className="flex gap-2 items-center p-3 bg-white rounded-md border">
- <input
- type="text"
- value={field.name}
- onChange={(e) => updateField(field.id, "name", e.target.value)}
- placeholder="Field name"
- className={`w-32 p-2 border rounded-md text-sm ${duplicateNames.has(field.name) ? "border-red-500 bg-red-50" : ""}`}
- title={duplicateNames.has(field.name) ? "Duplicate field name - will be overwritten in schema" : ""}
- />
- <select
- value={field.type}
- onChange={(e) => updateField(field.id, "type", e.target.value)}
- className="w-24 p-2 border rounded-md text-sm bg-white"
- >
- {FIELD_TYPES.map((t) => (
- <option key={t.value} value={t.value}>{t.label}</option>
- ))}
- </select>
- <input
- type="text"
- value={field.description}
- onChange={(e) => updateField(field.id, "description", e.target.value)}
- placeholder="Description (helps AI understand what to extract)"
- className="flex-1 p-2 border rounded-md text-sm"
- />
- <button
- onClick={() => removeField(field.id)}
- disabled={fields.length === 1}
- className={`px-2 py-1 rounded text-lg ${fields.length === 1 ? "text-gray-300 cursor-not-allowed" : "text-red-500 hover:bg-red-50"}`}
- >
- ×
- </button>
- </div>
- ))}
- </div>
- <button onClick={addField} className="w-full mt-2 p-2 border border-dashed rounded-md text-gray-500 text-sm hover:bg-gray-50">
- + Add field
- </button>
- {duplicateNames.size > 0 && (
- <div className="mt-2 p-2 bg-red-50 border border-red-200 rounded-md text-red-700 text-xs">
- Duplicate field names detected. Only the last field with each name will appear in the schema.
- </div>
- )}
- </div>
-
- <div>
- <div className="flex justify-between items-center mb-2">
- <label className="font-semibold text-sm">Generated schema</label>
- <div className="flex gap-1">
- {["python", "typescript", "curl"].map((format) => (
- <button
- key={format}
- onClick={() => setOutputFormat(format)}
- className={`px-3 py-1 rounded text-xs ${outputFormat === format ? "bg-indigo-100 border-indigo-500 border font-medium" : "bg-white border border-gray-200"}`}
- >
- {format === "curl" ? "cURL" : format.charAt(0).toUpperCase() + format.slice(1)}
- </button>
- ))}
- </div>
- </div>
- <div className="relative">
- <pre className="bg-slate-800 text-slate-200 p-4 rounded-md overflow-auto text-xs leading-relaxed">
- <code>{formattedOutput}</code>
- </pre>
- <button
- onClick={copyToClipboard}
- className={`absolute top-2 right-2 px-3 py-1 rounded text-xs text-white ${copied ? "bg-green-500" : "bg-slate-600 hover:bg-slate-500"}`}
- >
- {copied ? "Copied!" : "Copy"}
- </button>
- </div>
- </div>
- </div>
- )
-}
+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/).
-By default, Skyvern returns extracted data in whatever format makes sense for the task.
-Pass a `data_extraction_schema` to enforce a specific structure 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
-Add `data_extraction_schema` parameter to your task with a JSON Schema object:
+Pass a JSON Schema object to `page.extract` via the `schema` parameter, or to `run_task` via `data_extraction_schema`:
-<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"
+<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 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",
+ ```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",
+ },
},
},
- },
- },
-});
-```
-
-```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>
+ <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"
+ }
+ }
}
- }
- }
- }'
-```
-</CodeGroup>
+ )
+ ```
+
+ ```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.
@@ -724,6 +571,50 @@ curl -X POST "https://api.skyvern.com/v1/run/tasks" \
## 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>
@@ -810,17 +701,17 @@ If using webhooks, the same `output` field appears in the webhook payload.
<CardGroup cols={2}>
<Card
- title="Task Parameters"
+ title="Actions Reference"
icon="sliders"
- href="/running-automations/task-parameters"
+ href="/browser-automations/actions-reference"
>
- All available parameters for run_task
+ All available page actions and agent methods
</Card>
<Card
- title="Run a Task"
+ title="Build a Browser Automation"
icon="play"
- href="/running-automations/run-a-task"
+ href="/browser-automations/overview"
>
- Execute tasks and retrieve results
+ Launch a browser, navigate pages, and extract data
</Card>
</CardGroup>
diff --git a/docs/browser-automations/handle-browsers.mdx b/docs/browser-automations/handle-browsers.mdx
new file mode 100644
index 000000000..28e878153
--- /dev/null
+++ b/docs/browser-automations/handle-browsers.mdx
@@ -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: 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](/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](/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](/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](/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](/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)
diff --git a/docs/browser-automations/overview.mdx b/docs/browser-automations/overview.mdx
new file mode 100644
index 000000000..fd63ebeb3
--- /dev/null
+++ b/docs/browser-automations/overview.mdx
@@ -0,0 +1,586 @@
+---
+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: 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>
+
+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](/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](/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="[email protected]")
+
+# AI only (no selector needed, resilient to layout changes)
+await page.click(prompt="Click the 'Submit' button")
+await page.fill(prompt="Fill '[email protected]' 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="[email protected]", prompt="Fill the email field")
+```
+
+```typescript TypeScript
+// Selector only (fast, deterministic)
+await page.click("#submit-button");
+await page.fill("#email", "[email protected]");
+
+// AI only (no selector needed, resilient to layout changes)
+await page.click({ prompt: "Click the 'Submit' button" });
+await page.fill({ prompt: "Fill '[email protected]' 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", "[email protected]", { 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="[email protected]") # 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", "[email protected]"); // 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](/debugging/using-artifacts).
+
+---
+
+## Next steps
+
+<CardGroup cols={2}>
+ <Card
+ title="Actions Reference"
+ icon="list"
+ href="/browser-automations/actions-reference"
+ >
+ Every page action and agent method with parameters and return types
+ </Card>
+ <Card
+ title="Managing Browsers"
+ icon="browser"
+ href="/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>
diff --git a/docs/browser-automations/work-with-files.mdx b/docs/browser-automations/work-with-files.mdx
new file mode 100644
index 000000000..17e76e879
--- /dev/null
+++ b/docs/browser-automations/work-with-files.mdx
@@ -0,0 +1,180 @@
+---
+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: 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 |
+| `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](/debugging/using-artifacts) - access recordings, screenshots, and downloaded files from any run
diff --git a/docs/cloud/account-settings/billing-usage.mdx b/docs/cloud/account-settings/billing-usage.mdx
index ba2e5fe53..085b3578b 100644
--- a/docs/cloud/account-settings/billing-usage.mdx
+++ b/docs/cloud/account-settings/billing-usage.mdx
@@ -15,7 +15,7 @@ keywords:
- 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.
+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
@@ -104,7 +104,7 @@ A credit maps to one discrete browser action: clicking a button, typing into a f
| 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.
+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.
@@ -117,7 +117,7 @@ The **Your Current Balance** section shows your remaining dollar balance. Credit
## 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.
+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?">
diff --git a/docs/cloud/account-settings/organization-settings.mdx b/docs/cloud/account-settings/organization-settings.mdx
index 50a5bfdc7..048b53256 100644
--- a/docs/cloud/account-settings/organization-settings.mdx
+++ b/docs/cloud/account-settings/organization-settings.mdx
@@ -12,7 +12,7 @@ keywords:
- permissions
---
-Everything in Skyvern — workflows, credentials, runs, API keys — belongs to an **organization**. One is created automatically when you sign up.
+Everything in Skyvern (workflows, credentials, runs, API keys) belongs to an **organization**. One is created automatically when you sign up.
## Organization details
@@ -33,7 +33,7 @@ Click **Invite Member**, enter their email address, and send the invitation. The
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.
+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>
diff --git a/docs/cloud/account-settings/profile-settings.mdx b/docs/cloud/account-settings/profile-settings.mdx
index 4471f1f4e..1d02a0475 100644
--- a/docs/cloud/account-settings/profile-settings.mdx
+++ b/docs/cloud/account-settings/profile-settings.mdx
@@ -23,7 +23,7 @@ The **Security** tab is where you manage your password and review active session
<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.
+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.
diff --git a/docs/cloud/browser-management/browser-profiles.mdx b/docs/cloud/browser-management/browser-profiles.mdx
index 68a241e78..badca168d 100644
--- a/docs/cloud/browser-management/browser-profiles.mdx
+++ b/docs/cloud/browser-management/browser-profiles.mdx
@@ -12,7 +12,7 @@ keywords:
- 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.
+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:
@@ -28,7 +28,7 @@ Looking to manage profiles from code? See the [API & SDK guide](/optimization/br
## 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.
+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
@@ -45,7 +45,7 @@ Browser profiles are created automatically when you test a password credential w
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.
+ 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.
diff --git a/docs/cloud/browser-management/browser-sessions.mdx b/docs/cloud/browser-management/browser-sessions.mdx
index 2ccb4f2ad..7b6a9df57 100644
--- a/docs/cloud/browser-management/browser-sessions.mdx
+++ b/docs/cloud/browser-management/browser-sessions.mdx
@@ -12,7 +12,7 @@ keywords:
- 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.
+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](/optimization/browser-sessions) instead.
@@ -113,7 +113,7 @@ You can also run workflows inside an existing session:
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.
+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" />
@@ -139,9 +139,9 @@ If your steps run back-to-back with no pauses between them, a [workflow](/cloud/
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
+- **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
---
diff --git a/docs/cloud/building-workflows/add-parameters.mdx b/docs/cloud/building-workflows/add-parameters.mdx
index f5cc0b8ab..568d8d29a 100644
--- a/docs/cloud/building-workflows/add-parameters.mdx
+++ b/docs/cloud/building-workflows/add-parameters.mdx
@@ -13,7 +13,9 @@ keywords:
- 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, reference a parameter and fill in the value when you run the workflow.
+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](/browser-automations/overview) for the code-first approach.
---
diff --git a/docs/cloud/building-workflows/build-a-workflow.mdx b/docs/cloud/building-workflows/build-a-workflow.mdx
index 191b30dc0..695cfaa47 100644
--- a/docs/cloud/building-workflows/build-a-workflow.mdx
+++ b/docs/cloud/building-workflows/build-a-workflow.mdx
@@ -14,7 +14,15 @@ keywords:
- visual builder
---
-A task handles one goal on one page. When your automation needs multiple steps, you need a workflow. This page explains how workflows work, walks you through building one from scratch, and covers the editor's features.
+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](/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
diff --git a/docs/cloud/building-workflows/configure-blocks.mdx b/docs/cloud/building-workflows/configure-blocks.mdx
index 015b474a7..e042b3b6f 100644
--- a/docs/cloud/building-workflows/configure-blocks.mdx
+++ b/docs/cloud/building-workflows/configure-blocks.mdx
@@ -17,9 +17,11 @@ keywords:
- 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 [editor](/cloud/building-workflows/build-a-workflow), grouped by category.
+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.
-<Frame caption="To add a block in your workflow, click the **+** button —> click on Add block —> select the block type from the menu.">
+If you're writing automations in code instead, the equivalent operations are Page and Agent methods. See the [Actions Reference](/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>
diff --git a/docs/cloud/building-workflows/manage-workflows.mdx b/docs/cloud/building-workflows/manage-workflows.mdx
index 0a79466a9..3b2ae53b7 100644
--- a/docs/cloud/building-workflows/manage-workflows.mdx
+++ b/docs/cloud/building-workflows/manage-workflows.mdx
@@ -13,7 +13,9 @@ keywords:
- organize
---
-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.
+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](/browser-automations/overview) developer docs.
Click **Workflows** in the left sidebar to open it.
diff --git a/docs/cloud/building-workflows/run-a-workflow.mdx b/docs/cloud/building-workflows/run-a-workflow.mdx
index 25973ee33..1e8dd4b50 100644
--- a/docs/cloud/building-workflows/run-a-workflow.mdx
+++ b/docs/cloud/building-workflows/run-a-workflow.mdx
@@ -14,7 +14,9 @@ keywords:
- live execution
---
-Once you've built and saved a workflow, you can run it from the editor or the workflows list. Each run creates an independent execution with its own status, logs, and output.
+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
diff --git a/docs/cloud/building-workflows/run-from-code.mdx b/docs/cloud/building-workflows/run-from-code.mdx
new file mode 100644
index 000000000..39461761f
--- /dev/null
+++ b/docs/cloud/building-workflows/run-from-code.mdx
@@ -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](/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](/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": "[email protected]",
+ "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>
diff --git a/docs/cloud/building-workflows/scheduling.mdx b/docs/cloud/building-workflows/scheduling.mdx
index ae3c2fcae..379f718e3 100644
--- a/docs/cloud/building-workflows/scheduling.mdx
+++ b/docs/cloud/building-workflows/scheduling.mdx
@@ -14,7 +14,9 @@ keywords:
- disable
---
-You can schedule any saved workflow to run automatically on a recurring basis. Schedules are configured with a cron expression and timezone, and Skyvern triggers the workflow at each interval.
+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.
@@ -123,7 +125,7 @@ To change which workflow a schedule runs, delete the schedule and create a new o
<Card
title="Scheduling API"
icon="code"
- href="/multi-step-automations/scheduling-workflows"
+ href="/cloud/building-workflows/run-from-code#create-a-schedule"
>
Create and manage schedules programmatically
</Card>
diff --git a/docs/cloud/getting-started/ai-agents-quickstart.mdx b/docs/cloud/getting-started/ai-agents-quickstart.mdx
new file mode 100644
index 000000000..4e55a1567
--- /dev/null
+++ b/docs/cloud/getting-started/ai-agents-quickstart.mdx
@@ -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 />
diff --git a/docs/cloud/getting-started/core-concepts.mdx b/docs/cloud/getting-started/core-concepts.mdx
index 01ebe8e4d..f730fad0d 100644
--- a/docs/cloud/getting-started/core-concepts.mdx
+++ b/docs/cloud/getting-started/core-concepts.mdx
@@ -1,7 +1,7 @@
---
title: Core Concepts
subtitle: The building blocks of Skyvern automations
-description: Understand the core building blocks of Skyvern automations including tasks, workflows, blocks, browser sessions, browser profiles, and credentials in the Cloud UI.
+description: Understand the building blocks of Skyvern automations
slug: cloud/getting-started/core-concepts
keywords:
- task
diff --git a/docs/cloud/getting-started/monitor-a-run.mdx b/docs/cloud/getting-started/monitor-a-run.mdx
index 3e14ba1ce..708597deb 100644
--- a/docs/cloud/getting-started/monitor-a-run.mdx
+++ b/docs/cloud/getting-started/monitor-a-run.mdx
@@ -51,21 +51,21 @@ Once a task reaches a final state, the live stream closes. Open the run from **R
## 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.
+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.
+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
+- **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.
diff --git a/docs/cloud/getting-started/overview.mdx b/docs/cloud/getting-started/overview.mdx
index 0675a5506..1478960ad 100644
--- a/docs/cloud/getting-started/overview.mdx
+++ b/docs/cloud/getting-started/overview.mdx
@@ -2,7 +2,7 @@
title: UI Overview
slug: cloud/overview
subtitle: Navigate the Skyvern Cloud dashboard
-description: Tour the Skyvern Cloud dashboard — run tasks, build workflows, manage credentials, view results, and configure settings from the web UI.
+description: Tour the Skyvern Cloud dashboard
keywords:
- dashboard
- navigation
@@ -20,7 +20,7 @@ New to Skyvern? The [homepage](/) covers how Skyvern works under the hood, built
</Tip>
<Note>
-Looking to integrate Skyvern into your own app? See the [API Quickstart](/getting-started/quickstart) instead.
+Looking to integrate Skyvern into your own app? See the [Quickstart](/getting-started/quickstart) instead.
</Note>
## The dashboard
@@ -63,7 +63,7 @@ Every automation in Skyvern Cloud follows the same pattern:
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.
+ 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.
diff --git a/docs/running-automations/run-a-task.mdx b/docs/cloud/getting-started/run-from-code.mdx
similarity index 60%
rename from docs/running-automations/run-a-task.mdx
rename to docs/cloud/getting-started/run-from-code.mdx
index 4eceecadd..72d10d7ca 100644
--- a/docs/running-automations/run-a-task.mdx
+++ b/docs/cloud/getting-started/run-from-code.mdx
@@ -1,36 +1,30 @@
---
-title: Run a Task
-subtitle: Execute a single browser automation with natural language
-description: Create and run browser automation tasks using the Skyvern API or SDK. Configure URLs, goals, data extraction schemas, webhooks, and advanced options.
-slug: running-automations/run-a-task
+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
- - cancel_run
- polling
- wait_for_completion
- webhook
- - data extraction
- - run status
- - terminal state
+ - SDK
+ - API
---
-A **Task** is the simplest way to automate a browser action.
-
-You describe what you want in natural language, and Skyvern's AI navigates the web to complete it.
+Run tasks programmatically using the Python SDK, TypeScript SDK, or REST API.
---
-## Call `run_task`
+## 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
-
-For additional parameters like engines, proxies, and extraction schemas, see [Task Parameters](/running-automations/task-parameters).
+- **`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.
+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
@@ -106,14 +100,14 @@ curl -X POST "https://api.skyvern.com/v1/run/tasks" \
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.
+`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.
+The `run_task` call queues the task and returns immediately.
Use the `run_id` to fetch results once the task reaches a terminal state.
@@ -122,10 +116,10 @@ Use the `run_id` to fetch results once the task reaches a terminal state.
| `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 |
+| `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 |
+| `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:
@@ -271,7 +265,7 @@ The response from polling (`get_run`) and webhooks have slightly different struc
"run_request": {
"prompt": "Get the title of the top post",
"url": "https://news.ycombinator.com/",
- "engine": "skyvern-1.0"
+ "engine": "skyvern-2.0"
}
}
```
@@ -352,146 +346,12 @@ The response from polling (`get_run`) and webhooks have slightly different struc
| `proxy_location` | string | Proxy location used (e.g., `RESIDENTIAL`) |
| `webhook_callback_url` | string | The webhook URL that received this payload |
----
-
-## Get artifacts
-
-The run response contains high-level data like `output`, `recording_url`, and `screenshot_urls`.
-
-Every run also generates Artifacts, such as screenshots, reasoning logs, downloaded files, for observability. To get them, use `get_run_artifacts`.
-
-<CodeGroup>
-```python Python
-artifacts = await client.get_run_artifacts(run_id)
-
-for artifact in artifacts:
- print(f"{artifact.artifact_type}: {artifact.signed_url}")
-```
-
-```typescript TypeScript
-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>
-
-This returns a list of artifacts.
-
-**Example response:**
-
-```json
-[
- {
- "artifact_id": "a_486305284826607484",
- "artifact_type": "recording",
- "uri": "s3://skyvern-artifacts/v1/production/.../recording.webm",
- "signed_url": "https://skyvern-artifacts.s3.amazonaws.com/v1/production/.../recording.webm?...",
- "task_id": "tsk_486305246171901814",
- "step_id": "stp_486305250466869112",
- "workflow_run_id": "wr_486305187432193510",
- "workflow_run_block_id": null,
- "run_id": "tsk_v2_486305187432193504",
- "organization_id": "o_485917350850524254",
- "created_at": "2026-01-20T11:52:52.083001",
- "modified_at": "2026-01-20T11:52:52.083003"
- },
- {
- "artifact_id": "a_486305516754841578",
- "artifact_type": "screenshot_final",
- "uri": "s3://skyvern-artifacts/v1/production/.../screenshot_final.png",
- "signed_url": "https://skyvern-artifacts.s3.amazonaws.com/v1/production/.../screenshot_final.png?...",
- "task_id": "tsk_486305439445430190",
- "step_id": "stp_486305439445430192",
- "workflow_run_id": "wr_486305187432193510",
- "workflow_run_block_id": null,
- "run_id": "tsk_v2_486305187432193504",
- "organization_id": "o_485917350850524254",
- "created_at": "2026-01-20T11:53:46.468908",
- "modified_at": "2026-01-20T11:53:46.468910"
- }
-]
-```
+### Artifacts
-**Artifact fields:**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `artifact_id` | string | Unique identifier for the artifact |
-| `artifact_type` | string | Type of artifact (see table below) |
-| `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 | Associated run ID (e.g., `tsk_v2_...`) |
-| `workflow_run_id` | string \| null | Associated workflow run ID |
-| `workflow_run_block_id` | string \| null | Associated workflow block ID |
-| `organization_id` | string | Organization that owns this artifact |
-| `created_at` | datetime | When the artifact was created |
-| `modified_at` | datetime | When the artifact was last modified |
-
-**Artifact types:**
-
-| Type | Description |
-|------|-------------|
-| `recording` | Full video of the browser session |
-| `screenshot` | Screenshot captured during execution |
-| `screenshot_action` | Screenshot taken after an action |
-| `screenshot_final` | Final screenshot when task completed |
-| `screenshot_llm` | Screenshot sent to the LLM for analysis |
-| `html` | Page HTML at various points |
-| `html_scrape` | Scraped HTML content |
-| `html_action` | HTML captured after an action |
-| `har` | HTTP Archive file for network debugging |
-| `trace` | Execution trace data |
-| `pdf` | PDF files generated or downloaded |
-| `script_file` | Generated script files |
-| `browser_console_log` | Browser console output |
-| `skyvern_log` | Skyvern execution logs |
-| `skyvern_log_raw` | Raw Skyvern execution logs |
-| `llm_prompt` | Prompt sent to the LLM |
-| `llm_request` | Full request sent to the LLM |
-| `llm_response` | Response from the LLM |
-| `llm_response_parsed` | Parsed LLM response |
-| `llm_response_rendered` | Rendered LLM response |
-| `visible_elements_tree` | DOM tree of visible elements |
-| `visible_elements_tree_trimmed` | Trimmed DOM tree |
-| `visible_elements_tree_in_prompt` | DOM tree included in prompt |
-| `visible_elements_id_css_map` | CSS selector map for elements |
-| `visible_elements_id_frame_map` | Frame map for elements |
-| `visible_elements_id_xpath_map` | XPath map for elements |
-| `hashed_href_map` | Hashed href mapping |
-
-You can filter by artifact type using query parameters:
-
-```bash
-curl -X GET "https://api.skyvern.com/v1/runs/RUN_ID/artifacts?artifact_type=screenshot&artifact_type=recording" \
- -H "x-api-key: $SKYVERN_API_KEY"
-```
+Every run captures recordings, screenshots, and logs. See [Using Artifacts](/debugging/using-artifacts) for retrieval and the full artifact type reference.
---
-## Next steps
-
-<CardGroup cols={2}>
- <Card
- title="Task Parameters"
- icon="sliders"
- href="/running-automations/task-parameters"
- >
- Configure engines, proxies, extraction schemas, etc when running a task
- </Card>
- <Card
- title="Extract Structured Data"
- icon="database"
- href="/running-automations/extract-structured-data"
- >
- Define a schema to get typed JSON output from your automations
- </Card>
-</CardGroup>
+<Note>
+For multi-step automations that chain multiple actions, see [Browser Automation](/browser-automations/overview).
+</Note>
diff --git a/docs/cloud/getting-started/run-your-first-task.mdx b/docs/cloud/getting-started/run-your-first-task.mdx
index 2251f4c24..f416fb2d2 100644
--- a/docs/cloud/getting-started/run-your-first-task.mdx
+++ b/docs/cloud/getting-started/run-your-first-task.mdx
@@ -96,7 +96,7 @@ The **Extracted Information** block shows your results as structured JSON:
]
```
-Your result will differ — the #1 post changes constantly. The structure is what matters.
+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.
diff --git a/docs/cloud/managing-credentials/totp-setup.mdx b/docs/cloud/managing-credentials/totp-setup.mdx
index d90dc00bc..8a2ecb947 100644
--- a/docs/cloud/managing-credentials/totp-setup.mdx
+++ b/docs/cloud/managing-credentials/totp-setup.mdx
@@ -171,7 +171,7 @@ This turns email-based 2FA into something nearly as automated as an authenticato
## 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](/running-automations/extract-structured-data) or [workflow](/multi-step-automations/build-a-workflow), and Skyvern will call your endpoint when it needs a verification code.
+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:
@@ -203,8 +203,8 @@ def validate_skyvern_request(request) -> bool:
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.
+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
@@ -222,7 +222,7 @@ await client.run_task(
)
```
-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.
+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.
---
diff --git a/docs/cloud/viewing-results/downloading-artifacts.mdx b/docs/cloud/viewing-results/downloading-artifacts.mdx
index 70a437dd8..08163eacb 100644
--- a/docs/cloud/viewing-results/downloading-artifacts.mdx
+++ b/docs/cloud/viewing-results/downloading-artifacts.mdx
@@ -13,7 +13,7 @@ keywords:
- 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.
+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
@@ -27,7 +27,7 @@ Every run generates artifacts — video recordings, screenshots at each decision
## From the API
-Use the API when you need artifacts programmatically — for a pipeline, an archive, or integration with another tool.
+Use the API when you need artifacts programmatically: for a pipeline, an archive, or integration with another tool.
### List artifacts for a run
@@ -45,7 +45,7 @@ curl -X GET "https://api.skyvern.com/v1/runs/{run_id}/artifacts?artifact_type=sc
### Download an artifact
-Each artifact in the response includes a `signed_url` — a temporary, pre-authenticated download link:
+Each artifact in the response includes a `signed_url`, a temporary, pre-authenticated download link:
```json
{
@@ -69,17 +69,17 @@ Signed URLs expire after a short period. Always generate a fresh URL via the API
| Value | What it is |
|-------|-----------|
| `recording` | Full browser session video |
-| `screenshot_llm` | Screenshots with numbered element annotations — what the AI analyzed |
+| `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 |
+| `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 |
+| `har` | HTTP Archive file (every network request the browser made) |
| `trace` | Browser trace file for performance analysis |
<Tip>
diff --git a/docs/cloud/viewing-results/run-details.mdx b/docs/cloud/viewing-results/run-details.mdx
index 52bf112a3..d8e4a459a 100644
--- a/docs/cloud/viewing-results/run-details.mdx
+++ b/docs/cloud/viewing-results/run-details.mdx
@@ -21,9 +21,9 @@ Every run has a detail page showing what the AI saw, what it decided, what it ex
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)
+- **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.
@@ -31,7 +31,7 @@ While a run is in progress, a **Cancel** button appears instead of Rerun.
## Extracted information
-On success, the **Extracted Information** section appears above the tabs — the structured data you asked for, displayed as JSON.
+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" />
@@ -49,25 +49,25 @@ 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." |
+| **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 — a misidentified element, or a premature "goal met" conclusion.
+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.
+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.
+When you select a block in the Overview timeline, this tab also shows that block's configuration: prompt, URL, schema, and other settings.
### Recording
@@ -89,7 +89,7 @@ If the workflow uses cached code, a **Cache Key selector** lets you switch betwe
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.
+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.
@@ -100,7 +100,7 @@ Work through these in order:
|--------|---------|
| `created` | Initialized, waiting to be queued |
| `queued` | Waiting for an available browser slot |
-| `running` | Actively executing — browser stream is live |
+| `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) |
diff --git a/docs/cloud/viewing-results/run-history.mdx b/docs/cloud/viewing-results/run-history.mdx
index cea788526..fd367feba 100644
--- a/docs/cloud/viewing-results/run-history.mdx
+++ b/docs/cloud/viewing-results/run-history.mdx
@@ -22,7 +22,7 @@ The **Runs** page shows every task and workflow execution, sorted newest-first.
<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.
+**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**.
@@ -34,7 +34,7 @@ Each row is one run. The columns:
|--------|--------------|
| **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). |
+| **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. |
diff --git a/docs/cookbooks/bulk-invoice-downloader.mdx b/docs/cookbooks/bulk-invoice-downloader.mdx
index a3188695c..2e79b1dad 100644
--- a/docs/cookbooks/bulk-invoice-downloader.mdx
+++ b/docs/cookbooks/bulk-invoice-downloader.mdx
@@ -34,7 +34,7 @@ A workflow that:
## Prerequisites
-- **Skyvern Cloud API key** — Get one at [app.skyvern.com/settings](https://app.skyvern.com/settings) → API Keys
+- **Skyvern Cloud API key**: Get one at [app.skyvern.com/settings](https://app.skyvern.com/settings) → API Keys
Install the SDK:
@@ -169,7 +169,7 @@ Before defining the workflow, store the login email and password Skyvern will us
</Steps>
</Tab>
<Tab title="API / SDK">
- A **workflow definition** is a JSON or YAML file that describes your entire workflow — its metadata, parameters, and blocks.
+ A **workflow definition** is a JSON or YAML file that describes your entire workflow: its metadata, parameters, and blocks.
This definition file contains no sensitive information (like credentials or input values) and can be shared publicly. Once we make this, it can either be uploaded via the Cloud UI or sent as an input parameter to `create_workflow()`. We'll do this in Step 4.
@@ -286,12 +286,12 @@ Parameters are the inputs your workflow accepts. Defining them upfront lets you
The workflow chains together several blocks to automate the full invoice collection process:
-1. **Login block** — Authenticates to the vendor portal using stored credentials
-2. **Navigation block** — Navigates to order history and applies date filters
-3. **Extraction block** — Extracts order metadata from the filtered results
-4. **For loop + File download** — Iterates over each order and downloads its invoice PDF
-5. **For loop + File parser** — Parses each downloaded PDF to extract structured data
-6. **Send email** — Sends a summary with PDFs attached to the recipient
+1. **Login block**: Authenticates to the vendor portal using stored credentials
+2. **Navigation block**: Navigates to order history and applies date filters
+3. **Extraction block**: Extracts order metadata from the filtered results
+4. **For loop + File download**: Iterates over each order and downloads its invoice PDF
+5. **For loop + File parser**: Parses each downloaded PDF to extract structured data
+6. **Send email**: Sends a summary with PDFs attached to the recipient
In the Cloud UI, click the **+** button after the Start node to add blocks sequentially. For SDK users, add each block to the `blocks` array in your workflow definition file.
@@ -745,16 +745,16 @@ Send a summary email with PDFs attached.
<Step title="Block 1: Login">
Add a **Login** block. Set **URL** to the `portal_url` parameter. Select the `credentials` parameter. Set the goal: "Log in using the provided credentials. Handle any cookie consent popups. COMPLETE when on the account dashboard or orders page." In **Advanced Settings**, add error messages for `INVALID_CREDENTIALS` and `ACCOUNT_LOCKED`.
</Step>
- <Step title="Block 2: Navigation — filter orders">
+ <Step title="Block 2: Navigation (filter orders)">
Add a **Navigation** block. Leave **URL** empty (continues from login). Add `start_date` and `end_date` as parameter keys. Set the goal: "Navigate to Order History or My Orders. Filter orders between start_date and end_date. Click the Filter button. COMPLETE when filtered results are visible."
</Step>
- <Step title="Block 3: Extraction — order metadata">
+ <Step title="Block 3: Extraction (order metadata)">
Add an **Extraction** block. Set the goal: "Extract all visible orders: order ID, date, total amount, and status." Paste the orders JSON schema into **Data Schema**.
</Step>
- <Step title="Block 4: For Loop — download invoices">
+ <Step title="Block 4: For Loop (download invoices)">
Add a **For Loop** block. Set **Loop Variable** to `data_extraction_block_output.orders`. Enable **Continue on Failure** and **Next Loop on Failure**. Inside the loop, add a **File Download** block with goal: "Find order (current order ID). Click Download Invoice. COMPLETE when the PDF download starts." Set **Download Suffix** to `invoice_(order_id).pdf`.
</Step>
- <Step title="Block 5: For Loop — parse invoices">
+ <Step title="Block 5: For Loop (parse invoices)">
Add another **For Loop** block with the same loop variable. Inside the loop, add a **File URL Parser** block. Set **File URL** to `SKYVERN_DOWNLOAD_DIRECTORY/invoice_(order_id).pdf`, **File Type** to PDF, and paste the invoice JSON schema.
</Step>
<Step title="Block 6: Send Email">
@@ -1230,13 +1230,13 @@ Create the workflow from your definition file and execute it.
## Resources
<CardGroup cols={2}>
- <Card title="Workflow Blocks Reference" icon="cube" href="/multi-step-automations/workflow-blocks-reference">
+ <Card title="Workflow Blocks Reference" icon="cube" href="/cloud/building-workflows/configure-blocks">
Complete parameter reference for all block types
</Card>
- <Card title="Credential Management" icon="key" href="/sdk-reference/credentials">
+ <Card title="Credential Management" icon="key" href="/sdk-reference/credentials/create-credential">
Securely store and use login credentials
</Card>
- <Card title="File Operations" icon="file" href="/multi-step-automations/file-operations">
+ <Card title="File Operations" icon="file" href="/cloud/building-workflows/configure-blocks">
Download, parse, and upload files in workflows
</Card>
<Card title="Error Handling" icon="triangle-exclamation" href="/going-to-production/error-handling">
diff --git a/docs/cookbooks/healthcare-portal-data.mdx b/docs/cookbooks/healthcare-portal-data.mdx
index 3a4b4083a..41b3e1b4b 100644
--- a/docs/cookbooks/healthcare-portal-data.mdx
+++ b/docs/cookbooks/healthcare-portal-data.mdx
@@ -65,7 +65,7 @@ const result = await client.runTask({
|---------|--------|
| No proxy | Production EHR portals sit behind WAFs that block datacenter IPs |
| Login every run | Wastes steps, fragile with session complexity |
-| Vague navigation | OpenEMR uses iframes and dynamic menus — needs explicit goals |
+| Vague navigation | OpenEMR uses iframes and dynamic menus, so it needs explicit goals |
| No pagination | Only gets page 1 of multi-page results |
The sections below solve each one.
@@ -263,7 +263,7 @@ Log in once, save the browser state as a profile, and skip login on future runs.
</Tabs>
<Note>
-`persist_browser_session` is a workflow definition property — set it when creating the workflow, not when running it. See [Browser Profiles](/optimization/browser-profiles) for the full lifecycle.
+`persist_browser_session` is a workflow definition property. Set it when creating the workflow, not when running it. See [Browser Profiles](/optimization/browser-profiles) for the full lifecycle.
</Note>
---
@@ -276,8 +276,8 @@ Navigate to **Patient/Client > Finder** and extract the results table.
<Tab title="Cloud UI">
Create a workflow with two blocks:
- 1. **Navigation** block — URL: `https://demo.openemr.io/openemr/index.php`. Goal: "Click Patient/Client in the top menu, then click Finder. Click Search to display all patients."
- 2. **Extraction** block — Goal: "Extract all patient rows from the Patient Finder results table." Paste the patient schema into **Data Schema**.
+ 1. **Navigation** block, URL: `https://demo.openemr.io/openemr/index.php`. Goal: "Click Patient/Client in the top menu, then click Finder. Click Search to display all patients."
+ 2. **Extraction** block, Goal: "Extract all patient rows from the Patient Finder results table." Paste the patient schema into **Data Schema**.
On the **Start** node, set **Proxy Location** to a country (e.g., **United States**). Run the workflow.
</Tab>
@@ -410,8 +410,8 @@ Navigate to **Reports > Visits > Superbill**, set a date range, and extract the
<Tab title="Cloud UI">
Create a workflow with two blocks:
- 1. **Navigation** block — Goal: "Click Reports in the top menu, then Visits, then Superbill. Set the From date to 2020-01-01 and the To date to today. Click Submit."
- 2. **Extraction** block — Goal: "Extract all encounter rows from the Superbill report." Paste the encounter schema into **Data Schema**.
+ 1. **Navigation** block, Goal: "Click Reports in the top menu, then Visits, then Superbill. Set the From date to 2020-01-01 and the To date to today. Click Submit."
+ 2. **Extraction** block, Goal: "Extract all encounter rows from the Superbill report." Paste the encounter schema into **Data Schema**.
On the **Start** node, set **Proxy Location** to a country (e.g., **United States**). Run the workflow.
</Tab>
@@ -786,13 +786,13 @@ OpenEMR can timeout or show session-expired pages. Use `error_code_mapping` on w
</Tab>
</Tabs>
-See [Error Handling](/going-to-production/error-handling) and [CAPTCHA & Bot Detection](/going-to-production/captcha-bot-detection) for more.
+See [Error Handling](/going-to-production/error-handling) and [CAPTCHA & Bot Bypass](/features/captcha-and-bot-bypass) for more.
---
## Complete workflow
-This workflow combines everything: navigate to the Patient Finder, extract demographics, navigate to Superbill, and extract billing data — with error recovery and residential proxy.
+This workflow combines everything: navigate to the Patient Finder, extract demographics, navigate to Superbill, and extract billing data, with error recovery and residential proxy.
<Tabs>
<Tab title="Cloud UI">
@@ -800,16 +800,16 @@ This workflow combines everything: navigate to the Patient Finder, extract demog
<Step title="Create the workflow">
Go to **Workflows** and create a new workflow named "OpenEMR Daily Extract." On the **Start** node, enable **Save & Reuse Session** and set **Proxy Location** to a country (e.g., **United States**).
</Step>
- <Step title="Block 1: Navigation — open Patient Finder">
+ <Step title="Block 1: Navigation (open Patient Finder)">
Add a **Navigation** block. Set URL to `https://demo.openemr.io/openemr/index.php` and goal: "Click Patient/Client > Finder. Click Search to display all patients. If a login page appears, log in with 'admin'/'pass'." In **Advanced Settings**, enable **Error Messages** and add `{"session_expired": "Session expired, login required, or access denied page"}`.
</Step>
- <Step title="Block 2: Extraction — patient demographics">
+ <Step title="Block 2: Extraction (patient demographics)">
Add an **Extraction** block. Set goal: "Extract all patient rows from the Patient Finder results table." Paste the patient schema into **Data Schema**.
</Step>
- <Step title="Block 3: Navigation — open Superbill">
+ <Step title="Block 3: Navigation (open Superbill)">
Add another **Navigation** block. Set goal: "Click Reports > Visits > Superbill. Set From to 2020-01-01, To to today. Click Submit." Add the same error messages mapping.
</Step>
- <Step title="Block 4: Extraction — encounter billing">
+ <Step title="Block 4: Extraction (encounter billing)">
Add another **Extraction** block. Set goal: "Extract all encounter rows from the Superbill report." Paste the encounter schema into **Data Schema**.
</Step>
<Step title="Run">
@@ -1087,7 +1087,7 @@ The OpenEMR demo resets daily at 8:00 AM UTC, so profiles expire every day. In p
<Card
title="Credential Management"
icon="key"
- href="/sdk-reference/credentials"
+ href="/sdk-reference/credentials/create-credential"
>
Securely store and use login credentials
</Card>
diff --git a/docs/cookbooks/job-application-filler.mdx b/docs/cookbooks/job-application-filler.mdx
index 0c373231f..d37d6fb8d 100644
--- a/docs/cookbooks/job-application-filler.mdx
+++ b/docs/cookbooks/job-application-filler.mdx
@@ -33,7 +33,7 @@ A workflow that:
## Prerequisites
-- **Skyvern Cloud API key** — Get one at [app.skyvern.com/settings](https://app.skyvern.com/settings) → API Keys
+- **Skyvern Cloud API key**: Get one at [app.skyvern.com/settings](https://app.skyvern.com/settings) → API Keys
Install the SDK:
@@ -167,7 +167,7 @@ This makes sure your passwords are never stored in the shareable workflow defini
</Steps>
</Tab>
<Tab title="API / SDK">
- A **workflow definition** is a JSON or YAML file that describes your entire workflow — its metadata, parameters, and blocks. Create a file called `job-application-workflow.yaml` (or `.json`) with the following template:
+ A **workflow definition** is a JSON or YAML file that describes your entire workflow: its metadata, parameters, and blocks. Create a file called `job-application-workflow.yaml` (or `.json`) with the following template:
<CodeGroup>
```json JSON
@@ -259,11 +259,11 @@ Parameters are the inputs your workflow accepts. Defining them upfront lets you
The workflow chains together several blocks to automate the full job application process:
-1. **PDF Parser block** — Extracts structured data from your resume
-2. **Login block** — Authenticates to the job portal using stored credentials
-3. **Navigation block** — Searches for relevant jobs based on your resume
-4. **Extraction block** — Extracts a list of job postings from search results
-5. **For loop** (Go to URL + Extraction + Action + Extraction + Text Prompt + Navigation) — Iterates over each job to extract details, generates tailored answers using an LLM, and submits the application.
+1. **PDF Parser block**: Extracts structured data from your resume
+2. **Login block**: Authenticates to the job portal using stored credentials
+3. **Navigation block**: Searches for relevant jobs based on your resume
+4. **Extraction block**: Extracts a list of job postings from search results
+5. **For loop** (Go to URL + Extraction + Action + Extraction + Text Prompt + Navigation): Iterates over each job to extract details, generates tailored answers using an LLM, and submits the application.
In the Cloud UI, click the **+** button after the Start node to add blocks sequentially. For SDK users, add each block to the `blocks` array in your workflow definition file.
@@ -503,12 +503,12 @@ The output is accessible as `jobs_list_extraction_output.jobs` in subsequent blo
Iterate over each job posting and complete the application. This loop contains multiple blocks that work together:
-1. **goto_url** — Navigate to the job page
-2. **extraction** — Extract detailed job information
-3. **action** — Click the Apply button
-4. **extraction** — Extract application form questions
-5. **text_prompt** — Generate tailored answers using AI
-6. **navigation** — Fill out and submit the application
+1. **goto_url**: Navigate to the job page
+2. **extraction**: Extract detailed job information
+3. **action**: Click the Apply button
+4. **extraction**: Extract application form questions
+5. **text_prompt**: Generate tailored answers using AI
+6. **navigation**: Fill out and submit the application
<Tabs>
<Tab title="Cloud UI">
@@ -695,13 +695,13 @@ Iterate over each job posting and complete the application. This loop contains m
<Step title="Block 2: Login">
Add a **Login** block. Set **URL** to the `job_portal_url` parameter. Select the `credentials` parameter. Set the goal: "Log in using the provided credentials. Handle any cookie consent popups. COMPLETE when on the account dashboard or orders page."
</Step>
- <Step title="Block 3: Navigation — search for jobs">
+ <Step title="Block 3: Navigation (search for jobs)">
Add a **Navigation** block. Leave **URL** empty. Set the goal: "Search for a relevant job based on the parsed resume."
</Step>
- <Step title="Block 4: Extraction — job listings">
+ <Step title="Block 4: Extraction (job listings)">
Add an **Extraction** block. Set the goal: "Extract all visible job profiles: job page url, title, employer, location, and type." Paste the jobs JSON schema into **Data Schema**.
</Step>
- <Step title="Block 5: For Loop — apply to each job">
+ <Step title="Block 5: For Loop (apply to each job)">
Add a **For Loop** block. Set **Loop Variable** to `jobs_list_extraction_output.jobs`. Enable **Continue on Failure** and **Next Loop on Failure**. Inside the loop, add six blocks in order: **Go to URL** (job page), **Extraction** (job details), **Action** (click Apply), **Extraction** (form questions), **Text Prompt** (generate answers), **Navigation** (fill and submit the form).
</Step>
</Steps>
@@ -1146,13 +1146,13 @@ Create the workflow from your definition file and execute it.
## Resources
<CardGroup cols={2}>
- <Card title="Workflow Blocks Reference" icon="cube" href="/multi-step-automations/workflow-blocks-reference">
+ <Card title="Workflow Blocks Reference" icon="cube" href="/cloud/building-workflows/configure-blocks">
Complete parameter reference for all block types
</Card>
- <Card title="Credential Management" icon="key" href="/sdk-reference/credentials">
+ <Card title="Credential Management" icon="key" href="/sdk-reference/credentials/create-credential">
Securely store and use login credentials
</Card>
- <Card title="File Operations" icon="file" href="/multi-step-automations/file-operations">
+ <Card title="File Operations" icon="file" href="/cloud/building-workflows/configure-blocks">
Upload and parse files in workflows
</Card>
<Card title="Error Handling" icon="triangle-exclamation" href="/going-to-production/error-handling">
diff --git a/docs/cookbooks/overview.mdx b/docs/cookbooks/overview.mdx
index 9f301344e..ac08df5e4 100644
--- a/docs/cookbooks/overview.mdx
+++ b/docs/cookbooks/overview.mdx
@@ -82,14 +82,14 @@ If you're new to Skyvern workflows, start with these foundational guides:
<Card
title="Build a Workflow"
icon="hammer"
- href="/multi-step-automations/build-a-workflow"
+ href="/cloud/building-workflows/build-a-workflow"
>
Learn workflow basics: parameters, blocks, and data passing
</Card>
<Card
title="Workflow Blocks Reference"
icon="cube"
- href="/multi-step-automations/workflow-blocks-reference"
+ href="/cloud/building-workflows/configure-blocks"
>
Complete reference for all block types
</Card>
diff --git a/docs/credentials/handle-2fa.mdx b/docs/credentials/handle-2fa.mdx
index 2965e77c6..d255fa63a 100644
--- a/docs/credentials/handle-2fa.mdx
+++ b/docs/credentials/handle-2fa.mdx
@@ -26,7 +26,7 @@ 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 |
+| 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) |
@@ -420,8 +420,8 @@ Skyvern automatically detects URLs and classifies them as magic links. The autom
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
+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
---
diff --git a/docs/credentials/troubleshooting-login.mdx b/docs/credentials/troubleshooting-login.mdx
index 770c64c6c..d5c8225d7 100644
--- a/docs/credentials/troubleshooting-login.mdx
+++ b/docs/credentials/troubleshooting-login.mdx
@@ -40,7 +40,7 @@ curl -X GET "https://api.skyvern.com/v1/credentials/cred_xyz789" \
-H "x-api-key: $SKYVERN_API_KEY"
```
-2. Check workflow parameter configuration—ensure the credential parameter is linked to a Login block
+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
@@ -60,17 +60,17 @@ curl -X GET "https://api.skyvern.com/v1/credentials/cred_xyz789" \
**Solutions:**
-1. **Verify credentials work manually** — Log in to the site yourself with the same credentials
+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:
+2. **Check username format**: Some sites require email, others want a username:
```
❌ john.smith
```
-3. **Test credential retrieval** — Create a simple test task to verify Skyvern can access the credential
+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
+4. **Check for copy/paste errors**: Re-enter credentials in your vault, avoiding trailing spaces
---
@@ -85,13 +85,13 @@ curl -X GET "https://api.skyvern.com/v1/credentials/cred_xyz789" \
**Solutions:**
-1. **Skyvern handles timing automatically** — If a TOTP code has less than 20 seconds remaining, Skyvern uses the next code
+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.
+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)
+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
+4. **Retry the run**: Intermittent timing issues often resolve on retry
---
@@ -106,7 +106,7 @@ curl -X GET "https://api.skyvern.com/v1/credentials/cred_xyz789" \
**Solutions:**
-1. **Verify your push endpoint** — Check that it's receiving and forwarding codes:
+1. **Verify your push endpoint**: Check that it's receiving and forwarding codes:
```bash
# Test your Zapier/webhook endpoint manually
@@ -120,7 +120,7 @@ curl -X POST "https://api.skyvern.com/v1/credentials/totp" \
}'
```
-2. **Check `totp_identifier` matches** — The identifier in your login must exactly match what you push:
+2. **Check `totp_identifier` matches**: The identifier in your login must exactly match what you push:
```python
# These must match exactly
@@ -144,7 +144,7 @@ curl -X GET "https://api.skyvern.com/v1/credentials/totp?totp_identifier=user@ex
-H "x-api-key: $SKYVERN_API_KEY"
```
-4. **For pull-based 2FA** — Check your endpoint returns the correct format:
+4. **For pull-based 2FA**: Check your endpoint returns the correct format:
```json
{
@@ -163,7 +163,7 @@ curl -X GET "https://api.skyvern.com/v1/credentials/totp?totp_identifier=user@ex
**Solutions:**
-1. **Use residential proxies** — Many CAPTCHAs trigger on datacenter IPs:
+1. **Use residential proxies**: Many CAPTCHAs trigger on datacenter IPs:
```python
result = await client.run_task(
@@ -173,9 +173,9 @@ result = await client.run_task(
)
```
-2. **Some CAPTCHAs can be solved** — Skyvern's AI can solve simple image-based challenges
+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:
+3. **Browser profiles help**: Persistent browser state reduces CAPTCHA frequency:
```python
result = await client.login(
@@ -186,7 +186,7 @@ result = await client.login(
)
```
-4. **For persistent CAPTCHAs** — Contact [[email protected]](mailto:[email protected]) for enterprise CAPTCHA solutions
+4. **For persistent CAPTCHAs**: Contact [[email protected]](mailto:[email protected]) for enterprise CAPTCHA solutions
---
@@ -196,9 +196,9 @@ result = await client.login(
**Solutions:**
-1. **Prefer direct credentials** — SSO flows involve multiple domains and are harder to automate. If possible, use direct username/password login.
+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:
+2. **For required SSO**: Use browser sessions to maintain authentication state:
```python
# First run: Complete SSO manually or with Skyvern
@@ -216,7 +216,7 @@ result = await client.run_task(
)
```
-3. **Check for direct login options** — Many sites offer traditional login alongside SSO (often under "Other login options")
+3. **Check for direct login options**: Many sites offer traditional login alongside SSO (often under "Other login options")
---
@@ -226,7 +226,7 @@ result = await client.run_task(
**Solutions:**
-1. **Increase `max_steps`** — Multi-step logins require more navigation:
+1. **Increase `max_steps`**: Multi-step logins require more navigation:
```python
result = await client.run_task(
@@ -236,7 +236,7 @@ result = await client.run_task(
)
```
-2. **Use explicit prompts** — Guide Skyvern through the steps:
+2. **Use explicit prompts**: Guide Skyvern through the steps:
```python
result = await client.run_task(
@@ -251,10 +251,10 @@ result = await client.run_task(
```
<Tip>
-For login flows with credentials, use the `login()` method—it handles credential retrieval and 2FA automatically. Use `run_task()` only for general automation without credential management.
+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
+3. **Review recordings**: Watch the recording artifact to see exactly where the flow breaks
---
@@ -328,10 +328,10 @@ Check `llm_request` and `llm_response` artifacts to understand what the AI was t
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)
+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 [[email protected]](mailto:[email protected]) or join our [Discord](https://discord.gg/skyvern) for community help.
diff --git a/docs/debugging/faq.mdx b/docs/debugging/faq.mdx
index 4b0dc303c..2dc25ae0a 100644
--- a/docs/debugging/faq.mdx
+++ b/docs/debugging/faq.mdx
@@ -19,14 +19,14 @@ keywords:
<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
+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)
+- **`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](/debugging/troubleshooting-guide) for detailed steps.
</Accordion>
@@ -34,9 +34,9 @@ See the [Troubleshooting Guide](/debugging/troubleshooting-guide) for detailed s
<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"
+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>
@@ -98,13 +98,13 @@ result = await client.run_workflow(
)
```
-Parameters are available in prompts using `{{ parameter_name }}` syntax. See [Workflow Parameters](/multi-step-automations/workflow-parameters) for details.
+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
+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>
@@ -112,8 +112,8 @@ The AI will automatically fill the credential fields when it encounters a login
<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](/multi-step-automations/scheduling-workflows) to create, update, enable/disable, and delete schedules programmatically
+- **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](/going-to-production/webhooks) to get notified when scheduled runs complete.
</Accordion>
@@ -154,8 +154,8 @@ For local installations, run `skyvern init` to generate a local API key, which w
**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_GPT4O`, `ANTHROPIC_CLAUDE_SONNET`)
-- `SECONDARY_LLM_KEY` — Optional lightweight model for faster operations
+- `LLM_KEY`: Primary model (e.g., `OPENAI_GPT4O`, `ANTHROPIC_CLAUDE_SONNET`)
+- `SECONDARY_LLM_KEY`: Optional lightweight model for faster operations
</Accordion>
<Accordion title="How do I configure proxy settings?">
@@ -239,10 +239,10 @@ The workflow starts asynchronously. Poll the run status or configure a webhook t
<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
+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>
@@ -250,9 +250,9 @@ Watch the `recording` artifact to see exactly what happened during login.
<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
+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>
@@ -365,8 +365,8 @@ Skyvern supports OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, Gemini, and Ollam
<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
+- **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>
diff --git a/docs/debugging/observability-with-laminar.mdx b/docs/debugging/observability-with-laminar.mdx
index a0c94be0b..f1f999a86 100644
--- a/docs/debugging/observability-with-laminar.mdx
+++ b/docs/debugging/observability-with-laminar.mdx
@@ -16,11 +16,11 @@ keywords:
[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.
+- **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](/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.
+Laminar traces complement [artifacts](/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>
@@ -44,8 +44,8 @@ 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
+- 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
---
@@ -73,7 +73,7 @@ LMNR_PROJECT_API_KEY=your-laminar-api-key
## 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.
+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
@@ -143,14 +143,14 @@ Expected output:
}
```
-The task runs, the output is returned, and the full trace — every HTTP call, timing, and payload — appears in your Laminar dashboard.
+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.
+**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 — no callback setup is needed.
+**Python only:** `LaminarLiteLLMCallback` is deprecated and unnecessary. Laminar instruments LiteLLM directly, so no callback setup is needed.
</Warning>
---
@@ -165,11 +165,11 @@ When calling `run_task` or `run_workflow` through the SDK, Laminar traces the cl
| Trace data | What it shows |
|------------|---------------|
-| API request/response | The full round-trip to Skyvern's API — status, latency, payload size |
+| 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.
+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
@@ -182,7 +182,7 @@ When running Skyvern on your own infrastructure, you get deep server-side traces
| 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 |
+| Errors | Exceptions at any layer: LLM, browser, workflow engine |
---
@@ -205,7 +205,7 @@ 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.
+No code changes needed. Once the env vars are set, traces appear in your Laminar project automatically.
---
diff --git a/docs/debugging/troubleshooting-guide.mdx b/docs/debugging/troubleshooting-guide.mdx
index 7bcdb9f5c..d94d83513 100644
--- a/docs/debugging/troubleshooting-guide.mdx
+++ b/docs/debugging/troubleshooting-guide.mdx
@@ -38,11 +38,11 @@ When a run fails or produces unexpected results, this guide helps you identify t
</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
+- `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
---
@@ -91,7 +91,7 @@ curl -X GET "https://api.skyvern.com/v1/runs/$RUN_ID" \
| `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 | — |
+| `canceled` | Manually stopped | N/A |
---
@@ -216,7 +216,7 @@ See [Using Artifacts](/debugging/using-artifacts) for the full list of artifact
**Symptom:** Getting `504 Gateway Timeout` errors when creating browser sessions.
**Fix:**
-- Retry after a few seconds — usually transient
+- Retry after a few seconds; usually transient
- For self-hosted: check infrastructure resources
- If persistent, contact support with your run IDs
</Accordion>
@@ -288,9 +288,9 @@ See [Using Artifacts](/debugging/using-artifacts) for the full list of artifact
**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
+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
@@ -338,7 +338,7 @@ See [Using Artifacts](/debugging/using-artifacts) for the full list of artifact
**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 — ensure exit criteria are achievable
+- Review loop conditions to ensure exit criteria are achievable
</Accordion>
---
diff --git a/docs/debugging/using-artifacts.mdx b/docs/debugging/using-artifacts.mdx
index 98e984713..0811b84b9 100644
--- a/docs/debugging/using-artifacts.mdx
+++ b/docs/debugging/using-artifacts.mdx
@@ -15,7 +15,7 @@ keywords:
- 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.
+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.
@@ -69,7 +69,7 @@ curl -X GET "https://api.skyvern.com/v1/runs/$RUN_ID/artifacts" \
</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.
+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>
---
@@ -111,7 +111,7 @@ These show you what the browser looked like at various points.
|------|------------------|-------------|
| `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_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 |
diff --git a/docs/docs.json b/docs/docs.json
index a0644cae7..7294aacc3 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -41,7 +41,6 @@
"tab": "Home",
"pages": [
"index",
- "nav/getting-started",
"nav/cloud-ui",
"nav/developers",
"nav/cookbooks",
@@ -51,29 +50,24 @@
]
},
{
- "tab": "Getting Started",
+ "tab": "Cloud UI",
"groups": [
{
"group": "Getting Started",
"pages": [
- "getting-started/introduction",
- "getting-started/core-concepts",
- "getting-started/quickstart",
- "getting-started/ai-agents-quickstart"
+ "cloud/getting-started/introduction",
+ "cloud/getting-started/core-concepts",
+ "cloud/getting-started/ai-agents-quickstart",
+ "cloud/getting-started/overview"
]
- }
- ]
- },
- {
- "tab": "Cloud UI",
- "groups": [
+ },
{
- "group": "Getting Started",
+ "group": "Running Tasks",
"pages": [
- "cloud/getting-started/overview",
"cloud/getting-started/run-your-first-task",
"cloud/getting-started/run-a-task",
- "cloud/getting-started/monitor-a-run"
+ "cloud/getting-started/monitor-a-run",
+ "cloud/getting-started/run-from-code"
]
},
{
@@ -84,7 +78,8 @@
"cloud/building-workflows/add-parameters",
"cloud/building-workflows/configure-blocks",
"cloud/building-workflows/run-a-workflow",
- "cloud/building-workflows/scheduling"
+ "cloud/building-workflows/scheduling",
+ "cloud/building-workflows/run-from-code"
]
},
{
@@ -136,29 +131,42 @@
"tab": "Developers",
"groups": [
{
- "group": "Running Automations",
+ "group": "Getting Started",
+ "pages": [
+ "getting-started/introduction",
+ "getting-started/core-concepts",
+ "getting-started/quickstart",
+ "getting-started/ai-agents-quickstart",
+ "integrations/mcp",
+ "integrations/cli"
+ ]
+ },
+ {
+ "group": "Core Features",
"pages": [
- "running-automations/run-a-task",
- "running-automations/task-parameters",
- "running-automations/extract-structured-data"
+ "features/captcha-and-bot-bypass",
+ "features/browser-sessions",
+ "features/proxy-and-geo-targeting",
+ "features/authentication-and-2fa",
+ "features/code-caching"
]
},
{
- "group": "Handling Authentication",
+ "group": "Browser Automation",
"pages": [
- "credentials/store-credentials",
- "credentials/handle-2fa",
- "credentials/troubleshooting-login"
+ "browser-automations/overview",
+ "browser-automations/actions-reference",
+ "browser-automations/extract-structured-data",
+ "browser-automations/work-with-files",
+ "browser-automations/handle-browsers"
]
},
{
- "group": "Multi-Step Automations",
+ "group": "Handling Authentication",
"pages": [
- "multi-step-automations/build-a-workflow",
- "multi-step-automations/workflow-blocks-reference",
- "multi-step-automations/file-operations",
- "multi-step-automations/workflow-parameters",
- "multi-step-automations/scheduling-workflows"
+ "credentials/store-credentials",
+ "credentials/handle-2fa",
+ "credentials/troubleshooting-login"
]
},
{
@@ -175,10 +183,7 @@
"going-to-production/webhooks",
"going-to-production/proxy-geolocation",
"going-to-production/error-handling",
- "going-to-production/reliability-tips",
- "going-to-production/captcha-bot-detection",
- "integrations/mcp",
- "integrations/cli"
+ "going-to-production/reliability-tips"
]
},
{
@@ -224,44 +229,132 @@
},
{
"tab": "SDK Reference",
- "versions": [
+ "groups": [
{
- "version": "Python",
- "groups": [
- {
- "group": "Python SDK",
- "pages": [
- "sdk-reference/overview",
- "sdk-reference/tasks",
- "sdk-reference/workflows",
- "sdk-reference/browser-sessions",
- "sdk-reference/browser-profiles",
- "sdk-reference/credentials",
- "sdk-reference/helpers",
- "sdk-reference/error-handling",
- "sdk-reference/complete-reference"
- ]
- }
+ "group": "SDK",
+ "pages": [
+ "sdk-reference/overview",
+ "sdk-reference/error-handling",
+ "sdk-reference/complete-reference"
]
},
{
- "version": "TypeScript",
- "groups": [
+ "group": "Browser Automation",
+ "pages": [
{
- "group": "TypeScript SDK",
+ "group": "Page",
"pages": [
- "ts-sdk-reference/overview",
- "ts-sdk-reference/tasks",
- "ts-sdk-reference/workflows",
- "ts-sdk-reference/browser-sessions",
- "ts-sdk-reference/browser-profiles",
- "ts-sdk-reference/credentials",
- "ts-sdk-reference/helpers",
- "ts-sdk-reference/browser-automation",
- "ts-sdk-reference/error-handling",
- "ts-sdk-reference/complete-reference"
+ "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"
]
}
]
@@ -313,6 +406,82 @@
}
},
"redirects": [
+ {
+ "source": "/going-to-production/captcha-bot-detection",
+ "destination": "/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": "/getting-started/quickstart"
@@ -327,7 +496,7 @@
},
{
"source": "/running-tasks/run-tasks",
- "destination": "/running-automations/run-a-task"
+ "destination": "/cloud/getting-started/run-from-code"
},
{
"source": "/running-tasks/visualizing-results",
@@ -335,7 +504,7 @@
},
{
"source": "/running-tasks/cancel-runs",
- "destination": "/running-automations/run-a-task"
+ "destination": "/cloud/getting-started/run-from-code"
},
{
"source": "/running-tasks/webhooks-faq",
@@ -351,11 +520,23 @@
},
{
"source": "/running-tasks/advanced-features",
- "destination": "/running-automations/task-parameters"
+ "destination": "/sdk-reference/tasks/run-task"
},
{
"source": "/running-tasks/api-spec",
- "destination": "/running-automations/run-a-task"
+ "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": "/browser-automations/extract-structured-data"
},
{
"source": "/workflows/manage-workflows",
@@ -363,11 +544,11 @@
},
{
"source": "/workflows/workflow-blocks-details",
- "destination": "/multi-step-automations/workflow-blocks-reference"
+ "destination": "/cloud/building-workflows/configure-blocks"
},
{
"source": "/workflows/workflow-parameters",
- "destination": "/multi-step-automations/workflow-parameters"
+ "destination": "/cloud/building-workflows/add-parameters"
},
{
"source": "/workflows/run-workflows",
@@ -383,23 +564,63 @@
},
{
"source": "/workflows/introduction",
- "destination": "/multi-step-automations/build-a-workflow"
+ "destination": "/cloud/building-workflows/build-a-workflow"
},
{
"source": "/workflows/workflow-blocks",
- "destination": "/multi-step-automations/workflow-blocks-reference"
+ "destination": "/cloud/building-workflows/configure-blocks"
},
{
"source": "/workflows/creating-workflows",
- "destination": "/multi-step-automations/build-a-workflow"
+ "destination": "/cloud/building-workflows/build-a-workflow"
},
{
"source": "/workflows/getting-workflows",
- "destination": "/multi-step-automations/build-a-workflow#step-7:-get-results"
+ "destination": "/cloud/building-workflows/run-a-workflow"
},
{
"source": "/workflows/what-is-a-parameter",
- "destination": "/multi-step-automations/workflow-parameters"
+ "destination": "/cloud/building-workflows/add-parameters"
+ },
+ {
+ "source": "/multi-step-automations/overview",
+ "destination": "/browser-automations/overview"
+ },
+ {
+ "source": "/multi-step-automations/actions-reference",
+ "destination": "/browser-automations/actions-reference"
+ },
+ {
+ "source": "/multi-step-automations/extract-structured-data",
+ "destination": "/browser-automations/extract-structured-data"
+ },
+ {
+ "source": "/multi-step-automations/work-with-files",
+ "destination": "/browser-automations/work-with-files"
+ },
+ {
+ "source": "/multi-step-automations/handle-browsers",
+ "destination": "/browser-automations/handle-browsers"
+ },
+ {
+ "source": "/multi-step-automations/build-a-workflow",
+ "destination": "/browser-automations/overview"
+ },
+ {
+ "source": "/multi-step-automations/workflow-blocks-reference",
+ "destination": "/browser-automations/actions-reference"
+ },
+ {
+ "source": "/multi-step-automations/file-operations",
+ "destination": "/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",
diff --git a/docs/features/authentication-and-2fa.mdx b/docs/features/authentication-and-2fa.mdx
new file mode 100644
index 000000000..ce53f99d7
--- /dev/null
+++ b/docs/features/authentication-and-2fa.mdx
@@ -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: 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="/credentials/store-credentials"
+ >
+ Create passwords, cards, and secrets. Wire up Bitwarden, 1Password, Azure, or a custom vault.
+ </Card>
+ <Card
+ title="Handle 2FA"
+ href="/credentials/handle-2fa"
+ >
+ TOTP setup, pushed codes, polled endpoints, and magic links.
+ </Card>
+ <Card
+ title="Troubleshoot logins"
+ href="/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>
diff --git a/docs/features/browser-sessions.mdx b/docs/features/browser-sessions.mdx
new file mode 100644
index 000000000..b21cb042f
--- /dev/null
+++ b/docs/features/browser-sessions.mdx
@@ -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: 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](/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](/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="/optimization/browser-sessions"
+ >
+ Create sessions, run operations through them, and close cleanly.
+ </Card>
+ <Card
+ title="Browser profiles"
+ href="/optimization/browser-profiles"
+ >
+ Save state to reuse across days or weeks.
+ </Card>
+ <Card
+ title="Connect your local browser"
+ href="/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>
diff --git a/docs/features/captcha-and-bot-bypass.mdx b/docs/features/captcha-and-bot-bypass.mdx
new file mode 100644
index 000000000..b67874ff7
--- /dev/null
+++ b/docs/features/captcha-and-bot-bypass.mdx
@@ -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: 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](/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](/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](/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="/going-to-production/proxy-geolocation"
+ >
+ Route traffic through residential proxies in 21 countries.
+ </Card>
+ <Card
+ title="Handle 2FA"
+ href="/credentials/handle-2fa"
+ >
+ Configure TOTP, email, and SMS verification codes.
+ </Card>
+ <Card
+ title="Browser Sessions"
+ href="/optimization/browser-sessions"
+ >
+ Persist browser state across multiple runs.
+ </Card>
+ <Card
+ title="Error Handling"
+ href="/going-to-production/error-handling"
+ >
+ Map CAPTCHA and bot failures to custom error codes.
+ </Card>
+</CardGroup>
diff --git a/docs/features/code-caching.mdx b/docs/features/code-caching.mdx
new file mode 100644
index 000000000..b4f4251e3
--- /dev/null
+++ b/docs/features/code-caching.mdx
@@ -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: 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="/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="/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>
diff --git a/docs/features/proxy-and-geo-targeting.mdx b/docs/features/proxy-and-geo-targeting.mdx
new file mode 100644
index 000000000..47a1641fa
--- /dev/null
+++ b/docs/features/proxy-and-geo-targeting.mdx
@@ -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: 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](/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="/going-to-production/proxy-geolocation"
+ >
+ Full country list, `proxy_location` values, and `GeoTarget` examples.
+ </Card>
+ <Card
+ title="CAPTCHA & bot bypass"
+ href="/features/captcha-and-bot-bypass"
+ >
+ Pair residential proxies with stealth for sensitive sites.
+ </Card>
+ <Card
+ title="Browser sessions"
+ href="/optimization/browser-sessions"
+ >
+ Lock a proxy location across multiple operations in one session.
+ </Card>
+ <Card
+ title="Self-hosted proxy"
+ href="/self-hosted/proxy"
+ >
+ Bring your own proxy on self-hosted deployments.
+ </Card>
+</CardGroup>
diff --git a/docs/getting-started/ai-agents-quickstart.mdx b/docs/getting-started/ai-agents-quickstart.mdx
index 648ce69ac..2b090edf5 100644
--- a/docs/getting-started/ai-agents-quickstart.mdx
+++ b/docs/getting-started/ai-agents-quickstart.mdx
@@ -1,7 +1,7 @@
---
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.
+description: Give your AI coding assistant full browser control capabilities in one prommpt
slug: getting-started/ai-agents-quickstart
keywords:
- MCP
@@ -15,327 +15,6 @@ keywords:
- npm install
---
-export const ApiKeyPrompt = ({ children }) => {
- const [apiKey, setApiKey] = useState("");
- const [copied, setCopied] = useState(false);
- const text = typeof children === "string" ? children : String(children);
- const lines = text.split("\n");
- const indents = lines.slice(1).filter(l => l.trim()).map(l => l.match(/^(\s*)/)[1].length);
- const min = indents.length ? Math.min(...indents) : 0;
- const raw = min > 0 ? lines.map((l, i) => i === 0 ? l : l.slice(min)).join("\n") : text;
- const content = apiKey ? raw.replace(/PASTE_YOUR_API_KEY_HERE/g, apiKey) : raw;
- return (
- <div>
- <input
- type="text"
- placeholder="Paste your Skyvern API key"
- value={apiKey}
- onChange={(e) => setApiKey(e.target.value)}
- spellCheck={false}
- autoComplete="off"
- style={{
- width: "100%",
- padding: "10px 14px",
- marginBottom: "12px",
- borderRadius: "8px",
- border: "1px solid var(--border, #d1d5db)",
- fontSize: "14px",
- fontFamily: "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace",
- backgroundColor: "var(--background, transparent)",
- color: "inherit",
- outline: "none",
- boxSizing: "border-box",
- }}
- />
- <div style={{ position: "relative", borderRadius: "8px", overflow: "hidden" }}>
- <button
- onClick={async () => {
- await navigator.clipboard.writeText(content);
- setCopied(true);
- setTimeout(() => setCopied(false), 2000);
- }}
- style={{
- position: "absolute",
- top: "10px",
- right: "10px",
- padding: "4px 12px",
- fontSize: "12px",
- borderRadius: "6px",
- border: "none",
- backgroundColor: "rgba(255, 255, 255, 0.1)",
- color: "#a1a1aa",
- cursor: "pointer",
- zIndex: 1,
- }}
- >
- {copied ? "Copied!" : "Copy"}
- </button>
- <pre style={{
- margin: 0,
- padding: "16px",
- overflowX: "auto",
- fontSize: "13px",
- lineHeight: "1.7",
- backgroundColor: "#0d1117",
- color: "#e6edf3",
- }}>
- <code>{content}</code>
- </pre>
- </div>
- </div>
- );
-};
+import AIAgentsQuickstartContent from "/snippets/ai-agents-quickstart-content.mdx";
-Skyvern lets AI coding assistants (Claude Code, Cursor, Windsurf, Codex) control browsers, extract data, and run workflows.
-
-**Copy the prompt below** into your AI coding agent and you'll have a running automation in minutes.
-
-<Note>
-Looking to self-host instead? See the [local installation guide](/getting-started/quickstart) for full setup instructions.
-</Note>
-
-## 1. Get your API key
-
-Go to [app.skyvern.com/settings](https://app.skyvern.com/settings) and get your API key.
-
-<Frame>
- <img src="/images/get-api-key.png" alt="Skyvern Settings page showing the API Keys section with a masked key and reveal/copy buttons" width="500" />
-</Frame>
-
-## 2. Give this prompt to your AI coding agent
-
-Paste your API key below, then copy the prompt into your AI coding assistant.
-
-It will:
-1. install the Skyvern Python/Typescript SDK
-2. Ask what you want to automate (say "Go to Hacker News and get the top comment of the #1 post" for example)
-3. Write the code to a file, and run it.
-
-<Tabs>
-<Tab title="Python">
-
-<ApiKeyPrompt>{`Set up Skyvern for browser automation:
-
-1. Install the Skyvern Python SDK (requires Python 3.11, 3.12, or 3.13).
- If you hit version errors, use pipx to install in an isolated environment:
- pip install skyvern
- # or: pipx install skyvern
-
-2. Install all Skyvern skills into this project:
- skyvern skill copy --output .claude/skills/
-
-3. Set my API key:
- export SKYVERN_API_KEY="PASTE_YOUR_API_KEY_HERE"
-
-Now ask me what I want to automate in the browser. Suggest this as a default:
-"Go to Hacker News and get the top comment of the #1 post"
-
-After I respond, create a skyvern-tasks/ folder and save a Python file there
-using this template — replace <TASK> and <URL> with what I asked for:
-
- 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="<TASK>",
- url="<URL>",
- )
-
- print(f"Task started: {result.run_id}")
- print(f"View live: {result.app_url}")
-
- while True:
- run = await client.get_run(result.run_id)
- print(f"Status: {run.status}")
-
- if run.status in ("completed", "failed", "terminated", "timed_out", "canceled"):
- break
-
- await asyncio.sleep(5)
-
- print(f"Final status: {run.status}")
- print(f"Output: {run.output}")
- if run.recording_url:
- print(f"Recording: {run.recording_url}")
-
- asyncio.run(main())
-
-Run the file and show me the output.`}</ApiKeyPrompt>
-
-</Tab>
-<Tab title="TypeScript">
-
-<ApiKeyPrompt>{`Set up Skyvern for browser automation:
-
-1. Initialize a Node.js project (if needed) and install the Skyvern TypeScript SDK:
- npm init -y
- npm install @skyvern/client
-
-2. Set my API key:
- export SKYVERN_API_KEY="PASTE_YOUR_API_KEY_HERE"
-
-Now ask me what I want to automate in the browser. Suggest this as a default:
-"Go to Hacker News and get the top comment of the #1 post"
-
-After I respond, create a skyvern-tasks/ folder and save a TypeScript file there
-using this template — replace <TASK> and <URL> with what I asked for:
-
- 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: "<TASK>",
- url: "<URL>",
- },
- });
-
- console.log(\`Task started: \${result.run_id}\`);
- console.log(\`View live: \${result.app_url}\`);
-
- const terminalStatuses = ["completed", "failed", "terminated", "timed_out", "canceled"];
- let run;
- while (true) {
- run = await client.getRun(result.run_id);
- console.log(\`Status: \${run.status}\`);
-
- if (terminalStatuses.includes(run.status)) break;
-
- await new Promise((resolve) => setTimeout(resolve, 5000));
- }
-
- console.log(\`Final status: \${run.status}\`);
- console.log(\`Output: \${JSON.stringify(run.output, null, 2)}\`);
- if (run.recording_url) {
- console.log(\`Recording: \${run.recording_url}\`);
- }
- }
-
- main();
-
-Run the file and show me the output.`}</ApiKeyPrompt>
-
-</Tab>
-</Tabs>
-
-## 3. Next steps
-
-### Connect the MCP server
-
-Give your AI coding assistant direct browser control through natural language — no SDK code needed.
-
-<Tabs>
-<Tab title="Claude Code">
-
-```bash
-claude mcp add-json skyvern '{"type":"http","url":"https://api.skyvern.com/mcp/","headers":{"x-api-key":"YOUR_SKYVERN_API_KEY"}}' --scope user
-```
-
-</Tab>
-<Tab title="Cursor">
-
-Add to `~/.cursor/mcp.json`:
-
-```json
-{
- "mcpServers": {
- "Skyvern": {
- "type": "streamable-http",
- "url": "https://api.skyvern.com/mcp/",
- "headers": {
- "x-api-key": "YOUR_SKYVERN_API_KEY"
- }
- }
- }
-}
-```
-
-</Tab>
-<Tab title="Windsurf">
-
-Add to `~/.codeium/windsurf/mcp_config.json`:
-
-```json
-{
- "mcpServers": {
- "Skyvern": {
- "type": "streamable-http",
- "url": "https://api.skyvern.com/mcp/",
- "headers": {
- "x-api-key": "YOUR_SKYVERN_API_KEY"
- }
- }
- }
-}
-```
-
-</Tab>
-<Tab title="Codex">
-
-Add to `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.skyvern]
-url = "https://api.skyvern.com/mcp/"
-
-[mcp_servers.skyvern.http_headers]
-x-api-key = "YOUR_SKYVERN_API_KEY"
-```
-
-</Tab>
-</Tabs>
-
-### Keep building
-
-<CardGroup cols={3}>
- <Card
- title="Build a Workflow"
- icon="diagram-project"
- href="/multi-step-automations/build-a-workflow"
- >
- Chain multiple steps into a single automation with loops, conditionals, and data passing
- </Card>
- <Card
- title="Extract Structured Data"
- icon="database"
- href="/running-automations/extract-structured-data"
- >
- Define a JSON schema to get typed output from your automations
- </Card>
- <Card
- title="Handle Logins"
- icon="key"
- href="/sdk-reference/credentials"
- >
- Store credentials securely for sites that require authentication
- </Card>
- <Card
- title="Full MCP Reference"
- icon="server"
- href="/integrations/mcp"
- >
- All 33 tools, config options, local mode, and troubleshooting
- </Card>
- <Card
- title="CLI & Skills"
- icon="terminal"
- href="/integrations/cli"
- >
- Browser commands, workflow management, and the skill system
- </Card>
- <Card
- title="Use Webhooks"
- icon="webhook"
- href="/going-to-production/webhooks"
- >
- Get notified when tasks complete instead of polling
- </Card>
-</CardGroup>
+<AIAgentsQuickstartContent />
diff --git a/docs/getting-started/quickstart.mdx b/docs/getting-started/quickstart.mdx
index 2c892f787..d9c970306 100644
--- a/docs/getting-started/quickstart.mdx
+++ b/docs/getting-started/quickstart.mdx
@@ -1,24 +1,26 @@
---
-title: API Quickstart
+title: Quickstart
subtitle: Run your first browser automation in 5 minutes
-description: Run your first browser automation task with the Skyvern API. Scrape Hacker News using Python, TypeScript, or cURL in under 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: getting-started/quickstart
keywords:
- quickstart
- - 5 minutes
- - Hacker News
- - run_task
- - get_run
- - polling
+ - 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 scrape the top post from Hacker News using Skyvern's AI agent.
+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.
+Prefer a visual interface? Try the [Cloud UI](/cloud/getting-started/overview) instead. No code required.
</Note>
## Step 1: Get your API key
@@ -27,8 +29,6 @@ Prefer a visual interface? Try the [Cloud UI](/cloud/getting-started/overview) i
Sign up at [app.skyvern.com](https://app.skyvern.com) and go to [Settings](https://app.skyvern.com/settings) to copy your API key.
-When you make API calls, Skyvern spins up a cloud browser, executes your task with AI, and returns the results. You can watch the browser live at any time.
-
## Step 2: Install the SDK
<CodeGroup>
@@ -51,14 +51,9 @@ pipx install skyvern
pipx installs Python packages in isolated environments while making them globally available.
</Accordion>
-## Step 3: Run your first task
-
-Let's scrape the title of the #1 post on Hacker News. You only need two parameters:
+## Step 3: Launch a browser and extract data
-- **`prompt`** — Natural language instructions for what the AI should do. Be specific about the data you want extracted.
-- **`url`** — The starting page. Skyvern's AI will navigate from here based on your prompt.
-
-The SDK uses async/await because Skyvern spins up a cloud browser and executes your task remotely, which can take 30-60 seconds.
+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
@@ -67,42 +62,59 @@ import asyncio
from skyvern import Skyvern
async def main():
- client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
+ skyvern = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
- result = await client.run_task(
- prompt="Go to news.ycombinator.com and get the title of the #1 post",
- url="https://news.ycombinator.com",
- )
+ # 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}")
- print(f"Run ID: {result.run_id}")
- print(f"Status: {result.status}")
+ 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 { SkyvernClient } from "@skyvern/client";
+import { Skyvern } from "@skyvern/client";
async function main() {
- const client = new SkyvernClient({
- apiKey: process.env.SKYVERN_API_KEY,
- });
-
- const result = await client.runTask({
- body: {
- prompt: "Go to news.ycombinator.com and get the title of the #1 post",
- url: "https://news.ycombinator.com",
- },
- });
-
- console.log(`Run ID: ${result.run_id}`);
- console.log(`Status: ${result.status}`);
+ 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" \
@@ -113,85 +125,28 @@ curl -X POST "https://api.skyvern.com/v1/run/tasks" \
```
</CodeGroup>
-The response includes a `run_id` you'll use to check status and fetch results.
+<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](/browser-automations/overview) for the full walkthrough.
+</Info>
-## Step 4: Check the status
+## Step 4: Understand the output
-Since tasks run asynchronously, you have two options:
+`page.extract` returns the extracted data as a dict. For the Hacker News example you'll see something like:
-1. **Polling** — Periodically check the task status (shown below)
-2. **Webhooks** — Get notified when the task completes ([see webhooks guide](/going-to-production/webhooks))
-
-The code below polls every 5 seconds until the task reaches a terminal state. Once complete, `run.output` contains the extracted data as a dictionary.
-
-<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="Go to news.ycombinator.com and get the title of the #1 post",
- url="https://news.ycombinator.com",
- )
-
- run_id = result.run_id
- print(f"Task started: {run_id}")
-
- while True:
- run = await client.get_run(run_id)
- print(f"Status: {run.status}")
-
- if run.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
- break
-
- await asyncio.sleep(5)
-
- print(f"Final status: {run.status}")
- print(f"Output: {run.output}")
-
-asyncio.run(main())
+```text
+Watch live: https://app.skyvern.com/browser-session/pbs_519891155782767800
+Extracted: {'top_post_title': 'Linux kernel framework for PCIe device emulation, in userspace'}
```
-```typescript TypeScript
-import { SkyvernClient } from "@skyvern/client";
+- **`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](/browser-automations/extract-structured-data).
-async function main() {
- const client = new SkyvernClient({
- apiKey: process.env.SKYVERN_API_KEY,
- });
-
- const result = await client.runTask({
- body: {
- prompt: "Go to news.ycombinator.com and get the title of the #1 post",
- url: "https://news.ycombinator.com",
- },
- });
-
- const runId = result.run_id;
- console.log(`Task started: ${runId}`);
-
- while (true) {
- const run = await client.getRun(runId);
- console.log(`Status: ${run.status}`);
-
- 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));
- }
-}
+### If you used the cURL path
-main();
-```
+The task API is asynchronous. The POST returns a `run_id`; poll for the final result:
-```bash cURL
-RUN_ID="your_run_id_here"
+```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" \
@@ -204,73 +159,30 @@ while true; do
echo "$RESPONSE" | jq '.output'
break
fi
-
sleep 5
done
```
-</CodeGroup>
**Run states:**
-- `created` — Task initialized, not yet queued
-- `queued` — Waiting for an available browser
-- `running` — AI is navigating and executing
-- `completed` — Task finished successfully
-- `failed` — Task encountered an error
-- `terminated` — Task was manually stopped
-- `timed_out` — Task exceeded time limit
-- `canceled` — Task was cancelled before starting
-
-## Step 5: View your results
-
-When the task completes, you'll get a response like this:
-
-```json
-{
- "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/v1/production/.../screenshot_final.png?..."],
- "app_url": "https://app.skyvern.com/runs/wr_486305187432193510",
- "step_count": 2,
- "run_type": "task_v2"
-}
-```
+- `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
-The `output` contains whatever data the AI extracted based on your prompt. The `app_url` links to the Cloud UI where you can view the full run details.
+## Step 5: Watch the recording
-## Step 6: Watch the recording
+Every run is recorded. Two ways to access it:
-Every task is recorded. There are two ways to access recordings:
+### Live
-### From the API response
+While the script runs, the `Watch live: ...` URL printed in Step 3 streams the browser in real time.
-The `recording_url` field is included in every completed run response:
+### After the run
-```json
-{
- "run_id": "tsk_v2_486305187432193504",
- "status": "completed",
- "recording_url": "https://skyvern-artifacts.s3.amazonaws.com/v1/production/o_485917350850524254/tsk_.../recording.webm?AWSAccessKeyId=...&Signature=...&Expires=..."
-}
-```
-
-### From the Cloud UI
-
-Navigate to [Runs](https://app.skyvern.com/runs) and click on your run to see the Recording tab.
+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" />
-### What you'll see
-
-- **Live browser view** — Watch the AI navigate in real-time
-- **Recording** — Full video replay of the session
-- **Actions** — Step-by-step breakdown with screenshots
-- **AI Reasoning** — See why the AI made each decision
-
This is invaluable for debugging and understanding how Skyvern interprets your prompts.
---
@@ -352,9 +264,9 @@ skyvern run server
<img src="/images/skyvern-run-server.gif" alt="Skyvern local server logs" />
</p>
-### Run a task locally
+### Run locally
-The only difference from cloud is the `base_url` parameter pointing to your local server. The API is identical, so the same code works in both environments — develop locally, deploy to cloud without changes.
+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
@@ -362,17 +274,20 @@ import asyncio
from skyvern import Skyvern
async def main():
- client = Skyvern(
+ skyvern = Skyvern(
base_url="http://localhost:8000",
- api_key=os.getenv("SKYVERN_API_KEY")
+ api_key=os.getenv("SKYVERN_API_KEY"),
)
- result = await client.run_task(
- prompt="Go to news.ycombinator.com and get the title of the #1 post",
- url="https://news.ycombinator.com",
- )
+ browser = await skyvern.launch_local_browser()
+ page = await browser.get_working_page()
- print(f"Run ID: {result.run_id}")
+ 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())
```
@@ -390,24 +305,38 @@ If you also selected Claude Code during setup, start your local frontend dev ser
## Next steps
<CardGroup cols={2}>
+ <Card
+ title="Build a Browser Automation"
+ icon="browser"
+ href="/browser-automations/overview"
+ >
+ The full Page/Agent/Browser walkthrough: AI actions, Playwright selectors, and agent tasks
+ </Card>
+ <Card
+ title="Actions Reference"
+ icon="list"
+ href="/browser-automations/actions-reference"
+ >
+ Every page action and agent method with parameters and return types
+ </Card>
<Card
title="Extract Structured Data"
icon="database"
- href="/running-automations/extract-structured-data"
+ href="/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"
+ href="/sdk-reference/credentials/create-credential"
>
Store credentials securely for sites that require authentication
</Card>
<Card
title="Build Workflows"
icon="diagram-project"
- href="/multi-step-automations/build-a-workflow"
+ href="/cloud/building-workflows/build-a-workflow"
>
Chain multiple steps together for complex automations
</Card>
diff --git a/docs/going-to-production/captcha-bot-detection.mdx b/docs/going-to-production/captcha-bot-detection.mdx
deleted file mode 100644
index f29d17250..000000000
--- a/docs/going-to-production/captcha-bot-detection.mdx
+++ /dev/null
@@ -1,165 +0,0 @@
----
-title: CAPTCHA & Bot Detection
-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: going-to-production/captcha-bot-detection
-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.
-
-However, CAPTCHA solving is not guaranteed. Skyvern's solvers can fail on novel challenges or rate-limited IPs.
-
-This guide helps you detect CAPTCHA failures and implement fallbacks to keep your automation running smoothly.
-
-**Supported CAPTCHA types:**
-
-| Type | Examples |
-|------|----------|
-| `RECAPTCHA` | Google reCAPTCHA v2, v3 |
-| `HCAPTCHA` | hCaptcha checkbox, image challenges |
-| `CLOUDFLARE` | Cloudflare Turnstile, Challenge pages |
-| `FUNCAPTCHA` | FunCaptcha / ArkoseLabs |
-| `MTCAPTCHA` | MTCaptcha |
-| `TEXT_CAPTCHA` | Distorted text/number images with an input field |
-| `OTHER` | Unrecognized CAPTCHA types |
-
----
-
-## Use [`error_code_mapping`](/going-to-production/error-handling#step-3-use-error_code_mapping)
-
-When a CAPTCHA blocks your automation, this gives you a consistent error code instead of parsing free-text failure messages.
-
-<CodeGroup>
-```python Python
-result = await client.run_task(
- prompt="Submit the application form. COMPLETE when you see confirmation.",
- url="https://example.com/apply",
- error_code_mapping={
- "cant_solve_captcha": "return this error if captcha isn't solved after multiple retries",
- },
-)
-```
-
-```typescript TypeScript
-const result = await client.runTask({
- body: {
- prompt: "Submit the application form. COMPLETE when you see confirmation.",
- url: "https://example.com/apply",
- error_code_mapping: {
- cant_solve_captcha: "return this error if captcha isn't solved after multiple retries",
- },
- },
-});
-```
-
-```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": "Submit the application form. COMPLETE when you see confirmation.",
- "url": "https://example.com/apply",
- "error_code_mapping": {
- "cant_solve_captcha": "return this error if captcha isn't solved after multiple retries"
- }
- }'
-```
-</CodeGroup>
-
-When a CAPTCHA blocks the run, the response includes `output.error = "cant_solve_captcha"`. You can branch your logic on this code.
-
-<Info>
-For more on error code mapping and handling failures programmatically, see [Error Handling](/going-to-production/error-handling).
-</Info>
-
-## Take Control from the browser stream
-
-In the Cloud UI, head to Runs > Click on *your run* > Click on the "Take Control" button over the browser stream.
-
-This lets you manually solve CAPTCHAs.
-
-<img src="/images/take-control.png" />
-
-Release control when you're done and the agent resumes from where you left off.
-
----
-
-## Built-in bot detection avoidance
-
-Skyvern automatically configures the browser to reduce bot detection triggers. These protections apply to every run. No configuration needed.
-
-- **`AutomationControlled` disabled**: Removes the Blink feature flag that marks the browser as automated
-- **`navigator.webdriver` hidden**: The `enable-automation` flag is suppressed so JavaScript detection scripts don't see a webdriver
-- **Viewport and user agent**: Set to match real consumer browsers
-- **Locale and timezone**: Automatically matched to the proxy location (see [Proxy & Geolocation](/going-to-production/proxy-geolocation))
-
----
-
-## Reducing detection risk
-
-Beyond fingerprinting, how you structure your automation affects detection:
-
-- **Use residential proxies for sensitive sites**: Datacenter IPs are the most common bot signal. Residential proxies route through real ISP addresses. Set `proxy_location="RESIDENTIAL"` or use `RESIDENTIAL_ISP` for static IPs.
-- **Reuse browser sessions for multi-step flows**: Creating a fresh browser for every step looks suspicious. A persistent session maintains cookies, cache, and history. See [Browser Sessions](/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](/optimization/browser-profiles).
-- **Add wait blocks between rapid actions**: Instant actions can trigger behavioral detection. A short pause between steps looks more human.
-
-### If you get blocked
-
-- **Increase `max_steps`**: Some bot challenges (like Cloudflare) loop through multiple verification pages. More steps give the solver more attempts.
-- **Switch to a residential proxy**: `RESIDENTIAL_ISP` provides a static IP that services are more likely to trust.
-- **Use a browser profile that previously passed**: If a profile has already cleared a Cloudflare challenge on a domain, it's more likely to pass again.
-- **Load Chrome extensions**: Extensions can add additional stealth capabilities. Set `EXTENSIONS` and `EXTENSIONS_BASE_PATH` in your environment.
-
----
-
-## Self-hosted deployments
-
-Automatic CAPTCHA solving is not available for self-hosted deployments.
-
-Instead, 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.
-
----
-
-## Next steps
-
-<CardGroup cols={2}>
- <Card
- title="Proxy & Geolocation"
- icon="globe"
- href="/going-to-production/proxy-geolocation"
- >
- Route traffic through residential proxies in 19 countries
- </Card>
- <Card
- title="Handle 2FA"
- icon="lock"
- href="/credentials/handle-2fa"
- >
- Configure TOTP, email, and SMS verification codes
- </Card>
- <Card
- title="Browser Sessions"
- icon="window-restore"
- href="/optimization/browser-sessions"
- >
- Persist browser state across multiple runs
- </Card>
- <Card
- title="Error Handling"
- icon="triangle-exclamation"
- href="/going-to-production/error-handling"
- >
- Map CAPTCHA and bot failures to custom error codes
- </Card>
-</CardGroup>
diff --git a/docs/going-to-production/error-handling.mdx b/docs/going-to-production/error-handling.mdx
index 6df479ffd..6628528d7 100644
--- a/docs/going-to-production/error-handling.mdx
+++ b/docs/going-to-production/error-handling.mdx
@@ -37,7 +37,7 @@ Every run transitions through these states:
| `created` | Run initialized, not yet queued |
| `queued` | Waiting for an available browser |
| `running` | AI is navigating and executing |
-| `completed` | Success—check `output` for results |
+| `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 |
@@ -206,13 +206,13 @@ done
```
</CodeGroup>
-**`failed` vs `terminated`:** A `failed` run hit infrastructure problems—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.
+**`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.
+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:
@@ -326,7 +326,7 @@ fi
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—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.
+**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
@@ -383,7 +383,7 @@ curl -X POST "https://api.skyvern.com/v1/run/tasks" \
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.
+The JSON examples below include comments (`//`) for clarity. Remove comments before using in actual workflow definitions; JSON does not support comments.
</Note>
<CodeGroup>
@@ -520,7 +520,7 @@ async def run_with_error_handling(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
+ # Expected condition: no invoice for this period
return {"success": False, "reason": "no_invoice", "date": invoice_date}
elif error_code == "maintenance":
@@ -529,7 +529,7 @@ async def run_with_error_handling(retries=1):
return {"success": False, "reason": "scheduled_retry"}
else:
- # Unknown error—log and alert
+ # Unknown error: log and alert
log_error(run_id, run.failure_reason)
return {"success": False, "reason": "unknown", "details": run.failure_reason}
```
@@ -594,7 +594,7 @@ async function runWithErrorHandling(retries = 1) {
## 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.
+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:
diff --git a/docs/going-to-production/proxy-geolocation.mdx b/docs/going-to-production/proxy-geolocation.mdx
index 37abf490f..365088749 100644
--- a/docs/going-to-production/proxy-geolocation.mdx
+++ b/docs/going-to-production/proxy-geolocation.mdx
@@ -256,7 +256,7 @@ export const PROXY_LOCATIONS = [
{ code: "JP", name: "Japan", value: "RESIDENTIAL_JP", timezone: "Asia/Tokyo", flag: "🇯🇵" },
{ code: "AU", name: "Australia", value: "RESIDENTIAL_AU", timezone: "Australia/Sydney", flag: "🇦🇺" },
{ code: "NZ", name: "New Zealand", value: "RESIDENTIAL_NZ", timezone: "Pacific/Auckland", flag: "🇳🇿" },
- { code: "NONE", name: "No Proxy", value: "NONE", timezone: "—", flag: "🚫" },
+ { code: "NONE", name: "No Proxy", value: "NONE", timezone: "N/A", flag: "🚫" },
]
export const AVAILABLE_COUNTRIES = ["US", "CA", "MX", "AR", "BR", "GB", "IE", "NL", "DE", "FR", "ES", "IT", "TR", "ZA", "IN", "PH", "KR", "SA", "JP", "AU", "NZ"]
@@ -417,7 +417,7 @@ export const ProxyMapSelector = () => {
)
}
-Many websites serve different content based on your location—prices in local currency, region-locked inventory, or outright access blocks. Others detect and block datacenter IPs, treating them as bots. Skyvern's residential proxy network routes your browser through real consumer IP addresses in 20 countries, so sites see a legitimate local visitor.
+Many websites serve different content based on your location: prices in local currency, region-locked inventory, or outright access blocks. Others detect and block datacenter IPs, treating them as bots. Skyvern's residential proxy network routes your browser through real consumer IP addresses in 20 countries, so sites see a legitimate local visitor.
<Note>
Proxy routing is only available in Skyvern Cloud. Self-hosted deployments require your own proxy infrastructure.
@@ -532,10 +532,10 @@ curl -X POST "https://api.skyvern.com/v1/run/workflows" \
```
</CodeGroup>
-For browser sessions, set `proxy_location` at creation. All tasks in that session use the same proxy IP, which matters for sites that track IP consistency across a login session—switching IPs mid-session often triggers security warnings or logouts.
+For browser sessions, set `proxy_location` at creation. All tasks in that session use the same proxy IP, which matters for sites that track IP consistency across a login session. Switching IPs mid-session often triggers security warnings or logouts.
<Warning>
-**Browser profiles don't store proxy settings.** Profiles save cookies, localStorage, and authentication state—but not the proxy used to create them. When reusing a profile, explicitly set `proxy_location` to match the original session, or sites may detect the IP mismatch and invalidate your session.
+**Browser profiles don't store proxy settings.** Profiles save cookies, localStorage, and authentication state, but not the proxy used to create them. When reusing a profile, explicitly set `proxy_location` to match the original session, or sites may detect the IP mismatch and invalidate your session.
</Warning>
<CodeGroup>
@@ -601,11 +601,11 @@ Use these enum values for country-level targeting. Each routes through a residen
| `RESIDENTIAL_SA` | Saudi Arabia | Asia/Riyadh |
| `RESIDENTIAL_TR` | Türkiye | Europe/Istanbul |
| `RESIDENTIAL_ZA` | South Africa | Africa/Johannesburg |
-| `NONE` | No proxy | — |
+| `NONE` | No proxy | N/A |
- `RESIDENTIAL` is the default. It routes traffic through a random US residential IP.
- `RESIDENTIAL_ISP` uses static ISP IPs instead of rotating residential IPs. Useful for sites that distrust rotating pools or require consistent IP addresses across requests.
-- `NONE` disables proxy routing entirely—traffic originates from Skyvern's US datacenters. Useful for testing or internal tools.
+- `NONE` disables proxy routing entirely. Traffic originates from Skyvern's US datacenters. Useful for testing or internal tools.
<Note>
**Default behavior:** If you don't specify `proxy_location`, Skyvern uses `RESIDENTIAL` which routes through a random US residential IP. Each request may get a different IP from the pool. For consistent IPs, use `RESIDENTIAL_ISP` or browser sessions.
@@ -632,7 +632,7 @@ Use these enum values for country-level targeting. Each routes through a residen
### State and city targeting
-For granular targeting—a specific US state, a city, or a country not in the presets—pass a `GeoTarget` object instead of an enum.
+For granular targeting (a specific US state, a city, or a country not in the presets), pass a `GeoTarget` object instead of an enum.
<CodeGroup>
```python Python
@@ -725,7 +725,7 @@ curl -X POST "https://api.skyvern.com/v1/run/tasks" \
| Site still blocks requests | Bot detection beyond IP geolocation (fingerprinting, behavioral analysis) | Use `RESIDENTIAL_ISP` for static IPs, match proxy to site's region, add `wait` blocks between actions |
| Need to debug proxy issues | Isolate whether proxy is causing failures | Set `proxy_location: "NONE"` to bypass proxy entirely |
-For sites with aggressive bot detection, combine residential proxies with the techniques in [Captcha & Bot Detection](/going-to-production/captcha-bot-detection).
+For sites with aggressive bot detection, combine residential proxies with the techniques in [CAPTCHA & Bot Bypass](/features/captcha-and-bot-bypass).
Need a location that's not available? Get help in the [Skyvern Discord community](https://discord.gg/skyvern) to request new proxy pools.
@@ -737,7 +737,7 @@ Need a location that's not available? Get help in the [Skyvern Discord community
<Card
title="Captcha & Bot Detection"
icon="robot"
- href="/going-to-production/captcha-bot-detection"
+ href="/features/captcha-and-bot-bypass"
>
Combine proxies with anti-detection techniques
</Card>
diff --git a/docs/going-to-production/reliability-tips.mdx b/docs/going-to-production/reliability-tips.mdx
index c10e3e71a..74932f28a 100644
--- a/docs/going-to-production/reliability-tips.mdx
+++ b/docs/going-to-production/reliability-tips.mdx
@@ -24,10 +24,10 @@ The difference between a demo and production-ready automation is reliability. Th
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
+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.
@@ -45,10 +45,10 @@ TERMINATE if you see an error message or the form cannot be submitted.
**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—make clear that submission is part of the goal.
+**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"—there might be multiple buttons, and visual context helps the AI pick the right one. Describe position, color, icons, and surrounding text.
+**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.
@@ -70,13 +70,13 @@ TERMINATE if you see an error message or the form cannot be submitted.
### 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.
+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—don't modify it further."
+**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.
@@ -99,9 +99,9 @@ Multi-select fields (where you pick several options from a list) are slower and
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.
+**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.
+**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.
@@ -109,7 +109,7 @@ Skyvern offers three block types with different tradeoffs between reliability an
**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—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.
+**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.
---
@@ -160,7 +160,7 @@ 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.
+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
@@ -206,14 +206,14 @@ if result.output["submitted_email"] != expected_email:
```
<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.
+**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>
---
## ForLoop 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.
+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.
### Always set `continue_on_failure`
@@ -259,15 +259,15 @@ loop_blocks:
## 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.
+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
+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
@@ -297,13 +297,13 @@ Direct keyboard shortcuts (Ctrl+C, Alt+Tab, Esc, etc.) are not currently support
| **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—no workaround needed |
+| **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
+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
@@ -322,10 +322,10 @@ For applications that genuinely require keyboard shortcuts with no UI alternativ
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
+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
@@ -337,7 +337,7 @@ When a run fails:
| **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 |
+| **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 |
@@ -369,7 +369,7 @@ When a run fails:
<Card
title="Workflow Blocks Reference"
icon="cube"
- href="/multi-step-automations/workflow-blocks-reference"
+ href="/cloud/building-workflows/configure-blocks"
>
Detailed documentation for validation and other blocks
</Card>
diff --git a/docs/going-to-production/webhooks.mdx b/docs/going-to-production/webhooks.mdx
index 84f04df05..870aae8c6 100644
--- a/docs/going-to-production/webhooks.mdx
+++ b/docs/going-to-production/webhooks.mdx
@@ -156,7 +156,7 @@ curl -X POST "https://api.skyvern.com/v1/run/workflows" \
</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.
+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:**
@@ -168,7 +168,7 @@ When creating a workflow, use `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.
+**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>
---
@@ -262,8 +262,8 @@ User-Agent: python-httpx/0.28.1
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
+- `x-skyvern-signature`: HMAC-SHA256 signature of the payload
+- `x-skyvern-timestamp`: Unix timestamp when the webhook was sent
- `Content-Type: application/json`
<CodeGroup>
@@ -377,7 +377,7 @@ Never use simple equality operators (`==` or `===`) for signature comparison as
## 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.
+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
@@ -457,10 +457,10 @@ Even when webhook delivery fails, the task's `output` field may still contain ex
**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.
+- **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.
@@ -469,7 +469,7 @@ Even when webhook delivery fails, the task's `output` field may still contain ex
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.
+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>
@@ -509,14 +509,14 @@ curl -X POST "https://api.skyvern.com/v1/runs/tsk_v2_486305187432193504/retry_we
</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.
+`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.
+**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.
+You can pass a different `webhook_url` to send the payload to a new endpoint; useful if the original URL was misconfigured.
---
diff --git a/docs/index.mdx b/docs/index.mdx
index a6e3bf47f..1aba29be4 100644
--- a/docs/index.mdx
+++ b/docs/index.mdx
@@ -14,7 +14,7 @@ mode: custom
<div className="sk-hero-left">
<div style={{ display: "flex", alignItems: "center", gap: "12px", marginBottom: "12px" }}>
<p className="sk-mono sk-label" style={{ margin: "0" }}>DOCUMENTATION</p>
- <a href="/docs/changelog" className="sk-version-badge">v1.0.22 — latest</a>
+ <a href="/docs/changelog" className="sk-version-badge">v1.0.22 (latest)</a>
</div>
<h1 className="sk-hero-title">
Automate any<br />browser workflow<br /><span className="sk-hero-accent">with AI.</span>
@@ -52,11 +52,11 @@ mode: custom
</div>
</div>
-{/* ===== BENTO GRID — 3 PERSONA LANES ===== */}
+{/* ===== BENTO GRID: 3 PERSONA LANES ===== */}
<div className="sk-bento-row sk-bento-3col">
<div className="sk-bento-cell">
- <p className="sk-mono sk-label">01 — NO CODE</p>
+ <p className="sk-mono sk-label">01 / NO CODE</p>
<h3 className="sk-cell-title">Automate without code</h3>
<p className="sk-cell-desc">Use the dashboard to run tasks and build workflows visually.</p>
<div className="sk-cell-links">
@@ -67,18 +67,17 @@ mode: custom
</div>
</div>
<div className="sk-bento-cell">
- <p className="sk-mono sk-label">02 — API</p>
+ <p className="sk-mono sk-label">02 / API</p>
<h3 className="sk-cell-title">Build with the API</h3>
<p className="sk-cell-desc">Integrate browser automation into your product with Python, TypeScript, or REST.</p>
<div className="sk-cell-links">
<a href="/docs/getting-started/quickstart" className="sk-cell-link">API quickstart <span className="sk-arrow">↗</span></a>
- <a href="/docs/sdk-reference/overview" className="sk-cell-link">Python SDK <span className="sk-arrow">↗</span></a>
- <a href="/docs/ts-sdk-reference/overview" className="sk-cell-link">TypeScript SDK <span className="sk-arrow">↗</span></a>
+ <a href="/docs/sdk-reference/overview" className="sk-cell-link">SDK reference <span className="sk-arrow">↗</span></a>
<a href="/docs/api-reference" className="sk-cell-link">API reference <span className="sk-arrow">↗</span></a>
</div>
</div>
<div className="sk-bento-cell">
- <p className="sk-mono sk-label">03 — SELF-HOST</p>
+ <p className="sk-mono sk-label">03 / SELF-HOST</p>
<h3 className="sk-cell-title">Self-host</h3>
<p className="sk-cell-desc">Run Skyvern on your own infrastructure with your own LLM keys.</p>
<div className="sk-cell-links">
@@ -90,7 +89,7 @@ mode: custom
</div>
</div>
-{/* ===== BENTO GRID — 2 COL: HOW IT WORKS + CONCEPTS ===== */}
+{/* ===== BENTO GRID: 2 COL: HOW IT WORKS + CONCEPTS ===== */}
<div className="sk-bento-row sk-bento-2col">
<a href="/docs/getting-started/introduction" className="sk-bento-cell sk-bento-cell-link">
@@ -107,7 +106,7 @@ mode: custom
</a>
</div>
-{/* ===== BENTO GRID — 4 COL: USE CASES ===== */}
+{/* ===== BENTO GRID: 4 COL: USE CASES ===== */}
<p className="sk-mono sk-label" style={{ marginBottom: "24px", marginTop: "32px" }}>USE CASES</p>
@@ -147,7 +146,7 @@ mode: custom
</div>
<div className="sk-bento-row sk-bento-4col">
- <a href="/docs/multi-step-automations/build-a-workflow" className="sk-bento-cell sk-bento-cell-link sk-bento-cell-sm sk-usecase-orange">
+ <a href="/docs/cloud/building-workflows/build-a-workflow" className="sk-bento-cell sk-bento-cell-link sk-bento-cell-sm sk-usecase-orange">
<span className="sk-usecase-icon">
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><circle cx="9" cy="21" r="1"/><circle cx="20" cy="21" r="1"/><path d="M1 1h4l2.68 13.39a2 2 0 0 0 2 1.61h9.72a2 2 0 0 0 2-1.61L23 6H6"/></svg>
</span>
@@ -163,7 +162,7 @@ mode: custom
<p className="sk-cell-desc-sm">Navigate complex government websites to register accounts or file forms.</p>
<span className="sk-mono sk-arrow-sm">↗</span>
</a>
- <a href="/docs/multi-step-automations/workflow-blocks-reference" className="sk-bento-cell sk-bento-cell-link sk-bento-cell-sm sk-usecase-orange">
+ <a href="/docs/cloud/building-workflows/configure-blocks" className="sk-bento-cell sk-bento-cell-link sk-bento-cell-sm sk-usecase-orange">
<span className="sk-usecase-icon">
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/></svg>
</span>
diff --git a/docs/integrations/cli.mdx b/docs/integrations/cli.mdx
index 6f0b92f88..6fb4c57c6 100644
--- a/docs/integrations/cli.mdx
+++ b/docs/integrations/cli.mdx
@@ -14,7 +14,7 @@ keywords:
- one-liner
---
-The `skyvern` CLI gives you direct access to browser automation, workflow management, credential storage, and more — all from your terminal. Use it in shell scripts, CI/CD pipelines, or for quick one-off tasks.
+The `skyvern` CLI gives you direct access to browser automation, workflow management, credential storage, and more, all from your terminal. Use it in shell scripts, CI/CD pipelines, or for quick one-off tasks.
## Install
@@ -197,7 +197,7 @@ The CLI and MCP server share the same underlying logic. The CLI is for humans an
## Skills
-Skills are bundled reference markdown files that teach AI coding tools how to use Skyvern. They are **not** the same as MCP tools — they are documentation that an AI agent can load to learn the CLI and API.
+Skills are bundled reference markdown files that teach AI coding tools how to use Skyvern. They are **not** the same as MCP tools; they are documentation that an AI agent can load to learn the CLI and API.
```bash
skyvern skill list # List available skills
@@ -212,21 +212,21 @@ skyvern skill copy skyvern -o . # Copy a single skill
Skills are plain markdown files. You can load them into any AI coding tool that supports custom instructions:
-**Claude Code** — the recommended local path is `skyvern quickstart` or `skyvern init`, then choose Claude Code during MCP setup. That writes `.mcp.json` and installs bundled skills like `/qa`. You can also run `skyvern setup claude-code` later if you are configuring MCP separately.
+**Claude Code**: the recommended local path is `skyvern quickstart` or `skyvern init`, then choose Claude Code during MCP setup. That writes `.mcp.json` and installs bundled skills like `/qa`. You can also run `skyvern setup claude-code` later if you are configuring MCP separately.
-**Codex** — copy the skill into your project's `.codex/skills/` directory:
+**Codex**: copy the skill into your project's `.codex/skills/` directory:
```bash
skyvern skill copy skyvern -o .codex/skills/
```
-**Hermes** — copy the skill to your active Hermes profile's skills directory. The skill needs Hermes-compatible frontmatter (`metadata.hermes.requires_tools` instead of `allowed-tools`):
+**Hermes**: copy the skill to your active Hermes profile's skills directory. The skill needs Hermes-compatible frontmatter (`metadata.hermes.requires_tools` instead of `allowed-tools`):
```bash
# Create the skill directory
mkdir -p ~/.hermes/profiles/<your-profile>/skills/skyvern-browser-automation
-# Copy the skill body (you'll need to replace the frontmatter — see below)
+# Copy the skill body (you'll need to replace the frontmatter; see below)
skyvern skill copy skyvern -o /tmp/skyvern-skill
```
@@ -235,7 +235,7 @@ Replace the frontmatter in the copied `SKILL.md` with:
```yaml
---
name: skyvern-browser-automation
-description: "Browser automation via Skyvern — scrape pages, fill forms, extract data, run workflows."
+description: "Browser automation via Skyvern: scrape pages, fill forms, extract data, run workflows."
metadata:
hermes:
tags: [browser, automation, skyvern]
@@ -248,10 +248,10 @@ Then move it into place: `cp /tmp/skyvern-skill/SKILL.md ~/.hermes/profiles/<you
Verify with `hermes skills list | grep skyvern`.
<Tip>
-When both the Skyvern MCP server and the CLI skill are configured, Hermes prefers MCP tools over shelling out to the CLI — which is faster. The skill's judgment procedure (task classification, step ordering) works with either execution path.
+When both the Skyvern MCP server and the CLI skill are configured, Hermes prefers MCP tools over shelling out to the CLI, which is faster. The skill's judgment procedure (task classification, step ordering) works with either execution path.
</Tip>
-**OpenClaw** — copy the skill into your OpenClaw workspace `skills/` directory. By default that workspace lives at `~/.openclaw/workspace/`, but if you've customized the workspace path, use that location instead.
+**OpenClaw**: copy the skill into your OpenClaw workspace `skills/` directory. By default that workspace lives at `~/.openclaw/workspace/`, but if you've customized the workspace path, use that location instead.
```bash
mkdir -p ~/.openclaw/workspace/skills
@@ -263,7 +263,7 @@ openclaw skills list | grep skyvern
OpenClaw's MCP config provides the callable Skyvern tools; the workspace skill is optional guidance that teaches the agent when to use them.
</Tip>
-**Any tool** — point your tool at the file path returned by `skyvern skill path skyvern`.
+**Any tool**: point your tool at the file path returned by `skyvern skill path skyvern`.
</Accordion>
diff --git a/docs/integrations/local-llms.mdx b/docs/integrations/local-llms.mdx
index 52d558ba4..98398dc53 100644
--- a/docs/integrations/local-llms.mdx
+++ b/docs/integrations/local-llms.mdx
@@ -133,7 +133,7 @@ skyvern run server
<CardGroup cols={2}>
<Card
- title="API Quickstart"
+ title="Quickstart"
icon="rocket"
href="/getting-started/quickstart"
>
diff --git a/docs/integrations/make.mdx b/docs/integrations/make.mdx
index e92a095ef..961fca14f 100644
--- a/docs/integrations/make.mdx
+++ b/docs/integrations/make.mdx
@@ -16,13 +16,13 @@ Connect Skyvern to 2,000+ apps through Make. Trigger browser automations from an
## Available Modules
-- **Run a Task** — Run an automation using **Skyvern 1.0** (simple, single-step goals)
-- **Run a Task V2** — Run an automation using **Skyvern 2.0** (complex, multi-step goals)
-- **Run a Workflow** — Run a pre-built Skyvern workflow with parameters
-- **Get a Task / Get a Task V2** — Retrieve results from a previously run task
-- **Get a Workflow** — Retrieve results from a previously run workflow
-- **List Organizations** — List all organizations in your account
-- **Make an API Call** — Execute a custom API request with your credentials
+- **Run a Task**: Run an automation using **Skyvern 1.0** (simple, single-step goals)
+- **Run a Task V2**: Run an automation using **Skyvern 2.0** (complex, multi-step goals)
+- **Run a Workflow**: Run a pre-built Skyvern workflow with parameters
+- **Get a Task / Get a Task V2**: Retrieve results from a previously run task
+- **Get a Workflow**: Retrieve results from a previously run workflow
+- **List Organizations**: List all organizations in your account
+- **Make an API Call**: Execute a custom API request with your credentials
## Setup
@@ -70,16 +70,16 @@ Connect Skyvern to 2,000+ apps through Make. Trigger browser automations from an
### Run a Task
-- **URL** (required) — The starting page for the automation
-- **Navigation Goal** — What Skyvern should do on the page. Omit if only extracting data.
-- **Data Extraction Goal** — What data to pull from the page
-- **Navigation Payload** — JSON input data for forms. Lets you reuse the same task with different data.
-- **Extracted Information Schema** — JSON schema defining the shape of extracted data
-- **Webhook Callback URL** — URL to notify when the task finishes
-- **Max Steps** — Cap the number of steps to control costs
+- **URL** (required): The starting page for the automation
+- **Navigation Goal**: What Skyvern should do on the page. Omit if only extracting data.
+- **Data Extraction Goal**: What data to pull from the page
+- **Navigation Payload**: JSON input data for forms. Lets you reuse the same task with different data.
+- **Extracted Information Schema**: JSON schema defining the shape of extracted data
+- **Webhook Callback URL**: URL to notify when the task finishes
+- **Max Steps**: Cap the number of steps to control costs
<Note>
-The navigation goal describes what to do *after* loading the URL. Don't include "go to website X" — use the URL field instead.
+The navigation goal describes what to do *after* loading the URL. Don't include "go to website X"; use the URL field instead.
</Note>
<Frame>
@@ -90,8 +90,8 @@ The navigation goal describes what to do *after* loading the URL. Don't include
First, create your workflow in the [Skyvern UI](https://app.skyvern.com).
-- **Workflow** (required) — Select the workflow to run
-- **Parameters** — Fill in any parameters defined in your workflow
+- **Workflow** (required): Select the workflow to run
+- **Parameters**: Fill in any parameters defined in your workflow
<Frame>
<img src="/images/make/make4.png" alt="Configure workflow fields in Make.com" />
@@ -101,8 +101,8 @@ First, create your workflow in the [Skyvern UI](https://app.skyvern.com).
Retrieve the output of a completed run.
-- **Task ID** (required) — Starts with `tsk_`
-- **Workflow Run ID** (required) — Starts with `wr_`
+- **Task ID** (required): Starts with `tsk_`
+- **Workflow Run ID** (required): Starts with `wr_`
<Frame>
<img src="/images/make/make5.png" alt="Enter Task ID or Workflow Run ID in Make.com" />
diff --git a/docs/integrations/mcp.mdx b/docs/integrations/mcp.mdx
index c1a148a0c..08196ecfc 100644
--- a/docs/integrations/mcp.mdx
+++ b/docs/integrations/mcp.mdx
@@ -1,7 +1,7 @@
---
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, Cursor, Windsurf, Hermes, and other AI tools can run browser automations.
+description: Install and configure Skyvern's MCP server so Claude Desktop, Cursor, Windsurf, VS Code, Hermes, and other AI tools can run browser automations.
slug: going-to-production/mcp
keywords:
- MCP
@@ -26,7 +26,7 @@ The MCP server exposes 75+ tools across many categories. Here are the key ones:
| Category | Key tools | What they do |
|----------|-----------|--------------|
-| **Browser session management** | `skyvern_browser_session_create`, `skyvern_browser_session_close`, `skyvern_browser_session_list`, `skyvern_browser_session_get`, `skyvern_browser_session_connect` | Open, manage, and reuse browser sessions — including connecting to a local browser via CDP |
+| **Browser session management** | `skyvern_browser_session_create`, `skyvern_browser_session_close`, `skyvern_browser_session_list`, `skyvern_browser_session_get`, `skyvern_browser_session_connect` | Open, manage, and reuse browser sessions, including connecting to a local browser via CDP |
| **Browser actions** | `skyvern_act`, `skyvern_navigate`, `skyvern_click`, `skyvern_type`, `skyvern_hover`, `skyvern_scroll`, `skyvern_select_option`, `skyvern_press_key`, `skyvern_wait` | Control the browser with natural language, CSS/XPath selectors, or both (hybrid mode) |
| **Data extraction** | `skyvern_extract`, `skyvern_screenshot`, `skyvern_evaluate` | Pull structured JSON from pages, capture screenshots, run JavaScript |
| **Validation** | `skyvern_validate` | Assert page conditions in natural language (returns true/false with reasoning) |
@@ -41,7 +41,7 @@ Your AI assistant decides which tools to call based on your instructions. For ex
| | Cloud setup (recommended) | Local mode |
|---|---|---|
-| **Best for** | Most users — Skyvern Cloud handles everything | Self-hosting Skyvern with your own infrastructure |
+| **Best for** | Most users (Skyvern Cloud handles everything) | Self-hosting Skyvern with your own infrastructure |
| **Install required** | None | Python 3.11+ and `pip install skyvern` |
| **How it connects** | Your AI client connects to Skyvern Cloud over HTTPS | A local Python process runs on your machine |
| **API key** | From [app.skyvern.com](https://app.skyvern.com) | From your self-hosted Skyvern instance |
@@ -160,7 +160,7 @@ x-api-key = "SKYVERN_API_KEY"
</Tab>
<Tab title="Hermes">
-Using the Skyvern CLI (recommended — writes to all Hermes profiles automatically):
+Using the Skyvern CLI (recommended, writes to all Hermes profiles automatically):
```bash
pip install skyvern
@@ -231,7 +231,7 @@ For local stdio mode (self-hosted), use `skyvern setup openclaw --local` instead
</Tab>
<Tab title="MCPorter">
-MCPorter auto-discovers Skyvern from your existing MCP client configs (Cursor, Claude Code, Windsurf, etc.). If you've already set up Skyvern in any of those clients, MCPorter finds it automatically — no extra configuration needed.
+MCPorter auto-discovers Skyvern from your existing MCP client configs (Cursor, Claude Code, Windsurf, etc.). If you've already set up Skyvern in any of those clients, MCPorter finds it automatically. No extra configuration needed.
To check what MCPorter can discover:
@@ -243,7 +243,7 @@ skyvern setup mcporter
</Tab>
</Tabs>
-That's it — no Python, no `pip install`, no local server. Your AI assistant connects directly to Skyvern Cloud over HTTPS. Claude Desktop on macOS and Windows can use the one-click Skyvern bundle; Linux and advanced setups can still use [mcp-remote](https://www.npmjs.com/package/mcp-remote) with Node.js >= 20.
+That's it. No Python, no `pip install`, no local server. Your AI assistant connects directly to Skyvern Cloud over HTTPS. Claude Desktop on macOS and Windows can use the one-click Skyvern bundle; Linux and advanced setups can still use [mcp-remote](https://www.npmjs.com/package/mcp-remote) with Node.js >= 20.
<Tip>
Prefer a CLI? For Skyvern Cloud, `pip install skyvern` then run `skyvern setup`. For the local self-hosted path, run `skyvern quickstart` or `skyvern init` and choose Claude Code during the MCP step.
@@ -425,7 +425,7 @@ Replace `/usr/bin/python3` with the output of `which python3`. For Skyvern Cloud
## Connect to your local browser
-You can point your AI assistant at a browser running on your machine instead of a cloud browser. This lets you automate internal tools on localhost, reuse existing login sessions, and verify local dev changes — all through the same MCP tools.
+You can point your AI assistant at a browser running on your machine instead of a cloud browser. This lets you automate internal tools on localhost, reuse existing login sessions, and verify local dev changes, all through the same MCP tools.
Start a local browser with a tunnel so Skyvern Cloud can reach it:
@@ -440,7 +440,7 @@ This launches Chrome with your existing cookies and logins, and creates an ngrok
The `--use-local-profile` flag clones auth-relevant data from your default Chrome profile (cookies, saved passwords, local storage) so the browser starts pre-authenticated. Your original profile is never modified.
<Tip>
-This is especially powerful during development: make a code change, then ask your AI assistant to navigate to `localhost:3000` and verify it works — fix code and validate in the same prompt.
+This is especially powerful during development: make a code change, then ask your AI assistant to navigate to `localhost:3000` and verify it works. Fix code and validate in the same prompt.
</Tip>
<Warning>
@@ -453,7 +453,7 @@ Private Claude Desktop bundles do not auto-update. Download the latest [`skyvern
## QA your frontend changes
-For the local self-hosted path, run `skyvern quickstart` or `skyvern init`, choose `local`, then choose `Claude Code` during the MCP step. That writes local stdio MCP config and installs Claude Code skills — including `/qa`, which reads your git diff, generates browser tests, and runs them against your dev server.
+For the local self-hosted path, run `skyvern quickstart` or `skyvern init`, choose `local`, then choose `Claude Code` during the MCP step. That writes local stdio MCP config and installs Claude Code skills, including `/qa`, which reads your git diff, generates browser tests, and runs them against your dev server.
```bash
pip install skyvern
@@ -466,13 +466,13 @@ Then make a frontend change and type `/qa` in Claude Code. It will:
1. Read your `git diff` and the full source of each changed file
2. Generate targeted test cases (plus regression tests for adjacent behavior)
3. Open a browser against your running dev server
-4. Run the tests — navigate, click, fill forms, check the DOM
+4. Run the tests (navigate, click, fill forms, check the DOM)
5. Report pass/fail with screenshots
For localhost testing, start your local Skyvern backend and frontend. You do not need `skyvern browser serve --tunnel` for this path.
<Tip>
-The `/qa` skill uses `skyvern_evaluate` for fast DOM assertions (~10ms each) and `skyvern_act` for natural-language interactions. Tests are generated fresh from each diff — no test files to maintain.
+The `/qa` skill uses `skyvern_evaluate` for fast DOM assertions (~10ms each) and `skyvern_act` for natural-language interactions. Tests are generated fresh from each diff, so there are no test files to maintain.
</Tip>
## Troubleshooting
@@ -484,7 +484,7 @@ If you recently regenerated your API key, run `skyvern mcp switch` if you instal
</Accordion>
<Accordion title="Tools not responding or timing out">
-Skyvern browser sessions take a few seconds to start. If a tool call times out, try again — the first call in a new session is slower than subsequent ones.
+Skyvern browser sessions take a few seconds to start. If a tool call times out, try again. The first call in a new session is slower than subsequent ones.
If timeouts persist, check that your Skyvern account is active and has available credits at [app.skyvern.com](https://app.skyvern.com).
</Accordion>
diff --git a/docs/integrations/n8n.mdx b/docs/integrations/n8n.mdx
index 338756a60..3969dbef0 100644
--- a/docs/integrations/n8n.mdx
+++ b/docs/integrations/n8n.mdx
@@ -16,10 +16,10 @@ Connect Skyvern to n8n's open-source automation platform. Trigger browser automa
## Available Operations
-- **Task → Dispatch a Task** — Run a browser automation with a prompt
-- **Task → Get a Task** — Retrieve results from a previously run task
-- **Workflow → Dispatch a Workflow Run** — Run a pre-built Skyvern workflow with parameters
-- **Workflow → Get a Workflow Run** — Retrieve results from a previously run workflow
+- **Task → Dispatch a Task**: Run a browser automation with a prompt
+- **Task → Get a Task**: Retrieve results from a previously run task
+- **Workflow → Dispatch a Workflow Run**: Run a pre-built Skyvern workflow with parameters
+- **Workflow → Get a Workflow Run**: Retrieve results from a previously run workflow
## Setup
@@ -60,16 +60,16 @@ Connect Skyvern to n8n's open-source automation platform. Trigger browser automa
<img src="/images/n8n/n8n2.png" alt="Configure Dispatch a Task fields in n8n" />
</Frame>
-- **User Prompt** (required) — What Skyvern should do
-- **URL** — The starting page. If omitted, Skyvern navigates based on the prompt.
-- **Webhook Callback URL** — URL to notify when the task finishes
+- **User Prompt** (required): What Skyvern should do
+- **URL**: The starting page. If omitted, Skyvern navigates based on the prompt.
+- **Webhook Callback URL**: URL to notify when the task finishes
Under **Task Options**:
-- **Engine** — Defaults to **Skyvern 2.0**.
- - **Skyvern 1.0** — Simple, single-step tasks
- - **Skyvern 2.0** — Complex, multi-step goals with dynamic planning
- - **OpenAI CUA** / **Anthropic CUA** — Third-party computer-use agents
+- **Engine**: Defaults to **Skyvern 2.0**.
+ - **Skyvern 1.0**: Simple, single-step tasks
+ - **Skyvern 2.0**: Complex, multi-step goals with dynamic planning
+ - **OpenAI CUA** / **Anthropic CUA**: Third-party computer-use agents
### Dispatch a Workflow Run
@@ -79,9 +79,9 @@ Under **Task Options**:
First, create your workflow in the [Skyvern UI](https://app.skyvern.com).
-- **Workflow Name or ID** (required) — Select from the dropdown or specify an ID with an expression
-- **Workflow Run Parameters** — Loaded dynamically from the selected workflow
-- **Webhook Callback URL** — URL to notify when the workflow finishes
+- **Workflow Name or ID** (required): Select from the dropdown or specify an ID with an expression
+- **Workflow Run Parameters**: Loaded dynamically from the selected workflow
+- **Webhook Callback URL**: URL to notify when the workflow finishes
### Get a Task
@@ -89,7 +89,7 @@ First, create your workflow in the [Skyvern UI](https://app.skyvern.com).
<img src="/images/n8n/n8n5.png" alt="Enter Task ID field in n8n" />
</Frame>
-- **Task ID** (required) — The ID of the task run
+- **Task ID** (required): The ID of the task run
### Get a Workflow Run
@@ -97,8 +97,8 @@ First, create your workflow in the [Skyvern UI](https://app.skyvern.com).
<img src="/images/n8n/n8n4.png" alt="Enter Workflow Run ID field in n8n" />
</Frame>
-- **Workflow Name or ID** (required) — Select the workflow from the dropdown
-- **Workflow Run ID** (required) — Starts with `wr_`
+- **Workflow Name or ID** (required): Select the workflow from the dropdown
+- **Workflow Run ID** (required): Starts with `wr_`
## Next steps
diff --git a/docs/integrations/workato.mdx b/docs/integrations/workato.mdx
index 5314a2fb4..540202472 100644
--- a/docs/integrations/workato.mdx
+++ b/docs/integrations/workato.mdx
@@ -15,11 +15,11 @@ Connect Skyvern to Workato's enterprise automation platform. Trigger browser aut
## Available Actions
-- **Create and Run Task** — Run an automation using **Skyvern 1.0** (simple, single-step goals)
-- **Create and Run Task V2** — Run an automation using **Skyvern 2.0** (complex, multi-step goals)
-- **Run a Workflow** — Run a pre-built Skyvern workflow with parameters
-- **Get Task / Get Task V2** — Retrieve results from a previously run task
-- **Get Workflow** — Retrieve results from a previously run workflow
+- **Create and Run Task**: Run an automation using **Skyvern 1.0** (simple, single-step goals)
+- **Create and Run Task V2**: Run an automation using **Skyvern 2.0** (complex, multi-step goals)
+- **Run a Workflow**: Run a pre-built Skyvern workflow with parameters
+- **Get Task / Get Task V2**: Retrieve results from a previously run task
+- **Get Workflow**: Retrieve results from a previously run workflow
## Setup
@@ -71,16 +71,16 @@ Connect Skyvern to Workato's enterprise automation platform. Trigger browser aut
### Create and Run a Task
-- **URL** (required) — The starting page for the automation
-- **Navigation Goal** — What Skyvern should do on the page. Omit if only extracting data.
-- **Data Extraction Goal** — What data to pull from the page
-- **Navigation Payload** — JSON input data for forms. Lets you reuse the same task with different data.
-- **Extracted Information Schema** — JSON schema defining the shape of extracted data
-- **Webhook Callback URL** — URL to notify when the task finishes
-- **Max Steps** — Cap the number of steps to control costs
+- **URL** (required): The starting page for the automation
+- **Navigation Goal**: What Skyvern should do on the page. Omit if only extracting data.
+- **Data Extraction Goal**: What data to pull from the page
+- **Navigation Payload**: JSON input data for forms. Lets you reuse the same task with different data.
+- **Extracted Information Schema**: JSON schema defining the shape of extracted data
+- **Webhook Callback URL**: URL to notify when the task finishes
+- **Max Steps**: Cap the number of steps to control costs
<Note>
-The navigation goal describes what to do *after* loading the URL. Don't include "go to website X" — use the URL field instead.
+The navigation goal describes what to do *after* loading the URL. Don't include "go to website X"; use the URL field instead.
</Note>
<Frame>
@@ -91,8 +91,8 @@ The navigation goal describes what to do *after* loading the URL. Don't include
First, create your workflow in the [Skyvern UI](https://app.skyvern.com).
-- **Workflow** (required) — Select the workflow to run
-- **Parameters** — Fill in any parameters defined in your workflow
+- **Workflow** (required): Select the workflow to run
+- **Parameters**: Fill in any parameters defined in your workflow
<Frame>
<img src="/images/workato/s5img1.png" alt="Select workflow in Workato" />
@@ -102,8 +102,8 @@ First, create your workflow in the [Skyvern UI](https://app.skyvern.com).
Retrieve the details of a completed run.
-- **Task ID** (required) — Starts with `tsk_`
-- **Workflow Run ID** (required) — Starts with `wr_`
+- **Task ID** (required): Starts with `tsk_`
+- **Workflow Run ID** (required): Starts with `wr_`
## Next steps
diff --git a/docs/integrations/zapier.mdx b/docs/integrations/zapier.mdx
index 5c101a953..246306fb3 100644
--- a/docs/integrations/zapier.mdx
+++ b/docs/integrations/zapier.mdx
@@ -17,15 +17,15 @@ Connect Skyvern to 7,000+ apps through Zapier. Trigger browser automations from
## Available Triggers
-- **New or Updated Skyvern Workflow** — Starts a Zap whenever a workflow is created or modified.
+- **New or Updated Skyvern Workflow**: Starts a Zap whenever a workflow is created or modified.
## Available Actions
-- **Create and Run a Task** — Run an automation using **Skyvern 1.0** (simple, single-step goals)
-- **Create and Run Task V2** — Run an automation using **Skyvern 2.0** (complex, multi-step goals)
-- **Run a Workflow** — Run a pre-built Skyvern workflow with parameters
-- **Get a Task / Get a Task V2** — Retrieve results from a previously run task
-- **Get a Workflow** — Retrieve results from a previously run workflow
+- **Create and Run a Task**: Run an automation using **Skyvern 1.0** (simple, single-step goals)
+- **Create and Run Task V2**: Run an automation using **Skyvern 2.0** (complex, multi-step goals)
+- **Run a Workflow**: Run a pre-built Skyvern workflow with parameters
+- **Get a Task / Get a Task V2**: Retrieve results from a previously run task
+- **Get a Workflow**: Retrieve results from a previously run workflow
## Setup
@@ -77,16 +77,16 @@ Connect Skyvern to 7,000+ apps through Zapier. Trigger browser automations from
### Create and Run a Task
-- **URL** (required) — The starting page for the automation
-- **Navigation Goal** — What Skyvern should do on the page. Omit if only extracting data.
-- **Data Extraction Goal** — What data to pull from the page
-- **Navigation Payload** — JSON input data for forms. Lets you reuse the same task with different data.
-- **Extracted Information Schema** — JSON schema defining the shape of extracted data
-- **Webhook Callback URL** — URL to notify when the task finishes
-- **Max Steps** — Cap the number of steps to control costs
+- **URL** (required): The starting page for the automation
+- **Navigation Goal**: What Skyvern should do on the page. Omit if only extracting data.
+- **Data Extraction Goal**: What data to pull from the page
+- **Navigation Payload**: JSON input data for forms. Lets you reuse the same task with different data.
+- **Extracted Information Schema**: JSON schema defining the shape of extracted data
+- **Webhook Callback URL**: URL to notify when the task finishes
+- **Max Steps**: Cap the number of steps to control costs
<Note>
-The navigation goal describes what to do *after* loading the URL. Don't include "go to website X" — use the URL field instead.
+The navigation goal describes what to do *after* loading the URL. Don't include "go to website X"; use the URL field instead.
</Note>
<Frame>
@@ -97,8 +97,8 @@ The navigation goal describes what to do *after* loading the URL. Don't include
First, create your workflow in the [Skyvern UI](https://app.skyvern.com).
-- **Workflow** (required) — Select the workflow to run
-- **Parameters** — Fill in any parameters defined in your workflow
+- **Workflow** (required): Select the workflow to run
+- **Parameters**: Fill in any parameters defined in your workflow
<Frame>
<img src="/images/zapier/z.7w.png" alt="Select workflow in Zapier" />
@@ -111,8 +111,8 @@ First, create your workflow in the [Skyvern UI](https://app.skyvern.com).
Retrieve the output of a completed run.
-- **Task ID** (required) — Starts with `tsk_`
-- **Workflow Run ID** (required) — Starts with `wr_`
+- **Task ID** (required): Starts with `tsk_`
+- **Workflow Run ID** (required): Starts with `wr_`
<Frame>
<img src="/images/zapier/z.11ag.png" alt="Enter Task ID field in Zapier" />
diff --git a/docs/llms.txt b/docs/llms.txt
index c0ad734cc..6168d8f47 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -1,5 +1,14 @@
# Skyvern
+<<<<<<< HEAD
+> 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. Use the Python SDK, TypeScript SDK, REST API, MCP server, or Cloud UI to build and run browser automations. Key capabilities: natural-language task execution, multi-step workflows with loops and conditionals, credential management (passwords, credit cards, TOTP/2FA), browser session persistence, data extraction, file downloads, webhook notifications, and proxy/geolocation support.
+
+## Getting Started
+
+- [What is Skyvern?](https://skyvern.com/docs/getting-started/introduction.md): Overview of Skyvern's AI-powered browser automation platform; how it uses LLMs and computer vision to navigate any website without custom scripts
+- [Core Concepts](https://skyvern.com/docs/getting-started/core-concepts.md): Key building blocks; tasks, workflows, blocks, parameters, browser sessions, browser profiles, credentials, runs, and artifacts
+- [Quickstart](https://skyvern.com/docs/getting-started/quickstart.md): Run your first browser automation task with the Skyvern REST API using Python, TypeScript, or cURL in under 5 minutes
+=======
> 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. Use the Python SDK, TypeScript SDK, REST API, MCP server, or Cloud UI to build and run browser automations. Key capabilities: natural-language task execution, multi-step workflows with loops and conditionals, credential management (passwords, credit cards, TOTP/2FA), browser session persistence, data extraction, file downloads, webhook notifications, and proxy/geolocation support.
## Getting Started
@@ -7,10 +16,34 @@
- [What is Skyvern?](https://skyvern.com/docs/getting-started/introduction.md): Overview of Skyvern's AI-powered browser automation platform — how it uses LLMs and computer vision to navigate any website without custom scripts
- [Core Concepts](https://skyvern.com/docs/getting-started/core-concepts.md): Key building blocks — tasks, workflows, blocks, parameters, browser sessions, browser profiles, credentials, runs, and artifacts
- [API Quickstart](https://skyvern.com/docs/getting-started/quickstart.md): Run your first browser automation task with the Skyvern REST API using Python, TypeScript, or cURL in under 5 minutes
+>>>>>>> 022ec7b1 (docs: Add keywords and descriptions for every page, rewrote llms.txt, added another redirect (#5461))
- [AI Agents Quickstart](https://skyvern.com/docs/getting-started/ai-agents-quickstart.md): Set up Skyvern's MCP server so Claude Desktop, Cursor, Windsurf, or any AI coding assistant can run browser automations
## Creating & Running Tasks
+<<<<<<< HEAD
+- [Run a Task](https://skyvern.com/docs/running-automations/run-a-task.md): Execute a single browser automation with a natural-language goal; configure URLs, navigation goals, data extraction schemas, webhooks, and proxy settings via API or SDK
+- [Task Parameters](https://skyvern.com/docs/running-automations/task-parameters.md): Configure task behavior; proxy location, browser session reuse, TOTP/2FA credentials, max steps, webhook callbacks, error handling, and extraction schemas
+- [Extract Structured Data](https://skyvern.com/docs/running-automations/extract-structured-data.md): Define JSON schemas to get consistent, typed data extraction output from tasks; prices, addresses, table rows, and more
+
+## Building Multi-Step Workflows
+
+- [Build a Workflow](https://skyvern.com/docs/cloud/building-workflows/build-a-workflow.md): Create multi-step browser automations by chaining task blocks, loops, conditionals, extraction, and file operations into reusable workflows
+- [Workflow Blocks Reference](https://skyvern.com/docs/cloud/building-workflows/configure-blocks.md): Complete reference for every block type; navigation block, action block, extract block, loop block, text prompt block, login block, file operations, email, webhook, and validation blocks
+- [Workflow Parameters](https://skyvern.com/docs/cloud/building-workflows/add-parameters.md): Pass dynamic values into workflows at runtime; configure proxy, webhook, browser session, and credential parameters per run
+- [File Operations](https://skyvern.com/docs/cloud/building-workflows/configure-blocks.md): Download, parse (CSV, PDF, Excel), and upload files within workflow blocks
+- [Scheduling Workflows](https://skyvern.com/docs/cloud/building-workflows/scheduling.md): Run workflows automatically on a recurring cron schedule via API, SDK, or the Cloud UI
+
+## Handling Authentication
+
+- [Store Credentials](https://skyvern.com/docs/credentials/store-credentials.md): Securely manage login passwords, credit cards, TOTP secrets, and API keys; with Bitwarden, 1Password, Azure Key Vault, or Skyvern's built-in vault
+- [Handle 2FA](https://skyvern.com/docs/credentials/handle-2fa.md): Configure TOTP-based two-factor authentication so Skyvern can complete login flows that require 2FA codes
+- [Troubleshooting Login](https://skyvern.com/docs/credentials/troubleshooting-login.md): Debug common authentication failures; credential issues, CAPTCHA blocks, bot detection, and session expiration
+
+## Optimizing Performance
+
+- [Browser Sessions](https://skyvern.com/docs/optimization/browser-sessions.md): Persist a live browser across multiple tasks and workflows; maintain login state, cookies, and page context between API calls
+=======
- [Run a Task](https://skyvern.com/docs/running-automations/run-a-task.md): Execute a single browser automation with a natural-language goal — configure URLs, navigation goals, data extraction schemas, webhooks, and proxy settings via API or SDK
- [Task Parameters](https://skyvern.com/docs/running-automations/task-parameters.md): Configure task behavior — proxy location, browser session reuse, TOTP/2FA credentials, max steps, webhook callbacks, error handling, and extraction schemas
- [Extract Structured Data](https://skyvern.com/docs/running-automations/extract-structured-data.md): Define JSON schemas to get consistent, typed data extraction output from tasks — prices, addresses, table rows, and more
@@ -32,6 +65,7 @@
## Optimizing Performance
- [Browser Sessions](https://skyvern.com/docs/optimization/browser-sessions.md): Persist a live browser across multiple tasks and workflows — maintain login state, cookies, and page context between API calls
+>>>>>>> 022ec7b1 (docs: Add keywords and descriptions for every page, rewrote llms.txt, added another redirect (#5461))
- [Browser Profiles](https://skyvern.com/docs/optimization/browser-profiles.md): Save and reuse authenticated browser state (cookies, localStorage) across runs without re-logging in
- [Cost Control](https://skyvern.com/docs/optimization/cost-control.md): Limit max steps, optimize prompts, and use caching to manage credit consumption
@@ -39,7 +73,11 @@
- [Webhooks](https://skyvern.com/docs/going-to-production/webhooks.md): Receive HTTP callbacks when tasks and workflow runs complete, fail, or require human intervention
- [Proxy & Geolocation](https://skyvern.com/docs/going-to-production/proxy-geolocation.md): Route browser traffic through residential proxies in specific countries and regions to handle geo-restricted content
+<<<<<<< HEAD
+- [Error Handling](https://skyvern.com/docs/going-to-production/error-handling.md): Detect, classify, and recover from task failures; retry strategies, cancel runs, and webhook error payloads
+=======
- [Error Handling](https://skyvern.com/docs/going-to-production/error-handling.md): Detect, classify, and recover from task failures — retry strategies, cancel runs, and webhook error payloads
+>>>>>>> 022ec7b1 (docs: Add keywords and descriptions for every page, rewrote llms.txt, added another redirect (#5461))
- [Reliability Tips](https://skyvern.com/docs/going-to-production/reliability-tips.md): Write robust prompts, handle edge cases, and build resilient automations that work across website changes
- [CAPTCHA & Bot Detection](https://skyvern.com/docs/going-to-production/captcha-bot-detection.md): How Skyvern handles CAPTCHAs, anti-bot systems, and stealth browser configuration
@@ -47,7 +85,11 @@
- [MCP Server](https://skyvern.com/docs/going-to-production/mcp.md): Install and configure Skyvern's Model Context Protocol server for Claude Desktop, Cursor, Windsurf, VS Code, and other AI assistants
- [CLI & Skills](https://skyvern.com/docs/going-to-production/cli.md): Run tasks, manage workflows, store credentials, and open browser sessions from the command line
+<<<<<<< HEAD
+- [Zapier](https://skyvern.com/docs/integrations/zapier.md): Trigger browser automations from Zapier workflows; run tasks and get results via Zapier actions
+=======
- [Zapier](https://skyvern.com/docs/integrations/zapier.md): Trigger browser automations from Zapier workflows — run tasks and get results via Zapier actions
+>>>>>>> 022ec7b1 (docs: Add keywords and descriptions for every page, rewrote llms.txt, added another redirect (#5461))
- [Make.com](https://skyvern.com/docs/integrations/make.md): Integrate Skyvern browser automations into Make.com scenarios
- [n8n](https://skyvern.com/docs/integrations/n8n.md): Run browser automations as nodes in n8n workflows
- [Workato](https://skyvern.com/docs/integrations/workato.md): Run browser automations in Workato recipes with the Skyvern connector
@@ -56,6 +98,16 @@
## Python SDK Reference
- [Python SDK Overview](https://skyvern.com/docs/sdk-reference/overview.md): Install, authenticate, and configure the Skyvern Python client
+<<<<<<< HEAD
+- [Tasks](https://skyvern.com/docs/sdk-reference/tasks.md): Run single browser automations; run_task(), get_run(), cancel_run(), and extraction
+- [Workflows](https://skyvern.com/docs/sdk-reference/workflows.md): Create and run multi-step workflows; create_workflow(), run_workflow(), and block configuration
+- [Browser Sessions](https://skyvern.com/docs/sdk-reference/browser-sessions.md): Manage live browser state; create_session(), get_session(), close_session()
+- [Browser Profiles](https://skyvern.com/docs/sdk-reference/browser-profiles.md): Save and reuse browser state; create_profile(), list_profiles(), delete_profile()
+- [Credentials](https://skyvern.com/docs/sdk-reference/credentials.md): Store passwords, TOTP secrets, and credit cards; create_credential(), send_totp()
+- [Helper Methods](https://skyvern.com/docs/sdk-reference/helpers.md): High-level convenience methods for login, credential management, and common patterns
+- [Error Handling](https://skyvern.com/docs/sdk-reference/error-handling.md): Handle API errors, timeouts, rate limits, and configure retry behavior
+- [Complete Reference](https://skyvern.com/docs/sdk-reference/complete-reference.md): Every method, parameter, and type in the Python SDK on one page; optimized for LLM consumption
+=======
- [Tasks](https://skyvern.com/docs/sdk-reference/tasks.md): Run single browser automations — run_task(), get_run(), cancel_run(), and extraction
- [Workflows](https://skyvern.com/docs/sdk-reference/workflows.md): Create and run multi-step workflows — create_workflow(), run_workflow(), and block configuration
- [Browser Sessions](https://skyvern.com/docs/sdk-reference/browser-sessions.md): Manage live browser state — create_session(), get_session(), close_session()
@@ -64,10 +116,22 @@
- [Helper Methods](https://skyvern.com/docs/sdk-reference/helpers.md): High-level convenience methods for login, credential management, and common patterns
- [Error Handling](https://skyvern.com/docs/sdk-reference/error-handling.md): Handle API errors, timeouts, rate limits, and configure retry behavior
- [Complete Reference](https://skyvern.com/docs/sdk-reference/complete-reference.md): Every method, parameter, and type in the Python SDK on one page — optimized for LLM consumption
+>>>>>>> 022ec7b1 (docs: Add keywords and descriptions for every page, rewrote llms.txt, added another redirect (#5461))
## TypeScript SDK Reference
- [TypeScript SDK Overview](https://skyvern.com/docs/ts-sdk-reference/overview.md): Install, authenticate, and configure the Skyvern TypeScript client
+<<<<<<< HEAD
+- [Tasks](https://skyvern.com/docs/ts-sdk-reference/tasks.md): Run single browser automations; runTask(), getRun(), cancelRun(), and extraction
+- [Workflows](https://skyvern.com/docs/ts-sdk-reference/workflows.md): Create and run multi-step workflows; createWorkflow(), runWorkflow(), and block configuration
+- [Browser Sessions](https://skyvern.com/docs/ts-sdk-reference/browser-sessions.md): Manage live browser state; createSession(), getSession(), closeSession()
+- [Browser Profiles](https://skyvern.com/docs/ts-sdk-reference/browser-profiles.md): Save and reuse browser state; createProfile(), listProfiles(), deleteProfile()
+- [Credentials](https://skyvern.com/docs/ts-sdk-reference/credentials.md): Store passwords, TOTP secrets, and credit cards; createCredential(), sendTotp()
+- [Helper Methods](https://skyvern.com/docs/ts-sdk-reference/helpers.md): High-level convenience methods for login, credential management, and common patterns
+- [Browser Automation](https://skyvern.com/docs/ts-sdk-reference/browser-automation.md): Control cloud browsers with Playwright + AI; direct browser session automation
+- [Error Handling](https://skyvern.com/docs/ts-sdk-reference/error-handling.md): Handle API errors, timeouts, rate limits, and configure retry behavior
+- [Complete Reference](https://skyvern.com/docs/ts-sdk-reference/complete-reference.md): Every method, parameter, and type in the TypeScript SDK on one page; optimized for LLM consumption
+=======
- [Tasks](https://skyvern.com/docs/ts-sdk-reference/tasks.md): Run single browser automations — runTask(), getRun(), cancelRun(), and extraction
- [Workflows](https://skyvern.com/docs/ts-sdk-reference/workflows.md): Create and run multi-step workflows — createWorkflow(), runWorkflow(), and block configuration
- [Browser Sessions](https://skyvern.com/docs/ts-sdk-reference/browser-sessions.md): Manage live browser state — createSession(), getSession(), closeSession()
@@ -77,13 +141,20 @@
- [Browser Automation](https://skyvern.com/docs/ts-sdk-reference/browser-automation.md): Control cloud browsers with Playwright + AI — direct browser session automation
- [Error Handling](https://skyvern.com/docs/ts-sdk-reference/error-handling.md): Handle API errors, timeouts, rate limits, and configure retry behavior
- [Complete Reference](https://skyvern.com/docs/ts-sdk-reference/complete-reference.md): Every method, parameter, and type in the TypeScript SDK on one page — optimized for LLM consumption
+>>>>>>> 022ec7b1 (docs: Add keywords and descriptions for every page, rewrote llms.txt, added another redirect (#5461))
## Debugging & Troubleshooting
- [Using Artifacts](https://skyvern.com/docs/debugging/using-artifacts.md): Access recordings, screenshots, action logs, and network data for every run
+<<<<<<< HEAD
+- [Troubleshooting Guide](https://skyvern.com/docs/debugging/troubleshooting-guide.md): Diagnose common issues; step timeline analysis, prompt tuning, and when to adjust task configuration
+- [Observability with Laminar](https://skyvern.com/docs/debugging/observability-with-laminar.md): Add tracing and observability to Skyvern automations using Laminar
+- [FAQ](https://skyvern.com/docs/debugging/faq.md): Frequently asked questions; CAPTCHA handling, retries, artifacts, recordings, and error codes
+=======
- [Troubleshooting Guide](https://skyvern.com/docs/debugging/troubleshooting-guide.md): Diagnose common issues — step timeline analysis, prompt tuning, and when to adjust task configuration
- [Observability with Laminar](https://skyvern.com/docs/debugging/observability-with-laminar.md): Add tracing and observability to Skyvern automations using Laminar
- [FAQ](https://skyvern.com/docs/debugging/faq.md): Frequently asked questions — CAPTCHA handling, retries, artifacts, recordings, and error codes
+>>>>>>> 022ec7b1 (docs: Add keywords and descriptions for every page, rewrote llms.txt, added another redirect (#5461))
## Self-Hosted Deployment
@@ -93,7 +164,11 @@
- [Browser Configuration](https://skyvern.com/docs/self-hosted/browser.md): Configure browser modes, display settings, headless vs headed, and external Chrome connections via Playwright
- [Proxy Setup](https://skyvern.com/docs/self-hosted/proxy.md): Configure residential proxies and geolocation for bot detection avoidance in self-hosted deployments
- [Kubernetes Deployment](https://skyvern.com/docs/self-hosted/kubernetes.md): Deploy Skyvern at scale with Kubernetes manifests and Helm charts
+<<<<<<< HEAD
+- [Storage Configuration](https://skyvern.com/docs/self-hosted/storage.md): Configure where Skyvern stores artifacts, recordings, and screenshots; local filesystem or S3-compatible storage
+=======
- [Storage Configuration](https://skyvern.com/docs/self-hosted/storage.md): Configure where Skyvern stores artifacts, recordings, and screenshots — local filesystem or S3-compatible storage
+>>>>>>> 022ec7b1 (docs: Add keywords and descriptions for every page, rewrote llms.txt, added another redirect (#5461))
## Cookbooks
@@ -104,11 +179,19 @@
## Cloud UI
+<<<<<<< HEAD
+For visual dashboard documentation; running tasks, building workflows, managing credentials, viewing results, and account settings; see the [Cloud UI Guide](https://skyvern.com/docs/cloud/overview.md).
+
+## API Reference
+
+- [OpenAPI Specification](https://skyvern.com/docs/api-reference/openapi.json): Full OpenAPI 3.x spec for all Skyvern REST API endpoints; tasks, workflows, browser sessions, browser profiles, credentials, and artifacts
+=======
For visual dashboard documentation — running tasks, building workflows, managing credentials, viewing results, and account settings — see the [Cloud UI Guide](https://skyvern.com/docs/cloud/overview.md).
## API Reference
- [OpenAPI Specification](https://skyvern.com/docs/api-reference/openapi.json): Full OpenAPI 3.x spec for all Skyvern REST API endpoints — tasks, workflows, browser sessions, browser profiles, credentials, and artifacts
+>>>>>>> 022ec7b1 (docs: Add keywords and descriptions for every page, rewrote llms.txt, added another redirect (#5461))
## Changelog
diff --git a/docs/multi-step-automations/build-a-workflow.mdx b/docs/multi-step-automations/build-a-workflow.mdx
deleted file mode 100644
index 7fb4baf0d..000000000
--- a/docs/multi-step-automations/build-a-workflow.mdx
+++ /dev/null
@@ -1,1131 +0,0 @@
----
-title: Build a Workflow
-subtitle: Create, run, and test multi-step automations
-description: Create multi-step browser automations by chaining tasks, loops, conditionals, and data extraction blocks into reusable workflows.
-slug: multi-step-automations/build-a-workflow
-keywords:
- - create_workflow
- - JSON definition
- - YAML definition
- - block chaining
- - parameter passing
- - test run
- - publish
----
-
-A **Workflow** chains multiple automation steps into a reusable template. While a Task handles a single goal on one page, a Workflow orchestrates an entire process: filling forms, validating data, downloading files, and sending results.
-
-You define the workflow once with blocks, then run it with different parameters each time.
-
----
-
-## Tasks vs Workflows
-
-| Characteristic | Tasks | Workflows |
-|----------------|-------|-----------|
-| **Structure** | Single prompt, one execution | Multiple blocks in sequence |
-| **Scope** | Single goal, usually one page | Multi-step process across pages |
-| **Reusability** | Run ad-hoc or scheduled | Define once, run with different parameters |
-| **Parameterization** | Basic (prompt, URL, extraction schema) | Rich (input parameters, block outputs, Jinja templates) |
-| **Control Flow** | Linear | Loops, conditionals, validation gates |
-| **Data Passing** | Output returned at the end | Each block can pass data to subsequent blocks |
-| **Composition** | Single AI agent execution | Combine navigation, extraction, files, notifications |
-| **File Operations** | Download files during task | Download, parse, upload, email files across blocks |
-| **Best For** | Prototyping, simple extractions, one-offs | Production automations, bulk processing, complex logic |
-| **Run ID Format** | `tsk_*` | `wr_*` |
-
----
-
-## Workflow structure
-
-A workflow is defined as an ordered list of **blocks**. Blocks execute one after another, and each block can access the outputs of previous blocks.
-
-Here's an IRS EIN registration workflow that fills out a government form, validates the summary, extracts the result, downloads the confirmation letter, and emails it to your team:
-
-<Frame>
- <img src="/images/skyvern-ss4-workflow.svg" alt="IRS SS-4 Filing Workflow: Navigation → Validation → Extraction → File Download → Send Email" />
-</Frame>
-
-Here's what each block does in this workflow:
-
-- **Navigation** takes the company information from `ein_info` and fills out the multi-page SS-4 form until it reaches the review page
-- **Validation** checks that the form summary matches the provided information and either continues (if correct) or terminates the workflow (if incorrect)
-- **Extraction** pulls the assigned EIN number and legal name from the confirmation page into structured JSON output
-- **File Download** navigates to and downloads the EIN confirmation letter as a PDF file
-- **Send Email** attaches the downloaded PDF and sends it to the specified recipients with company details in the email body
-
-<Info>
-For detailed documentation on all available block types and their parameters, see [Workflow Blocks Reference](/multi-step-automations/workflow-blocks-reference).
-</Info>
-
----
-
-## Step 1: Understand the structure
-
-A workflow definition has two parts: **parameters** (the inputs) and **blocks** (the steps). Here's the complete shape:
-
-```yaml
-title: Job Application Workflow # Display name
-workflow_definition:
- parameters: # ← Inputs: change per run (Step 2)
- - key: job_url
- parameter_type: workflow
- workflow_parameter_type: string
-
- blocks: # ← Steps: execute in order (Step 3)
- - label: apply_to_job
- block_type: navigation
- url: "{{ job_url }}"
- navigation_goal: Fill out the job application form
-```
-
-You send this definition to the API to create a reusable workflow:
-
-```python
-workflow = await client.create_workflow(
- json_definition={ # ← or yaml_definition="..."
- "title": "...",
- "workflow_definition": {
- "parameters": [...], # Step 2
- "blocks": [...] # Step 3
- }
- }
-)
-```
-
-The rest of this guide walks through each part, then shows the full API calls for creating, running, and monitoring workflows.
-
----
-
-## Step 2: Define parameters
-
-The `parameters` array (inside `workflow_definition`) defines the inputs your workflow accepts. Instead of hardcoding a resume URL or job page into the workflow definition, you define named inputs that accept different values each time the workflow runs.
-
-Each parameter needs three fields:
-- `key` — the name you reference later with `{{ key }}`
-- `parameter_type` — always `"workflow"` for input parameters
-- `workflow_parameter_type` — the data type (`string`, `file_url`, `json`, etc.)
-
-<CodeGroup>
-```json JSON
-{
- "parameters": [
- {
- "key": "resume",
- "parameter_type": "workflow",
- "workflow_parameter_type": "file_url"
- },
- {
- "key": "job_url",
- "parameter_type": "workflow",
- "workflow_parameter_type": "string"
- }
- ]
-}
-```
-
-```yaml YAML
-parameters:
- - key: resume
- parameter_type: workflow
- workflow_parameter_type: file_url
- - key: job_url
- parameter_type: workflow
- workflow_parameter_type: string
-```
-</CodeGroup>
-
-This defines two inputs: a `resume` file and a `job_url` string. When you run the workflow later, you pass actual values for these parameters.
-
-**Available parameter types:**
-
-| Type | Description | Example value |
-|------|-------------|---------------|
-| `string` | Text | `"John Smith"` |
-| `integer` | Whole number | `42` |
-| `float` | Decimal number | `99.99` |
-| `boolean` | True or false | `true` |
-| `json` | JSON object or array | `{"key": "value"}` |
-| `file_url` | URL to a file | `"https://example.com/resume.pdf"` |
-| `credential_id` | Reference to a stored credential | `"cred_abc123"` |
-
-For the full parameter reference, see [Workflow Parameters](/multi-step-automations/workflow-parameters).
-
----
-
-## Step 3: Define blocks
-
-The `blocks` array (inside `workflow_definition`) defines the steps your workflow executes. Each block has a `block_type` that determines what it does: navigate a page, extract data, download a file, send an email.
-
-Every block needs two fields: a `label` (a unique name) and a `block_type`. The remaining fields depend on the block type.
-
-<CodeGroup>
-```json JSON
-{
- "blocks": [
- {
- "label": "parse_resume",
- "block_type": "file_url_parser",
- "file_url": "{{ resume }}",
- "file_type": "pdf"
- },
- {
- "label": "apply_to_job",
- "block_type": "navigation",
- "url": "{{ job_url }}",
- "navigation_goal": "Fill out the job application form using the candidate's information."
- }
- ]
-}
-```
-
-```yaml YAML
-blocks:
- - label: parse_resume
- block_type: file_url_parser
- file_url: "{{ resume }}"
- file_type: pdf
-
- - label: apply_to_job
- block_type: navigation
- url: "{{ job_url }}"
- navigation_goal: Fill out the job application form using the candidate's information.
-```
-</CodeGroup>
-
-The first block (`parse_resume`) parses the resume file passed as an input parameter. The second block (`apply_to_job`) navigates to the job page and fills out the application.
-
-Notice `{{ resume }}` and `{{ job_url }}` — double curly braces reference the input parameters you defined in Step 2. Skyvern replaces these with actual values when the workflow runs.
-
-<Info>
-Skyvern supports 23 block types: navigation, extraction, validation, file download, for loops, conditionals, and more. See [Workflow Blocks Reference](/multi-step-automations/workflow-blocks-reference) for the full list.
-</Info>
-
----
-
-## Step 4: Pass data between blocks
-
-When a block completes, its output becomes available to subsequent blocks. This is how you chain steps together: one block extracts data, the next block uses it.
-
-Reference a block's output with `{{ label_output }}` — the block's `label` followed by `_output`. Access nested fields with dot notation: `{{ parse_resume_output.name }}`.
-
-Here, the `apply_to_job` block uses specific fields from the `parse_resume` block's output:
-
-<CodeGroup>
-```json JSON
-{
- "blocks": [
- {
- "label": "parse_resume",
- "block_type": "file_url_parser",
- "file_url": "{{ resume }}",
- "file_type": "pdf"
- },
- {
- "label": "apply_to_job",
- "block_type": "navigation",
- "url": "{{ job_url }}",
- "navigation_goal": "Fill out the job application form.\n\nUse this information:\n- Name: {{ parse_resume_output.name }}\n- Email: {{ parse_resume_output.email }}\n- Experience: {{ parse_resume_output.work_experience }}"
- }
- ]
-}
-```
-
-```yaml YAML
-blocks:
- - label: parse_resume
- block_type: file_url_parser
- file_url: "{{ resume }}"
- file_type: pdf
-
- - label: apply_to_job
- block_type: navigation
- url: "{{ job_url }}"
- navigation_goal: |
- Fill out the job application form.
-
- Use this information:
- - Name: {{ parse_resume_output.name }}
- - Email: {{ parse_resume_output.email }}
- - Experience: {{ parse_resume_output.work_experience }}
-```
-</CodeGroup>
-
-`{{ parse_resume_output.name }}`, `{{ parse_resume_output.email }}`, and `{{ parse_resume_output.work_experience }}` are fields from the structured data the `parse_resume` block extracted from the PDF.
-
-### Looping over output data
-
-When a block produces a list, use a `for_loop` block to process each item. Set `loop_over_parameter_key` to the output field containing the array, and reference the current item with `{{ loop_block_label.current_value }}`.
-
-<CodeGroup>
-```json JSON
-{
- "blocks": [
- {
- "label": "extract_orders",
- "block_type": "extraction",
- "url": "https://example.com/orders",
- "data_extraction_goal": "Extract all order IDs from the page",
- "data_schema": {
- "type": "object",
- "properties": {
- "order_ids": {
- "type": "array",
- "items": { "type": "string" }
- }
- }
- }
- },
- {
- "label": "download_invoices",
- "block_type": "for_loop",
- "loop_over_parameter_key": "extract_orders_output.order_ids",
- "loop_blocks": [
- {
- "label": "download_invoice",
- "block_type": "file_download",
- "url": "https://example.com/invoice/{{ download_invoice.current_value }}",
- "navigation_goal": "Download the invoice PDF"
- }
- ]
- }
- ]
-}
-```
-
-```yaml YAML
-blocks:
- - label: extract_orders
- block_type: extraction
- url: "https://example.com/orders"
- data_extraction_goal: Extract all order IDs from the page
- data_schema:
- type: object
- properties:
- order_ids:
- type: array
- items:
- type: string
-
- - label: download_invoices
- block_type: for_loop
- loop_over_parameter_key: extract_orders_output.order_ids
- loop_blocks:
- - label: download_invoice
- block_type: file_download
- url: "https://example.com/invoice/{{ download_invoice.current_value }}"
- navigation_goal: Download the invoice PDF
-```
-</CodeGroup>
-
-The `for_loop` iterates over the `order_ids` array from the extraction block. Inside the loop, `{{ download_invoice.current_value }}` contains one order ID per iteration.
-
----
-
-## Step 5: Create the workflow
-
-Send the complete workflow definition to the API. Skyvern validates the parameters, blocks, and template references, then returns a `workflow_permanent_id` you use to run the workflow.
-
-The API accepts two formats: pass a JSON object via `json_definition`, or pass a YAML string via `yaml_definition`.
-
-### Using JSON
-
-<CodeGroup>
-```python Python
-import os
-import asyncio
-from skyvern import Skyvern
-
-async def main():
- client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
-
- workflow = await client.create_workflow(
- json_definition={
- "title": "Job Application Workflow",
- "workflow_definition": {
- "parameters": [
- {
- "key": "resume",
- "parameter_type": "workflow",
- "workflow_parameter_type": "file_url"
- },
- {
- "key": "job_url",
- "parameter_type": "workflow",
- "workflow_parameter_type": "string"
- }
- ],
- "blocks": [
- {
- "label": "parse_resume",
- "block_type": "file_url_parser",
- "file_url": "{{ resume }}",
- "file_type": "pdf"
- },
- {
- "label": "apply_to_job",
- "block_type": "navigation",
- "url": "{{ job_url }}",
- "navigation_goal": (
- "Fill out the job application form.\n\n"
- "Use this information:\n"
- "{{ parse_resume_output }}"
- )
- }
- ]
- }
- }
- )
-
- print(f"Workflow ID: {workflow.workflow_permanent_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 workflow = await client.createWorkflow({
- body: {
- json_definition: {
- title: "Job Application Workflow",
- workflow_definition: {
- parameters: [
- {
- key: "resume",
- parameter_type: "workflow",
- workflow_parameter_type: "file_url",
- },
- {
- key: "job_url",
- parameter_type: "workflow",
- workflow_parameter_type: "string",
- },
- ],
- blocks: [
- {
- label: "parse_resume",
- block_type: "file_url_parser",
- file_url: "{{ resume }}",
- file_type: "pdf",
- },
- {
- label: "apply_to_job",
- block_type: "navigation",
- url: "{{ job_url }}",
- navigation_goal: [
- "Fill out the job application form.",
- "",
- "Use this information:",
- "{{ parse_resume_output }}",
- ].join("\n"),
- },
- ],
- },
- },
- },
- });
-
- console.log(`Workflow ID: ${workflow.workflow_permanent_id}`);
-}
-
-main();
-```
-
-```bash cURL
-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": "Job Application Workflow",
- "workflow_definition": {
- "parameters": [
- {
- "key": "resume",
- "parameter_type": "workflow",
- "workflow_parameter_type": "file_url"
- },
- {
- "key": "job_url",
- "parameter_type": "workflow",
- "workflow_parameter_type": "string"
- }
- ],
- "blocks": [
- {
- "label": "parse_resume",
- "block_type": "file_url_parser",
- "file_url": "{{ resume }}",
- "file_type": "pdf"
- },
- {
- "label": "apply_to_job",
- "block_type": "navigation",
- "url": "{{ job_url }}",
- "navigation_goal": "Fill out the job application form.\n\nUse this information:\n{{ parse_resume_output }}"
- }
- ]
- }
- }
- }'
-```
-</CodeGroup>
-
-### Using YAML
-
-Pass the same definition as a YAML string via `yaml_definition`. This is useful when you store workflow definitions in `.yaml` files.
-
-<CodeGroup>
-```python Python
-workflow = await client.create_workflow(
- yaml_definition="""\
-title: Job Application Workflow
-workflow_definition:
- parameters:
- - key: resume
- parameter_type: workflow
- workflow_parameter_type: file_url
- - key: job_url
- parameter_type: workflow
- workflow_parameter_type: string
- blocks:
- - label: parse_resume
- block_type: file_url_parser
- file_url: "{{ resume }}"
- file_type: pdf
- - label: apply_to_job
- block_type: navigation
- url: "{{ job_url }}"
- navigation_goal: |
- Fill out the job application form.
-
- Use this information:
- {{ parse_resume_output }}
-"""
-)
-```
-
-```typescript TypeScript
-const workflow = await client.createWorkflow({
- body: {
- yaml_definition: `
-title: Job Application Workflow
-workflow_definition:
- parameters:
- - key: resume
- parameter_type: workflow
- workflow_parameter_type: file_url
- - key: job_url
- parameter_type: workflow
- workflow_parameter_type: string
- blocks:
- - label: parse_resume
- block_type: file_url_parser
- file_url: "{{ resume }}"
- file_type: pdf
- - label: apply_to_job
- block_type: navigation
- url: "{{ job_url }}"
- navigation_goal: |
- Fill out the job application form.
-
- Use this information:
- {{ parse_resume_output }}
-`.trim(),
- },
-});
-```
-
-```bash cURL
-curl -X POST "https://api.skyvern.com/v1/workflows" \
- -H "x-api-key: $SKYVERN_API_KEY" \
- -H "Content-Type: application/json" \
- -d '{
- "yaml_definition": "title: Job Application Workflow\nworkflow_definition:\n parameters:\n - key: resume\n parameter_type: workflow\n workflow_parameter_type: file_url\n - key: job_url\n parameter_type: workflow\n workflow_parameter_type: string\n blocks:\n - label: parse_resume\n block_type: file_url_parser\n file_url: \"{{ resume }}\"\n file_type: pdf\n - label: apply_to_job\n block_type: navigation\n url: \"{{ job_url }}\"\n navigation_goal: \"Fill out the job application form.\\n\\nUse this information:\\n{{ parse_resume_output }}\"\n"
- }'
-```
-</CodeGroup>
-
-<Tip>
-To load from a file: `await client.create_workflow(yaml_definition=open("workflow.yaml").read())`
-</Tip>
-
-**Example response:**
-
-```json
-{
- "workflow_permanent_id": "wpid_123456789",
- "workflow_id": "wf_987654321",
- "version": 1,
- "title": "Job Application Workflow",
- "workflow_definition": {
- "parameters": [...],
- "blocks": [...]
- },
- "created_at": "2026-01-20T12:00:00.000000",
- "modified_at": "2026-01-20T12:00:00.000000"
-}
-```
-
-Save the `workflow_permanent_id` — you need it to run the workflow.
-
----
-
-## Step 6: Run the workflow
-
-Pass values for the parameters you defined in Step 2. The call returns immediately with a `run_id` — the workflow runs asynchronously in the background.
-
-<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"
- }
-)
-
-print(f"Run ID: {run.run_id}")
-```
-
-```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",
- },
- },
-});
-
-console.log(`Run ID: ${run.run_id}`);
-```
-
-```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"
-}
-```
-
-The response includes a `run_id`. Use this ID to check status and fetch results.
-
----
-
-## Step 7: 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](/going-to-production/webhooks) for authentication and retry options.
-
----
-
-## Understand the response
-
-The response from polling contains the workflow run status and output from each block.
-
-```json
-{
- "run_id": "wr_486305187432193510",
- "run_type": "workflow_run",
- "status": "completed",
- "output": {
- "parse_resume_output": {
- "name": "John Smith",
- "email": "[email protected]",
- "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"
-}
-```
-
-**Response fields:**
-
-| 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 |
-| `created_at` | datetime | When the run started |
-| `modified_at` | datetime | When the run was last updated |
-
-### Block outputs
-
-Each block's output appears in the `output` object with the key `{label}_output`. The structure depends on the block type:
-
-**Navigation/Action blocks:**
-```json
-{
- "apply_to_job_output": {
- "task_id": "tsk_123456",
- "status": "completed",
- "extracted_information": null,
- "failure_reason": null
- }
-}
-```
-
-**Extraction blocks:**
-```json
-{
- "extract_data_output": {
- "product_name": "Widget Pro",
- "price": 99.99,
- "in_stock": true
- }
-}
-```
-
-**For Loop blocks:**
-```json
-{
- "download_invoices_output": [
- { "task_id": "tsk_111", "status": "completed" },
- { "task_id": "tsk_222", "status": "completed" },
- { "task_id": "tsk_333", "status": "completed" }
- ]
-}
-```
-
----
-
-## Complete example
-
-This script creates a job application workflow, runs it, and polls until completion. Copy and run it to get started.
-
-<CodeGroup>
-```python Python
-import os
-import asyncio
-from skyvern import Skyvern
-
-async def main():
- client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
-
- # Create the workflow
- workflow = await client.create_workflow(
- json_definition={
- "title": "Job Application Workflow",
- "workflow_definition": {
- "parameters": [
- {
- "key": "resume",
- "parameter_type": "workflow",
- "workflow_parameter_type": "file_url"
- },
- {
- "key": "job_url",
- "parameter_type": "workflow",
- "workflow_parameter_type": "string"
- }
- ],
- "blocks": [
- {
- "label": "parse_resume",
- "block_type": "file_url_parser",
- "file_url": "{{ resume }}",
- "file_type": "pdf"
- },
- {
- "label": "apply_to_job",
- "block_type": "navigation",
- "url": "{{ job_url }}",
- "navigation_goal": (
- "Fill out the job application form.\n\n"
- "Use this information:\n"
- "{{ parse_resume_output }}"
- )
- }
- ]
- }
- }
- )
- print(f"Created workflow: {workflow.workflow_permanent_id}")
-
- # Run the workflow
- run = await client.run_workflow(
- workflow_id=workflow.workflow_permanent_id,
- parameters={
- "resume": "https://example.com/resume.pdf",
- "job_url": "https://jobs.lever.co/company/position"
- }
- )
- print(f"Started run: {run.run_id}")
-
- # Poll for results
- while True:
- result = await client.get_run(run.run_id)
-
- if result.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
- break
-
- print(f"Status: {result.status}")
- await asyncio.sleep(5)
-
- print(f"Final status: {result.status}")
- print(f"Output: {result.output}")
-
-asyncio.run(main())
-```
-
-```typescript TypeScript
-import { SkyvernClient } from "@skyvern/client";
-
-async function main() {
- const client = new SkyvernClient({
- apiKey: process.env.SKYVERN_API_KEY,
- });
-
- // Create the workflow
- const workflow = await client.createWorkflow({
- body: {
- json_definition: {
- title: "Job Application Workflow",
- workflow_definition: {
- parameters: [
- {
- key: "resume",
- parameter_type: "workflow",
- workflow_parameter_type: "file_url",
- },
- {
- key: "job_url",
- parameter_type: "workflow",
- workflow_parameter_type: "string",
- },
- ],
- blocks: [
- {
- label: "parse_resume",
- block_type: "file_url_parser",
- file_url: "{{ resume }}",
- file_type: "pdf",
- },
- {
- label: "apply_to_job",
- block_type: "navigation",
- url: "{{ job_url }}",
- navigation_goal: [
- "Fill out the job application form.",
- "",
- "Use this information:",
- "{{ parse_resume_output }}",
- ].join("\n"),
- },
- ],
- },
- },
- },
- });
- console.log(`Created workflow: ${workflow.workflow_permanent_id}`);
-
- // Run the workflow
- const run = await client.runWorkflow({
- body: {
- workflow_id: workflow.workflow_permanent_id,
- parameters: {
- resume: "https://example.com/resume.pdf",
- job_url: "https://jobs.lever.co/company/position",
- },
- },
- });
- console.log(`Started run: ${run.run_id}`);
-
- // Poll for results
- while (true) {
- const result = await client.getRun(run.run_id);
-
- if (["completed", "failed", "terminated", "timed_out", "canceled"].includes(result.status)) {
- console.log(`Final status: ${result.status}`);
- console.log(`Output: ${JSON.stringify(result.output, null, 2)}`);
- break;
- }
-
- console.log(`Status: ${result.status}`);
- await new Promise((resolve) => setTimeout(resolve, 5000));
- }
-}
-
-main();
-```
-
-```bash cURL
-#!/bin/bash
-
-# Create the workflow
-WORKFLOW=$(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": "Job Application Workflow",
- "workflow_definition": {
- "parameters": [
- {
- "key": "resume",
- "parameter_type": "workflow",
- "workflow_parameter_type": "file_url"
- },
- {
- "key": "job_url",
- "parameter_type": "workflow",
- "workflow_parameter_type": "string"
- }
- ],
- "blocks": [
- {
- "label": "parse_resume",
- "block_type": "file_url_parser",
- "file_url": "{{ resume }}",
- "file_type": "pdf"
- },
- {
- "label": "apply_to_job",
- "block_type": "navigation",
- "url": "{{ job_url }}",
- "navigation_goal": "Fill out the job application form.\n\nUse this information:\n{{ parse_resume_output }}"
- }
- ]
- }
- }
- }')
-
-WORKFLOW_ID=$(echo "$WORKFLOW" | jq -r '.workflow_permanent_id')
-echo "Created workflow: $WORKFLOW_ID"
-
-# Run the workflow
-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\",
- \"parameters\": {
- \"resume\": \"https://example.com/resume.pdf\",
- \"job_url\": \"https://jobs.lever.co/company/position\"
- }
- }")
-
-RUN_ID=$(echo "$RUN" | jq -r '.run_id')
-echo "Started run: $RUN_ID"
-
-# Poll for results
-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>
-
----
-
-## List your 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>
-
----
-
-## Next steps
-
-<CardGroup cols={2}>
- <Card
- title="Workflow Blocks Reference"
- icon="cube"
- href="/multi-step-automations/workflow-blocks-reference"
- >
- Detailed documentation for all 23 block types
- </Card>
- <Card
- title="Workflow Parameters"
- icon="sliders"
- href="/multi-step-automations/workflow-parameters"
- >
- Configure proxies, webhooks, and other run options
- </Card>
- <Card
- title="File Operations"
- icon="file"
- href="/multi-step-automations/file-operations"
- >
- Download, parse, and upload files in workflows
- </Card>
- <Card
- title="Schedule a Workflow"
- icon="calendar"
- href="/multi-step-automations/scheduling-workflows"
- >
- Run workflows automatically on a recurring cron schedule
- </Card>
-</CardGroup>
diff --git a/docs/multi-step-automations/file-operations.mdx b/docs/multi-step-automations/file-operations.mdx
deleted file mode 100644
index 116371637..000000000
--- a/docs/multi-step-automations/file-operations.mdx
+++ /dev/null
@@ -1,2085 +0,0 @@
----
-title: File Operations
-subtitle: Download, parse, and upload files in workflows
-description: Download, parse, and upload files in Skyvern workflows using file download, file parser, and upload blocks. Handle PDFs, CSVs, Excel files, and pass files between workflow blocks.
-slug: multi-step-automations/file-operations
-keywords:
- - file download
- - file upload
- - file parser
- - PDF
- - CSV
- - Excel
- - S3
- - download_to_s3
- - upload_to_s3
----
-
-Workflows often need to handle files: downloading invoices, parsing spreadsheets, uploading documents to storage. This page covers the four core file operations: downloading, parsing, saving, and passing files between blocks.
-
-<Info>
-This page uses workflow template syntax (`{{ parameter }}`, `{{ label_output }}`) and assumes familiarity with blocks. See [Build a Workflow](/multi-step-automations/build-a-workflow) for an introduction.
-</Info>
-
----
-
-## Downloading files
-
-When your workflow needs to retrieve documents from a website — invoices from a vendor portal, confirmation letters after form submission, compliance certificates — use `file_download`. Downloaded files land in `SKYVERN_DOWNLOAD_DIRECTORY`, a temporary directory created for each workflow run. Every file downloaded during a run accumulates here, and you can reference this directory in later blocks to upload or email the files.
-
-### Downloading a single file
-
-Say you've just filed an SS-4 form on the IRS website and need to grab the EIN confirmation letter. The `file_download` block navigates the page and triggers the download:
-
-<CodeGroup>
-```python Python
-import os
-import asyncio
-from skyvern import Skyvern
-
-async def main():
- client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
-
- # Create the workflow
- workflow = await client.create_workflow(
- json_definition={
- "title": "Download EIN Letter",
- "workflow_definition": {
- "parameters": [],
- "blocks": [
- {
- "block_type": "file_download",
- "label": "download_ein_letter",
- "url": "https://sa.www4.irs.gov/modiein/individual/index.jsp",
- "navigation_goal": (
- "Find and download the EIN confirmation letter PDF. "
- "Look for a Download or Print button. "
- "COMPLETE when the download starts."
- ),
- "download_suffix": "ein_confirmation.pdf"
- }
- ]
- }
- }
- )
- print(f"Workflow ID: {workflow.workflow_permanent_id}")
-
- # Run the workflow
- run = await client.run_workflow(workflow_id=workflow.workflow_permanent_id)
- print(f"Run ID: {run.run_id}")
-
- # Poll until complete
- while True:
- result = await client.get_run(run.run_id)
- if result.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
- break
- print(f"Status: {result.status}")
- await asyncio.sleep(5)
-
- print(f"Final status: {result.status}")
- print(f"Output: {result.output}")
-
-asyncio.run(main())
-```
-
-```typescript TypeScript
-import { SkyvernClient } from "@skyvern/client";
-
-async function main() {
- const client = new SkyvernClient({
- apiKey: process.env.SKYVERN_API_KEY,
- });
-
- // Create the workflow
- const workflow = await client.createWorkflow({
- body: {
- json_definition: {
- title: "Download EIN Letter",
- workflow_definition: {
- parameters: [],
- blocks: [
- {
- block_type: "file_download",
- label: "download_ein_letter",
- url: "https://sa.www4.irs.gov/modiein/individual/index.jsp",
- navigation_goal: [
- "Find and download the EIN confirmation letter PDF.",
- "Look for a Download or Print button.",
- "COMPLETE when the download starts.",
- ].join(" "),
- download_suffix: "ein_confirmation.pdf",
- },
- ],
- },
- },
- },
- });
- console.log(`Workflow ID: ${workflow.workflow_permanent_id}`);
-
- // Run the workflow
- const run = await client.runWorkflow({
- body: { workflow_id: workflow.workflow_permanent_id },
- });
- console.log(`Run ID: ${run.run_id}`);
-
- // Poll until complete
- while (true) {
- const result = await client.getRun(run.run_id);
- if (
- ["completed", "failed", "terminated", "timed_out", "canceled"].includes(
- result.status
- )
- ) {
- console.log(`Final status: ${result.status}`);
- console.log(`Output: ${JSON.stringify(result.output, null, 2)}`);
- break;
- }
- console.log(`Status: ${result.status}`);
- await new Promise((resolve) => setTimeout(resolve, 5000));
- }
-}
-
-main();
-```
-
-```bash cURL
-# Create the workflow
-WORKFLOW=$(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": "Download EIN Letter",
- "workflow_definition": {
- "parameters": [],
- "blocks": [
- {
- "block_type": "file_download",
- "label": "download_ein_letter",
- "url": "https://sa.www4.irs.gov/modiein/individual/index.jsp",
- "navigation_goal": "Find and download the EIN confirmation letter PDF. Look for a Download or Print button. COMPLETE when the download starts.",
- "download_suffix": "ein_confirmation.pdf"
- }
- ]
- }
- }
- }')
-
-WORKFLOW_ID=$(echo "$WORKFLOW" | jq -r '.workflow_permanent_id')
-echo "Workflow ID: $WORKFLOW_ID"
-
-# Run the workflow
-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')
-echo "Run ID: $RUN_ID"
-
-# Poll until complete
-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>
-
-Three fields drive this block:
-
-- **`navigation_goal`** tells Skyvern what to do on the page — find the download button, click it, and mark the task complete when the download starts. Write this the way you'd explain the task to a colleague looking at the screen.
-- **`download_suffix`** names the downloaded file. Without it, you'd get a generic filename. Use a descriptive suffix so you can identify the file later when you upload or email it.
-- **`url`** sets the starting page. If your previous block already navigated to the right page, omit `url` and the download block continues from there.
-
-| Parameter | Type | Use this to |
-|-----------|------|-------------|
-| `navigation_goal` | string | Describe how to find and click the download button |
-| `url` | string | Set the starting page (omit to continue from previous block) |
-| `download_suffix` | string | Set the filename for the downloaded file |
-| `download_timeout` | number | Allow more time for large files (in seconds) |
-| `parameter_keys` | array | List workflow parameters this block can access |
-| `max_retries` | integer | Retry the block on failure |
-| `max_steps_per_run` | integer | Limit how many actions the block can take |
-| `engine` | string | Set the AI engine (`skyvern-1.0` or `skyvern-2.0`) |
-
-For the full parameter list, see [File Download](/multi-step-automations/workflow-blocks-reference#file-download) in the blocks reference.
-
-### Downloading multiple files
-
-When you need to download a batch of files — say, all monthly invoices from a vendor portal — pair a `for_loop` with `file_download`. A prior block (like an extraction) returns a list of URLs, and the loop downloads each one.
-
-Here, `get_invoices` is an extraction block that scrapes invoice URLs from the portal. The loop iterates over its output and downloads each one:
-
-<CodeGroup>
-```python Python
-import os
-import asyncio
-from skyvern import Skyvern
-
-async def main():
- client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
-
- # Create the workflow
- workflow = await client.create_workflow(
- json_definition={
- "title": "Download All Invoices",
- "workflow_definition": {
- "parameters": [
- {
- "key": "portal_url",
- "parameter_type": "workflow",
- "workflow_parameter_type": "string"
- }
- ],
- "blocks": [
- {
- "block_type": "extraction",
- "label": "get_invoices",
- "url": "{{ portal_url }}",
- "data_extraction_goal": "Extract all invoice download URLs from this page"
- },
- {
- "block_type": "for_loop",
- "label": "download_all_invoices",
- "loop_over_parameter_key": "get_invoices_output",
- "continue_on_failure": True,
- "loop_blocks": [
- {
- "block_type": "file_download",
- "label": "download_invoice",
- "url": "{{ download_invoice.current_value }}",
- "navigation_goal": "Download the invoice PDF from this page"
- }
- ]
- }
- ]
- }
- }
- )
- print(f"Workflow ID: {workflow.workflow_permanent_id}")
-
- # Run the workflow with parameters
- run = await client.run_workflow(
- workflow_id=workflow.workflow_permanent_id,
- parameters={"portal_url": "https://vendor.example.com/invoices"}
- )
- print(f"Run ID: {run.run_id}")
-
- # Poll until complete
- while True:
- result = await client.get_run(run.run_id)
- if result.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
- break
- print(f"Status: {result.status}")
- await asyncio.sleep(5)
-
- print(f"Final status: {result.status}")
- print(f"Output: {result.output}")
-
-asyncio.run(main())
-```
-
-```typescript TypeScript
-import { SkyvernClient } from "@skyvern/client";
-
-async function main() {
- const client = new SkyvernClient({
- apiKey: process.env.SKYVERN_API_KEY,
- });
-
- // Create the workflow
- const workflow = await client.createWorkflow({
- body: {
- json_definition: {
- title: "Download All Invoices",
- workflow_definition: {
- parameters: [
- {
- key: "portal_url",
- parameter_type: "workflow",
- workflow_parameter_type: "string",
- },
- ],
- blocks: [
- {
- block_type: "extraction",
- label: "get_invoices",
- url: "{{ portal_url }}",
- data_extraction_goal:
- "Extract all invoice download URLs from this page",
- },
- {
- block_type: "for_loop",
- label: "download_all_invoices",
- loop_over_parameter_key: "get_invoices_output",
- continue_on_failure: true,
- loop_blocks: [
- {
- block_type: "file_download",
- label: "download_invoice",
- url: "{{ download_invoice.current_value }}",
- navigation_goal: "Download the invoice PDF from this page",
- },
- ],
- },
- ],
- },
- },
- },
- });
- console.log(`Workflow ID: ${workflow.workflow_permanent_id}`);
-
- // Run the workflow with parameters
- const run = await client.runWorkflow({
- body: {
- workflow_id: workflow.workflow_permanent_id,
- parameters: { portal_url: "https://vendor.example.com/invoices" },
- },
- });
- console.log(`Run ID: ${run.run_id}`);
-
- // Poll until complete
- while (true) {
- const result = await client.getRun(run.run_id);
- if (
- ["completed", "failed", "terminated", "timed_out", "canceled"].includes(
- result.status
- )
- ) {
- console.log(`Final status: ${result.status}`);
- console.log(`Output: ${JSON.stringify(result.output, null, 2)}`);
- break;
- }
- console.log(`Status: ${result.status}`);
- await new Promise((resolve) => setTimeout(resolve, 5000));
- }
-}
-
-main();
-```
-
-```bash cURL
-# Create the workflow
-WORKFLOW=$(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": "Download All Invoices",
- "workflow_definition": {
- "parameters": [
- {
- "key": "portal_url",
- "parameter_type": "workflow",
- "workflow_parameter_type": "string"
- }
- ],
- "blocks": [
- {
- "block_type": "extraction",
- "label": "get_invoices",
- "url": "{{ portal_url }}",
- "data_extraction_goal": "Extract all invoice download URLs from this page"
- },
- {
- "block_type": "for_loop",
- "label": "download_all_invoices",
- "loop_over_parameter_key": "get_invoices_output",
- "continue_on_failure": true,
- "loop_blocks": [
- {
- "block_type": "file_download",
- "label": "download_invoice",
- "url": "{{ download_invoice.current_value }}",
- "navigation_goal": "Download the invoice PDF from this page"
- }
- ]
- }
- ]
- }
- }
- }')
-
-WORKFLOW_ID=$(echo "$WORKFLOW" | jq -r '.workflow_permanent_id')
-echo "Workflow ID: $WORKFLOW_ID"
-
-# Run the workflow with parameters
-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\",
- \"parameters\": {
- \"portal_url\": \"https://vendor.example.com/invoices\"
- }
- }")
-
-RUN_ID=$(echo "$RUN" | jq -r '.run_id')
-echo "Run ID: $RUN_ID"
-
-# Poll until complete
-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>
-
-- **`loop_over_parameter_key`** points to the output of the prior extraction block (`get_invoices_output`).
-- **`{{ download_invoice.current_value }}`** gives you one URL per iteration — the inner block's label (`download_invoice`) followed by `.current_value`.
-- **`continue_on_failure: true`** on the loop means a single failed download won't stop the rest. All successful downloads still land in `SKYVERN_DOWNLOAD_DIRECTORY`.
-
-<Note>
-If a download fails, the block fails. Set `continue_on_failure: true` on the loop (as shown above) so a single failed download doesn't stop the entire workflow.
-</Note>
-
----
-
-## Parsing files
-
-When your workflow needs to act on information inside a file — filling forms with resume data, processing orders from a spreadsheet, extracting fields from a PDF — use `file_url_parser`. It downloads the file, parses it, and returns structured data you can use in subsequent blocks.
-
-### Parsing a PDF with a schema
-
-Say you're building a workflow that applies to jobs on Lever. You have a candidate's resume as a PDF URL and need to extract their name, email, and work history so a later navigation block can fill the application form.
-
-Define the fields you want in a `json_schema`, and Skyvern uses an LLM to extract them:
-
-<CodeGroup>
-```python Python
-import os
-import asyncio
-from skyvern import Skyvern
-
-async def main():
- client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
-
- # Create the workflow
- workflow = await client.create_workflow(
- json_definition={
- "title": "Parse Resume",
- "workflow_definition": {
- "parameters": [
- {
- "key": "resume",
- "parameter_type": "workflow",
- "workflow_parameter_type": "file_url",
- "description": "URL to the resume PDF"
- }
- ],
- "blocks": [
- {
- "block_type": "file_url_parser",
- "label": "parse_resume",
- "file_url": "{{ resume }}",
- "file_type": "pdf",
- "json_schema": {
- "type": "object",
- "properties": {
- "name": {"type": "string"},
- "email": {"type": "string"},
- "work_experience": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "company": {"type": "string"},
- "role": {"type": "string"}
- }
- }
- }
- }
- }
- }
- ]
- }
- }
- )
- print(f"Workflow ID: {workflow.workflow_permanent_id}")
-
- # Run the workflow with a resume URL
- run = await client.run_workflow(
- workflow_id=workflow.workflow_permanent_id,
- parameters={
- "resume": "https://writing.colostate.edu/guides/documents/resume/functionalsample.pdf"
- }
- )
- print(f"Run ID: {run.run_id}")
-
- # Poll until complete
- while True:
- result = await client.get_run(run.run_id)
- if result.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
- break
- print(f"Status: {result.status}")
- await asyncio.sleep(5)
-
- print(f"Final status: {result.status}")
- print(f"Output: {result.output}")
-
-asyncio.run(main())
-```
-
-```typescript TypeScript
-import { SkyvernClient } from "@skyvern/client";
-
-async function main() {
- const client = new SkyvernClient({
- apiKey: process.env.SKYVERN_API_KEY,
- });
-
- // Create the workflow
- const workflow = await client.createWorkflow({
- body: {
- json_definition: {
- title: "Parse Resume",
- workflow_definition: {
- parameters: [
- {
- key: "resume",
- parameter_type: "workflow",
- workflow_parameter_type: "file_url",
- description: "URL to the resume PDF",
- },
- ],
- blocks: [
- {
- block_type: "file_url_parser",
- label: "parse_resume",
- file_url: "{{ resume }}",
- file_type: "pdf",
- json_schema: {
- type: "object",
- properties: {
- name: { type: "string" },
- email: { type: "string" },
- work_experience: {
- type: "array",
- items: {
- type: "object",
- properties: {
- company: { type: "string" },
- role: { type: "string" },
- },
- },
- },
- },
- },
- },
- ],
- },
- },
- },
- });
- console.log(`Workflow ID: ${workflow.workflow_permanent_id}`);
-
- // Run the workflow with a resume URL
- const run = await client.runWorkflow({
- body: {
- workflow_id: workflow.workflow_permanent_id,
- parameters: {
- resume:
- "https://writing.colostate.edu/guides/documents/resume/functionalsample.pdf",
- },
- },
- });
- console.log(`Run ID: ${run.run_id}`);
-
- // Poll until complete
- while (true) {
- const result = await client.getRun(run.run_id);
- if (
- ["completed", "failed", "terminated", "timed_out", "canceled"].includes(
- result.status
- )
- ) {
- console.log(`Final status: ${result.status}`);
- console.log(`Output: ${JSON.stringify(result.output, null, 2)}`);
- break;
- }
- console.log(`Status: ${result.status}`);
- await new Promise((resolve) => setTimeout(resolve, 5000));
- }
-}
-
-main();
-```
-
-```bash cURL
-# Create the workflow
-WORKFLOW=$(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": "Parse Resume",
- "workflow_definition": {
- "parameters": [
- {
- "key": "resume",
- "parameter_type": "workflow",
- "workflow_parameter_type": "file_url",
- "description": "URL to the resume PDF"
- }
- ],
- "blocks": [
- {
- "block_type": "file_url_parser",
- "label": "parse_resume",
- "file_url": "{{ resume }}",
- "file_type": "pdf",
- "json_schema": {
- "type": "object",
- "properties": {
- "name": {"type": "string"},
- "email": {"type": "string"},
- "work_experience": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "company": {"type": "string"},
- "role": {"type": "string"}
- }
- }
- }
- }
- }
- }
- ]
- }
- }
- }')
-
-WORKFLOW_ID=$(echo "$WORKFLOW" | jq -r '.workflow_permanent_id')
-echo "Workflow ID: $WORKFLOW_ID"
-
-# Run the workflow with a resume URL
-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\",
- \"parameters\": {
- \"resume\": \"https://writing.colostate.edu/guides/documents/resume/functionalsample.pdf\"
- }
- }")
-
-RUN_ID=$(echo "$RUN" | jq -r '.run_id')
-echo "Run ID: $RUN_ID"
-
-# Poll until complete
-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>
-
-- **`file_url`** points to the file. Here, `{{ resume }}` is a workflow parameter passed at runtime — it could be a public URL, an S3 presigned URL, or a Google Drive link.
-- **`file_type`** tells Skyvern how to read the file. Use `csv`, `excel`, `pdf`, `image`, or `docx`.
-- **`json_schema`** defines exactly what to extract. The LLM reads the PDF and returns data matching this structure. The `work_experience` array means you'll get one object per job with `company` and `role` fields.
-
-The output is available as `{{ parse_resume_output }}` in subsequent blocks and looks like this:
-
-```json
-{
- "name": "Jane Doe",
- "email": "[email protected]",
- "work_experience": [
- { "company": "Acme Corp", "role": "Software Engineer" },
- { "company": "Globex Inc", "role": "Tech Lead" }
- ]
-}
-```
-
-Without a `json_schema`, you get the raw parsed content instead — plain text for PDFs, or an array of row objects for CSVs. The schema is what turns unstructured file content into typed, structured data.
-
-| Parameter | Type | Use this to |
-|-----------|------|-------------|
-| `file_url` | string | Point to the file (HTTP URL, S3 URI, or parameter like `{{ resume }}`) |
-| `file_type` | string | Specify format: `csv`, `excel`, `pdf`, `image`, or `docx` |
-| `json_schema` | object | Define the structure you want extracted |
-
-**Supported sources for `file_url`:**
-- HTTP/HTTPS URLs
-- S3 URIs (`s3://bucket/path/file.csv`)
-- Azure Blob URIs (`azure://container/path/file.xlsx`)
-- Google Drive links (auto-converted)
-- Workflow parameters (`{{ parameter_name }}`)
-
-### Parsing a CSV and processing each row
-
-Say your procurement team exports purchase orders as a CSV and you need to enter each one into your web-based ERP. First parse the CSV, then loop over the rows:
-
-<CodeGroup>
-```python Python
-import os
-import asyncio
-from skyvern import Skyvern
-
-async def main():
- client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
-
- # Create the workflow
- workflow = await client.create_workflow(
- json_definition={
- "title": "Import Purchase Orders",
- "workflow_definition": {
- "parameters": [
- {
- "key": "orders_csv",
- "parameter_type": "workflow",
- "workflow_parameter_type": "file_url"
- }
- ],
- "blocks": [
- {
- "block_type": "file_url_parser",
- "label": "parse_orders",
- "file_url": "{{ orders_csv }}",
- "file_type": "csv"
- },
- {
- "block_type": "for_loop",
- "label": "process_orders",
- "loop_over_parameter_key": "parse_orders_output",
- "loop_blocks": [
- {
- "block_type": "navigation",
- "label": "enter_order",
- "url": "https://erp.example.com/orders/new",
- "navigation_goal": "Create a new order with: {{ enter_order.current_value }}"
- }
- ]
- }
- ]
- }
- }
- )
- print(f"Workflow ID: {workflow.workflow_permanent_id}")
-
- # Run the workflow with a CSV URL
- run = await client.run_workflow(
- workflow_id=workflow.workflow_permanent_id,
- parameters={
- "orders_csv": "https://example.com/purchase_orders.csv"
- }
- )
- print(f"Run ID: {run.run_id}")
-
- # Poll until complete
- while True:
- result = await client.get_run(run.run_id)
- if result.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
- break
- print(f"Status: {result.status}")
- await asyncio.sleep(5)
-
- print(f"Final status: {result.status}")
- print(f"Output: {result.output}")
-
-asyncio.run(main())
-```
-
-```typescript TypeScript
-import { SkyvernClient } from "@skyvern/client";
-
-async function main() {
- const client = new SkyvernClient({
- apiKey: process.env.SKYVERN_API_KEY,
- });
-
- // Create the workflow
- const workflow = await client.createWorkflow({
- body: {
- json_definition: {
- title: "Import Purchase Orders",
- workflow_definition: {
- parameters: [
- {
- key: "orders_csv",
- parameter_type: "workflow",
- workflow_parameter_type: "file_url",
- },
- ],
- blocks: [
- {
- block_type: "file_url_parser",
- label: "parse_orders",
- file_url: "{{ orders_csv }}",
- file_type: "csv",
- },
- {
- block_type: "for_loop",
- label: "process_orders",
- loop_over_parameter_key: "parse_orders_output",
- loop_blocks: [
- {
- block_type: "navigation",
- label: "enter_order",
- url: "https://erp.example.com/orders/new",
- navigation_goal:
- "Create a new order with: {{ enter_order.current_value }}",
- },
- ],
- },
- ],
- },
- },
- },
- });
- console.log(`Workflow ID: ${workflow.workflow_permanent_id}`);
-
- // Run the workflow with a CSV URL
- const run = await client.runWorkflow({
- body: {
- workflow_id: workflow.workflow_permanent_id,
- parameters: {
- orders_csv: "https://example.com/purchase_orders.csv",
- },
- },
- });
- console.log(`Run ID: ${run.run_id}`);
-
- // Poll until complete
- while (true) {
- const result = await client.getRun(run.run_id);
- if (
- ["completed", "failed", "terminated", "timed_out", "canceled"].includes(
- result.status
- )
- ) {
- console.log(`Final status: ${result.status}`);
- console.log(`Output: ${JSON.stringify(result.output, null, 2)}`);
- break;
- }
- console.log(`Status: ${result.status}`);
- await new Promise((resolve) => setTimeout(resolve, 5000));
- }
-}
-
-main();
-```
-
-```bash cURL
-# Create the workflow
-WORKFLOW=$(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": "Import Purchase Orders",
- "workflow_definition": {
- "parameters": [
- {
- "key": "orders_csv",
- "parameter_type": "workflow",
- "workflow_parameter_type": "file_url"
- }
- ],
- "blocks": [
- {
- "block_type": "file_url_parser",
- "label": "parse_orders",
- "file_url": "{{ orders_csv }}",
- "file_type": "csv"
- },
- {
- "block_type": "for_loop",
- "label": "process_orders",
- "loop_over_parameter_key": "parse_orders_output",
- "loop_blocks": [
- {
- "block_type": "navigation",
- "label": "enter_order",
- "url": "https://erp.example.com/orders/new",
- "navigation_goal": "Create a new order with: {{ enter_order.current_value }}"
- }
- ]
- }
- ]
- }
- }
- }')
-
-WORKFLOW_ID=$(echo "$WORKFLOW" | jq -r '.workflow_permanent_id')
-echo "Workflow ID: $WORKFLOW_ID"
-
-# Run the workflow with a CSV URL
-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\",
- \"parameters\": {
- \"orders_csv\": \"https://example.com/purchase_orders.csv\"
- }
- }")
-
-RUN_ID=$(echo "$RUN" | jq -r '.run_id')
-echo "Run ID: $RUN_ID"
-
-# Poll until complete
-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>
-
-CSV parsing returns an array of objects — one per row, with column headers as keys. No `json_schema` needed for CSVs since the column headers already provide structure:
-
-```json
-[
- { "order_id": "ORD-001", "product": "Widget", "quantity": "10" },
- { "order_id": "ORD-002", "product": "Gadget", "quantity": "5" }
-]
-```
-
-The `for_loop` iterates over this array. On each iteration, `{{ enter_order.current_value }}` contains one row object (e.g., `{ "order_id": "ORD-001", "product": "Widget", "quantity": "10" }`), which the navigation block uses to fill the ERP form.
-
----
-
-## Saving files
-
-When your workflow needs to store downloaded files permanently — archiving invoices, sending reports to a shared bucket, integrating with other systems — use one of the upload blocks.
-
-| Block | When to use it |
-|-------|---------------|
-| `upload_to_s3` | Store files in Skyvern's managed S3. Simplest option — no credentials needed. |
-| `file_upload` | Store files in your own S3 bucket or Azure Blob Storage. Use when you need files in your infrastructure. |
-| `download_to_s3` | Save a file from a URL directly to Skyvern's S3, skipping the browser. Use when you already have the file URL. |
-
-### Upload to Skyvern's S3
-
-After downloading EIN confirmation letters from the IRS, archive them to Skyvern's managed S3. Pass `SKYVERN_DOWNLOAD_DIRECTORY` as the path and the block uploads every file downloaded during this run:
-
-<CodeGroup>
-```python Python
-import os
-import asyncio
-from skyvern import Skyvern
-
-async def main():
- client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
-
- # Create the workflow
- workflow = await client.create_workflow(
- json_definition={
- "title": "Archive Downloads to S3",
- "workflow_definition": {
- "parameters": [],
- "blocks": [
- {
- "block_type": "upload_to_s3",
- "label": "save_invoices",
- "path": "SKYVERN_DOWNLOAD_DIRECTORY"
- }
- ]
- }
- }
- )
- print(f"Workflow ID: {workflow.workflow_permanent_id}")
-
- # Run the workflow
- run = await client.run_workflow(workflow_id=workflow.workflow_permanent_id)
- print(f"Run ID: {run.run_id}")
-
- # Poll until complete
- while True:
- result = await client.get_run(run.run_id)
- if result.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
- break
- print(f"Status: {result.status}")
- await asyncio.sleep(5)
-
- print(f"Final status: {result.status}")
- print(f"Output: {result.output}")
-
-asyncio.run(main())
-```
-
-```typescript TypeScript
-import { SkyvernClient } from "@skyvern/client";
-
-async function main() {
- const client = new SkyvernClient({
- apiKey: process.env.SKYVERN_API_KEY,
- });
-
- // Create the workflow
- const workflow = await client.createWorkflow({
- body: {
- json_definition: {
- title: "Archive Downloads to S3",
- workflow_definition: {
- parameters: [],
- blocks: [
- {
- block_type: "upload_to_s3",
- label: "save_invoices",
- path: "SKYVERN_DOWNLOAD_DIRECTORY",
- },
- ],
- },
- },
- },
- });
- console.log(`Workflow ID: ${workflow.workflow_permanent_id}`);
-
- // Run the workflow
- const run = await client.runWorkflow({
- body: { workflow_id: workflow.workflow_permanent_id },
- });
- console.log(`Run ID: ${run.run_id}`);
-
- // Poll until complete
- while (true) {
- const result = await client.getRun(run.run_id);
- if (
- ["completed", "failed", "terminated", "timed_out", "canceled"].includes(
- result.status
- )
- ) {
- console.log(`Final status: ${result.status}`);
- console.log(`Output: ${JSON.stringify(result.output, null, 2)}`);
- break;
- }
- console.log(`Status: ${result.status}`);
- await new Promise((resolve) => setTimeout(resolve, 5000));
- }
-}
-
-main();
-```
-
-```bash cURL
-# Create the workflow
-WORKFLOW=$(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": "Archive Downloads to S3",
- "workflow_definition": {
- "parameters": [],
- "blocks": [
- {
- "block_type": "upload_to_s3",
- "label": "save_invoices",
- "path": "SKYVERN_DOWNLOAD_DIRECTORY"
- }
- ]
- }
- }
- }')
-
-WORKFLOW_ID=$(echo "$WORKFLOW" | jq -r '.workflow_permanent_id')
-echo "Workflow ID: $WORKFLOW_ID"
-
-# Run the workflow
-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')
-echo "Run ID: $RUN_ID"
-
-# Poll until complete
-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>
-
-The output (`{{ save_invoices_output }}`) is a list of S3 URIs you can return from your workflow or pass to subsequent blocks.
-
-| Parameter | Type | Use this to |
-|-----------|------|-------------|
-| `path` | string | Specify what to upload (`SKYVERN_DOWNLOAD_DIRECTORY` or a specific file path) |
-
-**Limit:** 50 files maximum per upload.
-
-### Upload to your own storage
-
-When compliance certificates need to land in your company's own S3 bucket (not Skyvern's), use `file_upload` with your AWS credentials:
-
-<CodeGroup>
-```python Python
-import os
-import asyncio
-from skyvern import Skyvern
-
-async def main():
- client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
-
- # Create the workflow with AWS Secrets Manager-backed credentials
- workflow = await client.create_workflow(
- json_definition={
- "title": "Upload to Company S3",
- "workflow_definition": {
- "parameters": [
- {
- "key": "aws_key",
- "parameter_type": "aws_secret",
- "aws_key": "skyvern/aws/access_key_id"
- },
- {
- "key": "aws_secret",
- "parameter_type": "aws_secret",
- "aws_key": "skyvern/aws/secret_access_key"
- }
- ],
- "blocks": [
- {
- "block_type": "file_upload",
- "label": "upload_to_company_bucket",
- "storage_type": "s3",
- "s3_bucket": "company-documents",
- "aws_access_key_id": "{{ aws_key }}",
- "aws_secret_access_key": "{{ aws_secret }}",
- "region_name": "us-west-2",
- "path": "SKYVERN_DOWNLOAD_DIRECTORY"
- }
- ]
- }
- }
- )
- print(f"Workflow ID: {workflow.workflow_permanent_id}")
-
- # Run the workflow (credentials auto-resolve from AWS Secrets Manager)
- run = await client.run_workflow(workflow_id=workflow.workflow_permanent_id)
- print(f"Run ID: {run.run_id}")
-
- # Poll until complete
- while True:
- result = await client.get_run(run.run_id)
- if result.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
- break
- print(f"Status: {result.status}")
- await asyncio.sleep(5)
-
- print(f"Final status: {result.status}")
- print(f"Output: {result.output}")
-
-asyncio.run(main())
-```
-
-```typescript TypeScript
-import { SkyvernClient } from "@skyvern/client";
-
-async function main() {
- const client = new SkyvernClient({
- apiKey: process.env.SKYVERN_API_KEY,
- });
-
- // Create the workflow with AWS Secrets Manager-backed credentials
- const workflow = await client.createWorkflow({
- body: {
- json_definition: {
- title: "Upload to Company S3",
- workflow_definition: {
- parameters: [
- {
- key: "aws_key",
- parameter_type: "aws_secret",
- aws_key: "skyvern/aws/access_key_id",
- },
- {
- key: "aws_secret",
- parameter_type: "aws_secret",
- aws_key: "skyvern/aws/secret_access_key",
- },
- ],
- blocks: [
- {
- block_type: "file_upload",
- label: "upload_to_company_bucket",
- storage_type: "s3",
- s3_bucket: "company-documents",
- aws_access_key_id: "{{ aws_key }}",
- aws_secret_access_key: "{{ aws_secret }}",
- region_name: "us-west-2",
- path: "SKYVERN_DOWNLOAD_DIRECTORY",
- },
- ],
- },
- },
- },
- });
- console.log(`Workflow ID: ${workflow.workflow_permanent_id}`);
-
- // Run the workflow (credentials auto-resolve from AWS Secrets Manager)
- const run = await client.runWorkflow({
- body: {
- workflow_id: workflow.workflow_permanent_id,
- },
- });
- console.log(`Run ID: ${run.run_id}`);
-
- // Poll until complete
- while (true) {
- const result = await client.getRun(run.run_id);
- if (
- ["completed", "failed", "terminated", "timed_out", "canceled"].includes(
- result.status
- )
- ) {
- console.log(`Final status: ${result.status}`);
- console.log(`Output: ${JSON.stringify(result.output, null, 2)}`);
- break;
- }
- console.log(`Status: ${result.status}`);
- await new Promise((resolve) => setTimeout(resolve, 5000));
- }
-}
-
-main();
-```
-
-```bash cURL
-# Create the workflow with AWS Secrets Manager-backed credentials
-WORKFLOW=$(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": "Upload to Company S3",
- "workflow_definition": {
- "parameters": [
- {
- "key": "aws_key",
- "parameter_type": "aws_secret",
- "aws_key": "skyvern/aws/access_key_id"
- },
- {
- "key": "aws_secret",
- "parameter_type": "aws_secret",
- "aws_key": "skyvern/aws/secret_access_key"
- }
- ],
- "blocks": [
- {
- "block_type": "file_upload",
- "label": "upload_to_company_bucket",
- "storage_type": "s3",
- "s3_bucket": "company-documents",
- "aws_access_key_id": "{{ aws_key }}",
- "aws_secret_access_key": "{{ aws_secret }}",
- "region_name": "us-west-2",
- "path": "SKYVERN_DOWNLOAD_DIRECTORY"
- }
- ]
- }
- }
- }')
-
-WORKFLOW_ID=$(echo "$WORKFLOW" | jq -r '.workflow_permanent_id')
-echo "Workflow ID: $WORKFLOW_ID"
-
-# Run the workflow (credentials auto-resolve from AWS Secrets Manager)
-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')
-echo "Run ID: $RUN_ID"
-
-# Poll until complete
-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>
-
-- **`storage_type`** selects the destination: `s3` for AWS, `azure` for Azure Blob Storage.
-- **Credentials** should use `aws_secret` parameters backed by AWS Secrets Manager — credentials auto-resolve at runtime without being passed in the run payload.
-- **`path`** works the same as `upload_to_s3` — pass `SKYVERN_DOWNLOAD_DIRECTORY` to upload everything, or a specific file path.
-
-| Parameter | Type | Use this to |
-|-----------|------|-------------|
-| `storage_type` | string | Choose `s3` or `azure` |
-| `path` | string | Specify what to upload (`SKYVERN_DOWNLOAD_DIRECTORY` or a file path) |
-
-**S3 parameters:** `s3_bucket`, `aws_access_key_id`, `aws_secret_access_key`, `region_name`
-
-**Azure parameters:** `azure_storage_account_name`, `azure_storage_account_key`, `azure_blob_container_name`, `azure_folder_path`
-
-**Limit:** 50 files maximum per upload.
-
-### Quick URL-to-S3
-
-When you already have a direct URL to a file — say, a Google Analytics export link — and just need to save it without opening a browser, use `download_to_s3`:
-
-<CodeGroup>
-```python Python
-import os
-import asyncio
-from skyvern import Skyvern
-
-async def main():
- client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
-
- # Create the workflow
- workflow = await client.create_workflow(
- json_definition={
- "title": "Save Report to S3",
- "workflow_definition": {
- "parameters": [],
- "blocks": [
- {
- "block_type": "download_to_s3",
- "label": "save_report",
- "url": "https://analytics.example.com/report.pdf"
- }
- ]
- }
- }
- )
- print(f"Workflow ID: {workflow.workflow_permanent_id}")
-
- # Run the workflow
- run = await client.run_workflow(workflow_id=workflow.workflow_permanent_id)
- print(f"Run ID: {run.run_id}")
-
- # Poll until complete
- while True:
- result = await client.get_run(run.run_id)
- if result.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
- break
- print(f"Status: {result.status}")
- await asyncio.sleep(5)
-
- print(f"Final status: {result.status}")
- print(f"Output: {result.output}")
-
-asyncio.run(main())
-```
-
-```typescript TypeScript
-import { SkyvernClient } from "@skyvern/client";
-
-async function main() {
- const client = new SkyvernClient({
- apiKey: process.env.SKYVERN_API_KEY,
- });
-
- // Create the workflow
- const workflow = await client.createWorkflow({
- body: {
- json_definition: {
- title: "Save Report to S3",
- workflow_definition: {
- parameters: [],
- blocks: [
- {
- block_type: "download_to_s3",
- label: "save_report",
- url: "https://analytics.example.com/report.pdf",
- },
- ],
- },
- },
- },
- });
- console.log(`Workflow ID: ${workflow.workflow_permanent_id}`);
-
- // Run the workflow
- const run = await client.runWorkflow({
- body: { workflow_id: workflow.workflow_permanent_id },
- });
- console.log(`Run ID: ${run.run_id}`);
-
- // Poll until complete
- while (true) {
- const result = await client.getRun(run.run_id);
- if (
- ["completed", "failed", "terminated", "timed_out", "canceled"].includes(
- result.status
- )
- ) {
- console.log(`Final status: ${result.status}`);
- console.log(`Output: ${JSON.stringify(result.output, null, 2)}`);
- break;
- }
- console.log(`Status: ${result.status}`);
- await new Promise((resolve) => setTimeout(resolve, 5000));
- }
-}
-
-main();
-```
-
-```bash cURL
-# Create the workflow
-WORKFLOW=$(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": "Save Report to S3",
- "workflow_definition": {
- "parameters": [],
- "blocks": [
- {
- "block_type": "download_to_s3",
- "label": "save_report",
- "url": "https://analytics.example.com/report.pdf"
- }
- ]
- }
- }
- }')
-
-WORKFLOW_ID=$(echo "$WORKFLOW" | jq -r '.workflow_permanent_id')
-echo "Workflow ID: $WORKFLOW_ID"
-
-# Run the workflow
-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')
-echo "Run ID: $RUN_ID"
-
-# Poll until complete
-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>
-
-| Parameter | Type | Use this to |
-|-----------|------|-------------|
-| `url` | string | Specify the file URL to download and save |
-
-This skips the browser entirely — it fetches the file directly and stores it in Skyvern's S3. Use it when you already have the URL and don't need Skyvern to navigate a page. **Limit:** 10 MB maximum file size.
-
----
-
-## Passing files between blocks
-
-Files flow through workflows in two ways: through `SKYVERN_DOWNLOAD_DIRECTORY` for downloaded files, and through output parameters for parsed data.
-
-### Using downloaded files
-
-Say you downloaded invoices from a vendor portal earlier in the workflow and now need to email them to your accounting team. Any file downloaded during the run sits in `SKYVERN_DOWNLOAD_DIRECTORY`, and you can attach the entire directory to an email:
-
-<CodeGroup>
-```python Python
-import os
-import asyncio
-from skyvern import Skyvern
-
-async def main():
- client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
-
- # Create the workflow
- workflow = await client.create_workflow(
- json_definition={
- "title": "Email Downloaded Invoices",
- "workflow_definition": {
- "parameters": [
- {
- "key": "smtp_host",
- "parameter_type": "aws_secret",
- "aws_key": "skyvern/smtp/host"
- },
- {
- "key": "smtp_port",
- "parameter_type": "aws_secret",
- "aws_key": "skyvern/smtp/port"
- },
- {
- "key": "smtp_username",
- "parameter_type": "aws_secret",
- "aws_key": "skyvern/smtp/username"
- },
- {
- "key": "smtp_password",
- "parameter_type": "aws_secret",
- "aws_key": "skyvern/smtp/password"
- }
- ],
- "blocks": [
- {
- "block_type": "send_email",
- "label": "email_documents",
- "sender": "[email protected]",
- "recipients": ["[email protected]"],
- "subject": "Monthly invoices attached",
- "body": "See attached invoices for this month.",
- "smtp_host_secret_parameter_key": "smtp_host",
- "smtp_port_secret_parameter_key": "smtp_port",
- "smtp_username_secret_parameter_key": "smtp_username",
- "smtp_password_secret_parameter_key": "smtp_password",
- "file_attachments": ["SKYVERN_DOWNLOAD_DIRECTORY"]
- }
- ]
- }
- }
- )
- print(f"Workflow ID: {workflow.workflow_permanent_id}")
-
- # Run the workflow (SMTP secrets are auto-resolved from AWS Secrets Manager)
- run = await client.run_workflow(workflow_id=workflow.workflow_permanent_id)
- print(f"Run ID: {run.run_id}")
-
- # Poll until complete
- while True:
- result = await client.get_run(run.run_id)
- if result.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
- break
- print(f"Status: {result.status}")
- await asyncio.sleep(5)
-
- print(f"Final status: {result.status}")
- print(f"Output: {result.output}")
-
-asyncio.run(main())
-```
-
-```typescript TypeScript
-import { SkyvernClient } from "@skyvern/client";
-
-async function main() {
- const client = new SkyvernClient({
- apiKey: process.env.SKYVERN_API_KEY,
- });
-
- // Create the workflow
- const workflow = await client.createWorkflow({
- body: {
- json_definition: {
- title: "Email Downloaded Invoices",
- workflow_definition: {
- parameters: [
- {
- key: "smtp_host",
- parameter_type: "aws_secret",
- aws_key: "skyvern/smtp/host",
- },
- {
- key: "smtp_port",
- parameter_type: "aws_secret",
- aws_key: "skyvern/smtp/port",
- },
- {
- key: "smtp_username",
- parameter_type: "aws_secret",
- aws_key: "skyvern/smtp/username",
- },
- {
- key: "smtp_password",
- parameter_type: "aws_secret",
- aws_key: "skyvern/smtp/password",
- },
- ],
- blocks: [
- {
- block_type: "send_email",
- label: "email_documents",
- sender: "[email protected]",
- recipients: ["[email protected]"],
- subject: "Monthly invoices attached",
- body: "See attached invoices for this month.",
- smtp_host_secret_parameter_key: "smtp_host",
- smtp_port_secret_parameter_key: "smtp_port",
- smtp_username_secret_parameter_key: "smtp_username",
- smtp_password_secret_parameter_key: "smtp_password",
- file_attachments: ["SKYVERN_DOWNLOAD_DIRECTORY"],
- },
- ],
- },
- },
- },
- });
- console.log(`Workflow ID: ${workflow.workflow_permanent_id}`);
-
- // Run the workflow (SMTP secrets are auto-resolved from AWS Secrets Manager)
- const run = await client.runWorkflow({
- body: { workflow_id: workflow.workflow_permanent_id },
- });
- console.log(`Run ID: ${run.run_id}`);
-
- // Poll until complete
- while (true) {
- const result = await client.getRun(run.run_id);
- if (
- ["completed", "failed", "terminated", "timed_out", "canceled"].includes(
- result.status
- )
- ) {
- console.log(`Final status: ${result.status}`);
- console.log(`Output: ${JSON.stringify(result.output, null, 2)}`);
- break;
- }
- console.log(`Status: ${result.status}`);
- await new Promise((resolve) => setTimeout(resolve, 5000));
- }
-}
-
-main();
-```
-
-```bash cURL
-# Create the workflow
-WORKFLOW=$(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": "Email Downloaded Invoices",
- "workflow_definition": {
- "parameters": [
- {
- "key": "smtp_host",
- "parameter_type": "aws_secret",
- "aws_key": "skyvern/smtp/host"
- },
- {
- "key": "smtp_port",
- "parameter_type": "aws_secret",
- "aws_key": "skyvern/smtp/port"
- },
- {
- "key": "smtp_username",
- "parameter_type": "aws_secret",
- "aws_key": "skyvern/smtp/username"
- },
- {
- "key": "smtp_password",
- "parameter_type": "aws_secret",
- "aws_key": "skyvern/smtp/password"
- }
- ],
- "blocks": [
- {
- "block_type": "send_email",
- "label": "email_documents",
- "sender": "[email protected]",
- "recipients": ["[email protected]"],
- "subject": "Monthly invoices attached",
- "body": "See attached invoices for this month.",
- "smtp_host_secret_parameter_key": "smtp_host",
- "smtp_port_secret_parameter_key": "smtp_port",
- "smtp_username_secret_parameter_key": "smtp_username",
- "smtp_password_secret_parameter_key": "smtp_password",
- "file_attachments": ["SKYVERN_DOWNLOAD_DIRECTORY"]
- }
- ]
- }
- }
- }')
-
-WORKFLOW_ID=$(echo "$WORKFLOW" | jq -r '.workflow_permanent_id')
-echo "Workflow ID: $WORKFLOW_ID"
-
-# Run the workflow (SMTP secrets are auto-resolved from AWS Secrets Manager)
-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')
-echo "Run ID: $RUN_ID"
-
-# Poll until complete
-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>
-
-`file_attachments: ["SKYVERN_DOWNLOAD_DIRECTORY"]` attaches every file downloaded during the run. The SMTP credentials use `aws_secret` parameters — these reference keys stored in AWS Secrets Manager so your credentials are never exposed in the workflow definition.
-
-### Using parsed data
-
-When you parse a file, the extracted data becomes available as `{{ label_output }}`. This is how you chain a parse step with a navigation step — for example, parsing a resume PDF and then using the candidate's info to fill a Lever job application:
-
-<CodeGroup>
-```python Python
-import os
-import asyncio
-from skyvern import Skyvern
-
-async def main():
- client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
-
- # Create the workflow
- workflow = await client.create_workflow(
- json_definition={
- "title": "Parse Resume and Apply",
- "workflow_definition": {
- "parameters": [
- {
- "key": "resume",
- "parameter_type": "workflow",
- "workflow_parameter_type": "file_url"
- },
- {
- "key": "job_url",
- "parameter_type": "workflow",
- "workflow_parameter_type": "string"
- }
- ],
- "blocks": [
- {
- "block_type": "file_url_parser",
- "label": "parse_resume",
- "file_url": "{{ resume }}",
- "file_type": "pdf"
- },
- {
- "block_type": "navigation",
- "label": "fill_application",
- "url": "{{ job_url }}",
- "navigation_goal": (
- "Fill out the application form using "
- "this candidate's information:\n\n"
- "{{ parse_resume_output }}"
- )
- }
- ]
- }
- }
- )
- print(f"Workflow ID: {workflow.workflow_permanent_id}")
-
- # Run the workflow with a resume and job URL
- run = await client.run_workflow(
- workflow_id=workflow.workflow_permanent_id,
- parameters={
- "resume": "https://writing.colostate.edu/guides/documents/resume/functionalsample.pdf",
- "job_url": "https://jobs.lever.co/company/position"
- }
- )
- print(f"Run ID: {run.run_id}")
-
- # Poll until complete
- while True:
- result = await client.get_run(run.run_id)
- if result.status in ["completed", "failed", "terminated", "timed_out", "canceled"]:
- break
- print(f"Status: {result.status}")
- await asyncio.sleep(5)
-
- print(f"Final status: {result.status}")
- print(f"Output: {result.output}")
-
-asyncio.run(main())
-```
-
-```typescript TypeScript
-import { SkyvernClient } from "@skyvern/client";
-
-async function main() {
- const client = new SkyvernClient({
- apiKey: process.env.SKYVERN_API_KEY,
- });
-
- // Create the workflow
- const workflow = await client.createWorkflow({
- body: {
- json_definition: {
- title: "Parse Resume and Apply",
- workflow_definition: {
- parameters: [
- {
- key: "resume",
- parameter_type: "workflow",
- workflow_parameter_type: "file_url",
- },
- {
- key: "job_url",
- parameter_type: "workflow",
- workflow_parameter_type: "string",
- },
- ],
- blocks: [
- {
- block_type: "file_url_parser",
- label: "parse_resume",
- file_url: "{{ resume }}",
- file_type: "pdf",
- },
- {
- block_type: "navigation",
- label: "fill_application",
- url: "{{ job_url }}",
- navigation_goal: [
- "Fill out the application form using this candidate's information:",
- "",
- "{{ parse_resume_output }}",
- ].join("\n"),
- },
- ],
- },
- },
- },
- });
- console.log(`Workflow ID: ${workflow.workflow_permanent_id}`);
-
- // Run the workflow with a resume and job URL
- const run = await client.runWorkflow({
- body: {
- workflow_id: workflow.workflow_permanent_id,
- parameters: {
- resume:
- "https://writing.colostate.edu/guides/documents/resume/functionalsample.pdf",
- job_url: "https://jobs.lever.co/company/position",
- },
- },
- });
- console.log(`Run ID: ${run.run_id}`);
-
- // Poll until complete
- while (true) {
- const result = await client.getRun(run.run_id);
- if (
- ["completed", "failed", "terminated", "timed_out", "canceled"].includes(
- result.status
- )
- ) {
- console.log(`Final status: ${result.status}`);
- console.log(`Output: ${JSON.stringify(result.output, null, 2)}`);
- break;
- }
- console.log(`Status: ${result.status}`);
- await new Promise((resolve) => setTimeout(resolve, 5000));
- }
-}
-
-main();
-```
-
-```bash cURL
-# Create the workflow
-WORKFLOW=$(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": "Parse Resume and Apply",
- "workflow_definition": {
- "parameters": [
- {
- "key": "resume",
- "parameter_type": "workflow",
- "workflow_parameter_type": "file_url"
- },
- {
- "key": "job_url",
- "parameter_type": "workflow",
- "workflow_parameter_type": "string"
- }
- ],
- "blocks": [
- {
- "block_type": "file_url_parser",
- "label": "parse_resume",
- "file_url": "{{ resume }}",
- "file_type": "pdf"
- },
- {
- "block_type": "navigation",
- "label": "fill_application",
- "url": "{{ job_url }}",
- "navigation_goal": "Fill out the application form using this candidate'\''s information:\n\n{{ parse_resume_output }}"
- }
- ]
- }
- }
- }')
-
-WORKFLOW_ID=$(echo "$WORKFLOW" | jq -r '.workflow_permanent_id')
-echo "Workflow ID: $WORKFLOW_ID"
-
-# Run the workflow with a resume and job URL
-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\",
- \"parameters\": {
- \"resume\": \"https://writing.colostate.edu/guides/documents/resume/functionalsample.pdf\",
- \"job_url\": \"https://jobs.lever.co/company/position\"
- }
- }")
-
-RUN_ID=$(echo "$RUN" | jq -r '.run_id')
-echo "Run ID: $RUN_ID"
-
-# Poll until complete
-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>
-
-The first block parses the resume and stores the result. The second block references `{{ parse_resume_output }}` in its `navigation_goal` — Skyvern replaces this with the full parsed data (name, email, work experience) and uses it to fill the form fields.
-
-### Accepting files as workflow inputs
-
-To accept a file when the workflow runs, define a parameter with `workflow_parameter_type: file_url`:
-
-<CodeGroup>
-```python Python
-workflow = await client.create_workflow(
- json_definition={
- "title": "Resume Parser",
- "workflow_definition": {
- "parameters": [
- {
- "key": "resume",
- "parameter_type": "workflow",
- "workflow_parameter_type": "file_url",
- "description": "URL to the applicant's resume"
- }
- ],
- "blocks": [...]
- }
- }
-)
-```
-
-```typescript TypeScript
-const workflow = await client.createWorkflow({
- body: {
- json_definition: {
- title: "Resume Parser",
- workflow_definition: {
- parameters: [
- {
- key: "resume",
- parameter_type: "workflow",
- workflow_parameter_type: "file_url",
- description: "URL to the applicant's resume",
- },
- ],
- blocks: [...],
- },
- },
- },
-});
-```
-
-```bash cURL
-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": "Resume Parser",
- "workflow_definition": {
- "parameters": [
- {
- "key": "resume",
- "parameter_type": "workflow",
- "workflow_parameter_type": "file_url",
- "description": "URL to the applicant'\''s resume"
- }
- ],
- "blocks": [...]
- }
- }
- }'
-```
-</CodeGroup>
-
-When running the workflow, pass any accessible URL: public links, S3 presigned URLs, or files in your own storage.
-
----
-
-## Next steps
-
-<CardGroup cols={2}>
- <Card
- title="Workflow Blocks Reference"
- icon="cube"
- href="/multi-step-automations/workflow-blocks-reference"
- >
- Complete parameter reference for all file blocks
- </Card>
- <Card
- title="Build a Workflow"
- icon="hammer"
- href="/multi-step-automations/build-a-workflow"
- >
- Learn how blocks pass data to each other
- </Card>
-</CardGroup>
diff --git a/docs/multi-step-automations/scheduling-workflows.mdx b/docs/multi-step-automations/scheduling-workflows.mdx
deleted file mode 100644
index cbe87dbf6..000000000
--- a/docs/multi-step-automations/scheduling-workflows.mdx
+++ /dev/null
@@ -1,442 +0,0 @@
----
-title: Scheduling Workflows
-subtitle: Run workflows automatically on a recurring cron schedule
-description: Schedule Skyvern workflows to run automatically using cron expressions. Create, list, update, pause, resume, and delete recurring workflow schedules via the API.
-slug: multi-step-automations/scheduling-workflows
-keywords:
- - schedule
- - cron expression
- - recurring
- - timezone
- - enable
- - disable
- - pause
- - resume
- - delete schedule
----
-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.
-
-Scheduled runs appear in your run history with `trigger_type: "scheduled"` so you can distinguish them from manual or API-triggered runs.
-
----
-
-## How schedules work
-
-A schedule links a **cron expression** and a **timezone** to a workflow. At each scheduled time, Skyvern creates a new workflow run with the parameters you configured when creating the schedule.
-
-```mermaid
-flowchart LR
- A["Cron trigger<br/>e.g. 0 9 * * 1"] --> B["Skyvern creates<br/>workflow run"]
- B --> C["Workflow executes<br/>with saved parameters"]
- C --> D["Results in<br/>Run History"]
-```
-
-Each scheduled run is identical to a manually triggered run — same blocks, same parameters, same outputs. The only difference is the `trigger_type` field, which is set to `"scheduled"` instead of `"manual"` or `"api"`.
-
----
-
-## Cron expression format
-
-Schedules use standard 5-field cron expressions:
-
-```
-┌───────── minute (0-59)
-│ ┌─────── hour (0-23)
-│ │ ┌───── day of month (1-31)
-│ │ │ ┌─── month (1-12)
-│ │ │ │ ┌─ day of week (0-6, Sun=0)
-│ │ │ │ │
-* * * * *
-```
-
-**Common patterns:**
-
-| Cron expression | Description |
-|----------------|-------------|
-| `0 9 * * 1-5` | Every weekday at 9:00 AM |
-| `0 */6 * * *` | Every 6 hours |
-| `0 9 * * 1` | Every Monday at 9:00 AM |
-| `0 0 1 * *` | First day of every month at midnight |
-| `*/30 * * * *` | Every 30 minutes |
-| `0 8,17 * * *` | Twice daily at 8:00 AM and 5:00 PM |
-
-<Warning>
-The minimum interval is **5 minutes**. Cron expressions that resolve to intervals shorter than 5 minutes return a validation error:
-
-```json
-{
- "detail": "Cron interval must be at least 5 minutes"
-}
-```
-
-Invalid cron syntax returns `"Invalid cron expression"`.
-</Warning>
-
-### Timezone handling
-
-Schedules use [IANA timezone identifiers](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) (e.g., `America/New_York`, `Europe/London`, `Asia/Tokyo`). If you don't specify a timezone, it defaults to **UTC**.
-
----
-
-## Create a schedule
-
-Send a `POST` request to `/api/v1/workflows/{workflow_permanent_id}/schedules` with your cron expression and timezone.
-
-<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>
-
-<Info>
-All Python examples on this page assume you've initialized the client as shown above:
-
-```python
-client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
-```
-</Info>
-
-### Request body
-
-| 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` |
-
-### Example response
-
-```json
-{
- "schedule": {
- "workflow_schedule_id": "wfs_510037469402471882",
- "organization_id": "o_510009610576515030",
- "workflow_permanent_id": "wpid_510013188284271440",
- "cron_expression": "0 9 * * 1-5",
- "timezone": "America/New_York",
- "enabled": true,
- "parameters": null,
- "temporal_schedule_id": "wf-sched-wfs_510037469402471882",
- "name": "Weekday morning report",
- "description": "Runs the data extraction workflow every weekday at 9 AM ET",
- "created_at": "2026-03-25T10:45:52.193974",
- "modified_at": "2026-03-25T10:45:52.221999",
- "deleted_at": null
- },
- "next_runs": [
- "2026-03-25T13:00:00Z",
- "2026-03-26T13:00:00Z",
- "2026-03-27T13:00:00Z",
- "2026-03-30T13:00:00Z",
- "2026-03-31T13:00:00Z"
- ]
-}
-```
-
-**Response fields:**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `schedule.workflow_schedule_id` | string | Unique identifier for this schedule (prefixed `wfs_`) |
-| `schedule.organization_id` | string | The organization that owns this schedule |
-| `schedule.workflow_permanent_id` | string | The workflow this schedule triggers |
-| `schedule.cron_expression` | string | The cron expression defining the recurrence |
-| `schedule.timezone` | string | IANA timezone for the cron expression |
-| `schedule.enabled` | boolean | Whether the schedule is active (`true`) or paused (`false`). Defaults to `true` on creation |
-| `schedule.parameters` | object \| null | Workflow parameters passed to each run |
-| `schedule.temporal_schedule_id` | string | Internal identifier used by the scheduling engine |
-| `schedule.name` | string \| null | Human-readable name |
-| `schedule.description` | string \| null | Description of the schedule |
-| `schedule.created_at` | string | When the schedule was created |
-| `schedule.modified_at` | string | When the schedule was last updated |
-| `schedule.deleted_at` | string \| null | When the schedule was deleted, if applicable |
-| `next_runs` | array | Upcoming execution times in UTC based on the cron expression and timezone |
-
-Workflow runs triggered by this schedule will include `trigger_type: "scheduled"` and `workflow_schedule_id` pointing back to the schedule, so you can distinguish them from manual or API-triggered runs.
-
----
-
-## List schedules
-
-To list all schedules in your organization:
-
-<CodeGroup>
-```python Python
-result = await client.agent.list_organization_schedules()
-
-for schedule in result.schedules:
- status = "active" if schedule.enabled else "paused"
- print(f"{schedule.workflow_schedule_id}: {schedule.name} ({status})")
-```
-
-```bash cURL
-curl -X GET "https://api.skyvern.com/api/v1/schedules" \
- -H "x-api-key: $SKYVERN_API_KEY"
-```
-</CodeGroup>
-
-### Example response
-
-```json
-{
- "schedules": [
- {
- "workflow_schedule_id": "wfs_510037469402471882",
- "organization_id": "o_510009610576515030",
- "workflow_permanent_id": "wpid_510013188284271440",
- "workflow_title": "New Workflow",
- "cron_expression": "0 9 * * 1-5",
- "timezone": "America/New_York",
- "enabled": true,
- "parameters": null,
- "name": "Weekday morning report",
- "description": "Runs the data extraction workflow every weekday at 9 AM ET",
- "next_run": "2026-03-25T13:00:00Z",
- "created_at": "2026-03-25T10:45:52.193974",
- "modified_at": "2026-03-25T10:45:52.221999"
- }
- ],
- "total_count": 1,
- "page": 1,
- "page_size": 10
-}
-```
-
-**Response fields:**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `schedules` | array | List of schedule objects |
-| `schedules[].workflow_schedule_id` | string | Schedule identifier |
-| `schedules[].workflow_permanent_id` | string | The workflow this schedule triggers |
-| `schedules[].workflow_title` | string | Title of the associated workflow |
-| `schedules[].enabled` | boolean | Whether the schedule is active |
-| `schedules[].next_run` | string | Next scheduled execution time in UTC |
-| `total_count` | integer | Total number of schedules matching the query |
-| `page` | integer | Current page number |
-| `page_size` | integer | Number of results per page |
-
-To list schedules for a specific workflow:
-
-<CodeGroup>
-```python Python
-result = await client.agent.list_workflow_schedules(
- workflow_permanent_id="wpid_123456789"
-)
-```
-
-```bash cURL
-curl -X GET "https://api.skyvern.com/api/v1/workflows/wpid_123456789/schedules" \
- -H "x-api-key: $SKYVERN_API_KEY"
-```
-</CodeGroup>
-
----
-
-## Get schedule details
-
-Retrieve a single schedule, including upcoming run times in `next_runs`.
-
-<CodeGroup>
-```python Python
-result = await client.agent.get_workflow_schedule(
- workflow_permanent_id="wpid_123456789",
- workflow_schedule_id="wfs_abc123"
-)
-
-print(f"Next runs: {result.next_runs}")
-```
-
-```bash cURL
-curl -X GET "https://api.skyvern.com/api/v1/workflows/wpid_123456789/schedules/wfs_abc123" \
- -H "x-api-key: $SKYVERN_API_KEY"
-```
-</CodeGroup>
-
-The response has the same shape as the [create response](#example-response) — a `schedule` object with a `next_runs` array.
-
----
-
-## Update a schedule
-
-Change the cron expression, timezone, name, description, or parameters.
-
-<CodeGroup>
-```python Python
-result = await client.agent.update_workflow_schedule(
- workflow_permanent_id="wpid_123456789",
- workflow_schedule_id="wfs_abc123",
- cron_expression="0 8 * * 1-5",
- timezone="America/Chicago",
- name="Updated morning report",
- description="Updated description"
-)
-```
-
-```bash cURL
-curl -X PUT "https://api.skyvern.com/api/v1/workflows/wpid_123456789/schedules/wfs_abc123" \
- -H "x-api-key: $SKYVERN_API_KEY" \
- -H "Content-Type: application/json" \
- -d '{
- "cron_expression": "0 8 * * 1-5",
- "timezone": "America/Chicago",
- "name": "Updated morning report",
- "description": "Updated description"
- }'
-```
-</CodeGroup>
-
-<Warning>
-Updates **replace** all fields — any optional field you omit (like `description` or `parameters`) will be set to `null`. Re-send all fields you want to keep.
-</Warning>
-
-The response has the same shape as the [create response](#example-response).
-
----
-
-## Enable and disable a schedule
-
-You can pause a schedule by disabling it. Compared to deleting a schedule, this keeps its configuration saved to be re-enabled at any time.
-
-<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>
-
-Both endpoints return the same shape as the [create response](#example-response), with `enabled` set to `false` or `true`.
-
----
-
-## 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>
-
-### Example response
-
-```json
-{
- "ok": true
-}
-```
-
----
-
-## Limits
-
-| | Self-hosted (OSS) | Skyvern Cloud |
-|---|---|---|
-| **Schedules per workflow** | Unlimited | Configurable per plan |
-| **Total schedules per org** | Unlimited | Configurable per plan |
-| **Minimum interval** | 5 minutes | 5 minutes |
-
----
-
-## What's next
-
-<CardGroup cols={2}>
- <Card
- title="Cloud UI: Scheduling"
- icon="calendar"
- href="/cloud/building-workflows/scheduling"
- >
- Create and manage schedules from the Skyvern dashboard
- </Card>
- <Card
- title="Cost Control"
- icon="gauge"
- href="/optimization/cost-control"
- >
- Set step limits and optimize scheduled workflow costs
- </Card>
- <Card
- title="Webhooks"
- icon="bell"
- href="/going-to-production/webhooks"
- >
- Get notified when scheduled runs complete
- </Card>
- <Card
- title="Run History"
- icon="clock-rotate-left"
- href="/cloud/viewing-results/run-history"
- >
- View and filter scheduled run results
- </Card>
-</CardGroup>
diff --git a/docs/multi-step-automations/workflow-blocks-reference.mdx b/docs/multi-step-automations/workflow-blocks-reference.mdx
deleted file mode 100644
index caf35b120..000000000
--- a/docs/multi-step-automations/workflow-blocks-reference.mdx
+++ /dev/null
@@ -1,1209 +0,0 @@
----
-title: Workflow Blocks Reference
-subtitle: Complete reference for all workflow block types
-description: Complete reference for all Skyvern workflow block types including navigation, action, extraction, login, validation, conditional, for loop, file download, text prompt, code, HTTP request, and more.
-slug: multi-step-automations/workflow-blocks-reference
-keywords:
- - navigation block
- - action block
- - extract block
- - loop block
- - code block
- - text prompt block
- - login block
- - validation block
- - conditional block
- - HTTP request block
- - file download block
- - file upload block
- - send email block
----
-
-This page covers all block types available for building workflows.
-
-Blocks are defined in the `workflow_definition.blocks` array. Use JSON when passing a `json_definition` or YAML when passing a `yaml_definition` — both formats are shown for every block below.
-
----
-
-## Quick reference
-
-| Block Type | Use this to |
-|------------|---------|
-| [`navigation`](#navigation) | Navigate websites and take actions with a goal |
-| [`action`](#action) | Take a single action on the current page |
-| [`extraction`](#extraction) | Extract structured data from a page |
-| [`login`](#login) | Authenticate using stored credentials |
-| [`task`](#task) | Legacy block combining navigation and extraction |
-| [`task_v2`](#task-v2) | Simplified task block using natural language prompts |
-| [`validation`](#validation) | Assert conditions and control workflow flow |
-| [`conditional`](#conditional) | Branch workflow based on conditions |
-| [`for_loop`](#for-loop) | Iterate over arrays and repeat nested blocks |
-| [`goto_url`](#goto-url) | Navigate directly to a URL |
-| [`file_download`](#file-download) | Download files from websites |
-| [`file_url_parser`](#file-parser) | Parse CSV, Excel, or PDF files |
-| [`pdf_parser`](#pdf-parser) | Parse PDF files specifically (deprecated, use `file_url_parser`) |
-| [`download_to_s3`](#download-to-s3) | Download a file from URL to S3 |
-| [`upload_to_s3`](#upload-to-s3) | Upload workflow files to S3 |
-| [`file_upload`](#file-upload) | Upload files to S3 or Azure storage |
-| [`http_request`](#http-request) | Make HTTP API calls |
-| [`send_email`](#send-email) | Send emails with attachments |
-| [`code`](#code) | Execute custom Python code |
-| [`text_prompt`](#text-prompt) | Make LLM calls for text generation |
-| [`print_page`](#print-page) | Save current page as PDF |
-| [`wait`](#wait) | Pause execution for a duration |
-| [`human_interaction`](#human-interaction) | Pause for human approval via email |
-
----
-
-## Common parameters
-
-These parameters are available on all block types:
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `label` | string | — | **Required.** Unique identifier for this block within the workflow. Used for referencing outputs as `{{label_output}}`. |
-| `continue_on_failure` | boolean | `false` | If `true`, workflow continues even if this block fails. |
-| `next_loop_on_failure` | boolean | `false` | If `true` and inside a loop, skips to next iteration on failure. |
-| `next_block_label` | string | — | Label of the next block to execute. If omitted, uses sequential order. |
-| `model` | object | — | Override model configuration for this block. |
-
-### Finally block
-
-You can designate any block as a "finally" block that always executes when the workflow ends — whether it completed, failed, terminated, or timed out. The only exception is explicit cancellation.
-
-Set `finally_block_label` at the workflow definition level (alongside `parameters` and `blocks`):
-
-```yaml
-workflow_definition:
- parameters: [...]
- blocks:
- - block_type: navigation
- label: main_task
- # ...
- - block_type: send_email
- label: notify_team
- # ...
- finally_block_label: notify_team
-```
-
-The referenced block must be a terminal block — it cannot have a `next_block_label`.
-
----
-
-### Error code mapping
-
-Several blocks accept an `error_code_mapping` parameter. This is an object mapping custom error codes to natural language descriptions. Skyvern evaluates each description against the current page state and surfaces matching errors in the block output.
-
-```json
-{
- "error_code_mapping": {
- "INVALID_CREDENTIALS": "The page shows an error message indicating the username or password is incorrect.",
- "ACCOUNT_LOCKED": "The page indicates the account has been locked or suspended.",
- "CAPTCHA_REQUIRED": "A CAPTCHA challenge is displayed that cannot be solved."
- }
-}
-```
-
-### Block outputs
-
-Every block produces an output accessible by other blocks as `{{label_output}}`, where `label` is the block's `label` value. The output shape depends on the block type:
-
-- **Navigation / Action / Login / File Download**: the output is `null` on success (the primary effect is the browser state change).
-- **Extraction**: the output matches the `data_schema` you provide (or a free-form object if no schema is given).
-- **Task**: `null` when only `navigation_goal` is set. When `data_extraction_goal` is set, the output matches the `data_schema`.
-- **Code**: the value of the `result` variable at the end of execution.
-- **Text Prompt**: the LLM response, structured according to `json_schema` if provided.
-- **File Parser / PDF Parser**: the parsed file content (structured if `json_schema` is provided).
-- **For Loop**: an array of outputs, one per iteration.
-- **HTTP Request**: the response body (as JSON if applicable, otherwise as a string).
-- **Upload to S3 / File Upload / Download to S3**: the storage URL of the uploaded/downloaded file.
-- **Print Page**: the file path of the saved PDF.
-- **Validation / Conditional / Goto URL / Wait / Send Email / Human Interaction**: `null` (control-flow blocks).
-
----
-
-## Navigation
-
-Navigate through websites to take actions with a natural language goal.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "navigation",
- "label": "search_registry",
- "url": "https://asha.org/verify",
- "navigation_goal": "Search for the person using the provided information. COMPLETE when search results are displayed. TERMINATE if no results found.",
- "parameter_keys": ["first_name", "last_name", "employee_state"],
- "engine": "skyvern-2.0",
- "max_steps_per_run": 20
-}
-```
-
-```yaml YAML
-- block_type: navigation
- label: search_registry
- url: "https://asha.org/verify"
- navigation_goal: |
- Search for the person using:
- - First name: {{first_name}}
- - Last name: {{last_name}}
- - State: {{employee_state}}
-
- COMPLETE when search results are displayed.
- TERMINATE if no results found.
- parameter_keys:
- - first_name
- - last_name
- - employee_state
- engine: skyvern-2.0
- max_steps_per_run: 20
-```
-</CodeGroup>
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `navigation_goal` | string | — | **Required.** Natural language description of what to do. Include when to COMPLETE or TERMINATE. |
-| `url` | string | — | Starting URL. If omitted, continues from previous block's page. |
-| `title` | string | `""` | Display title for this block. |
-| `engine` | string | `"skyvern-1.0"` | `"skyvern-1.0"` or `"skyvern-2.0"`. |
-| `max_steps_per_run` | integer | — | Maximum steps this block can take. |
-| `max_retries` | integer | `0` | Number of retry attempts on failure. |
-| `parameter_keys` | array | — | Parameters this block can access. |
-| `error_code_mapping` | object | — | Map conditions to custom error codes. |
-| `complete_on_download` | boolean | `false` | Complete when a file download is triggered. |
-| `download_suffix` | string | — | Filename for the downloaded file. |
-| `complete_criterion` | string | — | Natural language condition for completion. |
-| `terminate_criterion` | string | — | Natural language condition for termination. |
-| `complete_verification` | boolean | `true` | Whether to verify completion criteria. |
-| `include_action_history_in_verification` | boolean | `false` | Include action history when verifying completion. |
-| `totp_identifier` | string | — | TOTP credential identifier for 2FA. |
-| `totp_verification_url` | string | — | URL to fetch TOTP codes. |
-| `disable_cache` | boolean | `false` | Disable caching for this block. |
-
-<Info>
-For guidance on which engine to choose (`skyvern-1.0` vs `skyvern-2.0`), see [Engine Selection](/running-automations/task-parameters#engine).
-</Info>
-
----
-
-## Action
-
-Take a single action on the current page without navigation.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "action",
- "label": "click_download_button",
- "navigation_goal": "Click the \"Download PDF\" button",
- "engine": "skyvern-1.0"
-}
-```
-
-```yaml YAML
-- block_type: action
- label: click_download_button
- navigation_goal: Click the "Download PDF" button
- engine: skyvern-1.0
-```
-</CodeGroup>
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `navigation_goal` | string | — | Description of the action to take. |
-| `url` | string | — | URL to navigate to first. |
-| `title` | string | `""` | Display title for this block. |
-| `engine` | string | `"skyvern-1.0"` | AI engine to use (`"skyvern-1.0"` or `"skyvern-2.0"`). |
-| `max_retries` | integer | `0` | Number of retry attempts. |
-| `parameter_keys` | array | — | Parameters this block can access. |
-| `error_code_mapping` | object | — | Map conditions to custom error codes. |
-| `complete_on_download` | boolean | `false` | Complete when download triggered. |
-| `download_suffix` | string | — | Filename for the downloaded file. |
-| `totp_identifier` | string | — | TOTP credential identifier. |
-| `totp_verification_url` | string | — | URL to fetch TOTP codes. |
-| `disable_cache` | boolean | `false` | Disable caching for this block. |
-
----
-
-## Extraction
-
-Extract structured data from a page without taking any actions.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "extraction",
- "label": "extract_credentials",
- "data_extraction_goal": "Extract the professional credentials including ASHA account number, certification status, and valid through date.",
- "data_schema": {
- "type": "object",
- "properties": {
- "asha_account_number": { "type": "string" },
- "certification_status": { "type": "string" },
- "valid_through": { "type": "string" }
- }
- }
-}
-```
-
-```yaml YAML
-- block_type: extraction
- label: extract_credentials
- data_extraction_goal: |
- Extract the professional credentials:
- - ASHA account number
- - Certification status (active/inactive)
- - Valid through date
- - Supervisor/mentor information
- data_schema:
- type: object
- properties:
- asha_account_number:
- type: string
- certification_status:
- type: string
- enum: ["active", "inactive", "expired"]
- valid_through:
- type: string
-```
-</CodeGroup>
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `data_extraction_goal` | string | — | **Required.** What data to extract. |
-| `url` | string | — | URL to extract from. If omitted, uses current page. |
-| `title` | string | `""` | Display title for this block. |
-| `data_schema` | object/array/string | — | JSON Schema for the output structure. |
-| `engine` | string | `"skyvern-1.0"` | AI engine to use (`"skyvern-1.0"` or `"skyvern-2.0"`). |
-| `max_retries` | integer | `0` | Retry attempts. |
-| `max_steps_per_run` | integer | — | Maximum steps allowed. |
-| `parameter_keys` | array | — | Parameters this block can access. |
-| `disable_cache` | boolean | `false` | Disable caching for this block. |
-
----
-
-## Login
-
-Authenticate to a website using stored credentials.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "login",
- "label": "login_to_portal",
- "url": "{{website_url}}",
- "parameter_keys": ["credentials"],
- "navigation_goal": "Log in using the provided credentials. Handle any cookie consent or promotional popups first. COMPLETE when on the logged-in dashboard."
-}
-```
-
-```yaml YAML
-- block_type: login
- label: login_to_portal
- url: "{{website_url}}"
- parameter_keys:
- - credentials
- navigation_goal: |
- Log in using the provided credentials.
- Handle any cookie consent or promotional popups first.
- COMPLETE when on the logged-in dashboard.
- TERMINATE if login fails after 3 attempts.
-```
-</CodeGroup>
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `url` | string | — | Login page URL. |
-| `navigation_goal` | string | — | Additional instructions for complex login flows. |
-| `title` | string | `""` | Display title for this block. |
-| `engine` | string | `"skyvern-1.0"` | AI engine to use (`"skyvern-1.0"` or `"skyvern-2.0"`). |
-| `parameter_keys` | array | — | Parameters including credential reference. |
-| `error_code_mapping` | object | — | Map conditions to custom error codes. |
-| `max_retries` | integer | `0` | Retry attempts. |
-| `max_steps_per_run` | integer | — | Maximum steps allowed. |
-| `complete_criterion` | string | — | Condition for completion. |
-| `terminate_criterion` | string | — | Condition for termination. |
-| `complete_verification` | boolean | `true` | Verify completion criteria. |
-| `totp_identifier` | string | — | TOTP credential identifier for 2FA. |
-| `totp_verification_url` | string | — | URL to fetch TOTP codes. |
-| `disable_cache` | boolean | `false` | Disable caching for this block. |
-
----
-
-## Task
-
-Legacy block combining navigation and extraction. For new workflows, prefer separate Navigation and Extraction blocks.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "task",
- "label": "login_and_extract",
- "url": "{{website_url}}",
- "parameter_keys": ["credentials"],
- "navigation_goal": "Log in using the provided credentials. Navigate to the account settings page. COMPLETE when on the settings page.",
- "data_extraction_goal": "Extract the account ID and subscription plan.",
- "data_schema": {
- "type": "object",
- "properties": {
- "account_id": { "type": "string" },
- "subscription_plan": { "type": "string" }
- }
- }
-}
-```
-
-```yaml YAML
-- block_type: task
- label: login_and_extract
- url: "{{website_url}}"
- parameter_keys:
- - credentials
- navigation_goal: |
- Log in using the provided credentials.
- Navigate to the account settings page.
- COMPLETE when on the settings page.
- data_extraction_goal: |
- Extract the account ID and subscription plan.
- data_schema:
- type: object
- properties:
- account_id:
- type: string
- subscription_plan:
- type: string
-```
-</CodeGroup>
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `url` | string | — | Starting URL. |
-| `navigation_goal` | string | — | What to do on the page. |
-| `data_extraction_goal` | string | — | What data to extract. |
-| `data_schema` | object/array/string | — | Schema for extracted data. |
-| `title` | string | `""` | Display title for this block. |
-| `engine` | string | `"skyvern-1.0"` | AI engine to use (`"skyvern-1.0"` or `"skyvern-2.0"`). |
-| `parameter_keys` | array | — | Available parameters. |
-| `error_code_mapping` | object | — | Custom error codes. |
-| `max_steps_per_run` | integer | — | Maximum steps. |
-| `max_retries` | integer | `0` | Retry attempts. |
-| `complete_on_download` | boolean | `false` | Complete when download triggered. |
-| `download_suffix` | string | — | Filename for the downloaded file. |
-| `complete_criterion` | string | — | Condition for completion. |
-| `terminate_criterion` | string | — | Condition for termination. |
-| `complete_verification` | boolean | `true` | Verify completion criteria. |
-| `include_action_history_in_verification` | boolean | `false` | Include action history in verification. |
-| `totp_identifier` | string | — | TOTP credential identifier. |
-| `totp_verification_url` | string | — | URL to fetch TOTP codes. |
-| `disable_cache` | boolean | `false` | Disable caching. |
-
----
-
-## Task V2
-
-Simplified task block using natural language prompts. Uses computer-use agents for more flexible automation.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "task_v2",
- "label": "complete_form",
- "url": "https://example.com/form",
- "prompt": "Fill out the contact form with the provided information and submit it. Wait for the confirmation message.",
- "max_iterations": 10,
- "max_steps": 25
-}
-```
-
-```yaml YAML
-- block_type: task_v2
- label: complete_form
- url: "https://example.com/form"
- prompt: |
- Fill out the contact form with the provided information and submit it.
- Wait for the confirmation message.
- max_iterations: 10
- max_steps: 25
-```
-</CodeGroup>
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `prompt` | string | — | **Required.** Natural language description of the task. |
-| `url` | string | — | Starting URL. |
-| `max_iterations` | integer | `10` | Maximum number of iterations. |
-| `max_steps` | integer | `25` | Maximum steps per iteration. |
-| `totp_identifier` | string | — | TOTP credential identifier. |
-| `totp_verification_url` | string | — | URL to fetch TOTP codes. |
-| `disable_cache` | boolean | `false` | Disable caching. |
-
-<Info>
-`task_v2` does not use `parameter_keys`. All workflow parameters and previous block outputs are automatically available as Jinja2 template variables in `prompt` and `url`. For example: `"Fill the form with name {{first_name}} and email {{email}}"`.
-</Info>
-
----
-
-## Validation
-
-Assert conditions using the LLM to control workflow flow.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "validation",
- "label": "check_credential_status",
- "parameter_keys": ["extract_credentials_output"],
- "complete_criterion": "Continue if the certification_status is 'expired' or 'inactive', or if the valid_through date has changed.",
- "terminate_criterion": "Terminate if the certification_status is 'active' and valid_through matches current_credential_expiry."
-}
-```
-
-```yaml YAML
-- block_type: validation
- label: check_credential_status
- parameter_keys:
- - extract_credentials_output
- complete_criterion: |
- Continue if ANY of these are true:
- - certification_status is "expired"
- - certification_status is "inactive"
- - valid_through date has changed
- terminate_criterion: |
- Terminate (no email needed) if ALL of these are true:
- - certification_status is "active"
- - valid_through matches current_credential_expiry
-```
-</CodeGroup>
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `complete_criterion` | string | — | Condition that must be true to continue. |
-| `terminate_criterion` | string | — | Condition that terminates the workflow. |
-| `parameter_keys` | array | — | Parameters to evaluate. |
-| `error_code_mapping` | object | — | Map conditions to custom error codes. |
-| `disable_cache` | boolean | `false` | Disable caching. |
-
----
-
-## Conditional
-
-Branch workflow execution based on conditions. Supports Jinja2 templates or LLM-based evaluation.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "conditional",
- "label": "check_status",
- "branch_conditions": [
- {
- "criteria": {
- "criteria_type": "jinja2_template",
- "expression": "{{ status == 'approved' }}"
- },
- "next_block_label": "process_approved",
- "description": "Route to approval processing"
- },
- {
- "criteria": {
- "criteria_type": "jinja2_template",
- "expression": "{{ status == 'rejected' }}"
- },
- "next_block_label": "handle_rejection"
- },
- {
- "is_default": true,
- "next_block_label": "handle_pending"
- }
- ]
-}
-```
-
-```yaml YAML
-- block_type: conditional
- label: check_status
- branch_conditions:
- - criteria:
- criteria_type: jinja2_template
- expression: "{{ status == 'approved' }}"
- next_block_label: process_approved
- description: Route to approval processing
- - criteria:
- criteria_type: prompt
- expression: "Is the application status indicating rejection?"
- next_block_label: handle_rejection
- - is_default: true
- next_block_label: handle_pending
-```
-</CodeGroup>
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `branch_conditions` | array | — | **Required.** List of conditions and their target blocks. |
-
-**Branch Condition properties:**
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `criteria` | object | — | The condition to evaluate. |
-| `criteria.criteria_type` | string | `"jinja2_template"` | `"jinja2_template"` or `"prompt"`. |
-| `criteria.expression` | string | — | **Required.** Jinja2 expression or natural language prompt. |
-| `criteria.description` | string | — | Description of the criteria. |
-| `next_block_label` | string | — | Block to execute if condition is true. |
-| `description` | string | — | Description of this branch. |
-| `is_default` | boolean | `false` | If true, this branch is used when no other conditions match. |
-
----
-
-## For Loop
-
-Iterate over an array and execute nested blocks for each item.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "for_loop",
- "label": "apply_to_jobs",
- "loop_over_parameter_key": "job_urls",
- "continue_on_failure": true,
- "loop_blocks": [
- {
- "block_type": "navigation",
- "label": "submit_application",
- "url": "{{submit_application.current_value}}",
- "navigation_goal": "Fill out and submit the job application."
- }
- ]
-}
-```
-
-```yaml YAML
-- block_type: for_loop
- label: apply_to_jobs
- loop_over_parameter_key: job_urls
- continue_on_failure: true
- loop_blocks:
- - block_type: navigation
- label: submit_application
- url: "{{submit_application.current_value}}"
- navigation_goal: |
- Fill out the job application form using:
- - Resume data: {{parsed_resume_output}}
- - Additional info: {{additional_information}}
-
- COMPLETE when application is submitted.
-```
-</CodeGroup>
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `loop_blocks` | array | — | **Required.** Blocks to execute for each iteration. |
-| `loop_over_parameter_key` | string | `""` | Parameter containing the array to iterate. |
-| `loop_variable_reference` | string | — | Custom name for the loop variable. |
-| `complete_if_empty` | boolean | `false` | If `true`, completes successfully when array is empty. |
-
-<Info>
-**Accessing the current item inside a loop**
-
-Use `{{nested_block_label.current_value}}` to reference the current iteration value, where `nested_block_label` is the `label` of the block **inside** `loop_blocks` — not the label of the `for_loop` itself.
-
-In the example above, the loop label is `apply_to_jobs` and the nested block label is `submit_application`, so the current URL is accessed as `{{submit_application.current_value}}`.
-</Info>
-
-The output of a `for_loop` block is an array containing the result from each iteration.
-
----
-
-## Goto URL
-
-Navigate directly to a URL without any AI processing.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "goto_url",
- "label": "go_to_dashboard",
- "url": "https://app.example.com/dashboard"
-}
-```
-
-```yaml YAML
-- block_type: goto_url
- label: go_to_dashboard
- url: "https://app.example.com/dashboard"
-```
-</CodeGroup>
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `url` | string | — | **Required.** URL to navigate to. |
-
----
-
-## File Download
-
-Navigate to download a file from a website.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "file_download",
- "label": "download_ein_letter",
- "url": "https://irs.gov/ein/confirm",
- "navigation_goal": "Find and download the EIN confirmation letter PDF. Look for a \"Download\" or \"Print\" button. COMPLETE when download is triggered.",
- "download_suffix": "ein_confirmation.pdf"
-}
-```
-
-```yaml YAML
-- block_type: file_download
- label: download_ein_letter
- url: "https://irs.gov/ein/confirm"
- navigation_goal: |
- Find and download the EIN confirmation letter PDF.
- Look for a "Download" or "Print" button.
- COMPLETE when download is triggered.
- download_suffix: ein_confirmation.pdf
-```
-</CodeGroup>
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `navigation_goal` | string | — | **Required.** How to find and download the file. |
-| `url` | string | — | Starting URL. |
-| `title` | string | `""` | Display title for this block. |
-| `engine` | string | `"skyvern-1.0"` | AI engine to use (`"skyvern-1.0"` or `"skyvern-2.0"`). |
-| `download_suffix` | string | — | Filename for the downloaded file. |
-| `download_timeout` | number | — | Timeout in seconds for download. |
-| `parameter_keys` | array | — | Parameters this block can access. |
-| `error_code_mapping` | object | — | Map conditions to custom error codes. |
-| `max_retries` | integer | `0` | Retry attempts. |
-| `max_steps_per_run` | integer | — | Maximum steps. |
-| `totp_identifier` | string | — | TOTP credential identifier. |
-| `totp_verification_url` | string | — | URL to fetch TOTP codes. |
-| `disable_cache` | boolean | `false` | Disable caching. |
-
-Downloaded files are stored in `SKYVERN_DOWNLOAD_DIRECTORY`—use this path in `upload_to_s3`, `file_upload`, or `send_email`'s `file_attachments` to access them.
-
----
-
-## File Parser
-
-Download and parse a file from a URL. Supports CSV, Excel, and PDF files.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "file_url_parser",
- "label": "parse_order_csv",
- "file_url": "{{order_file_url}}",
- "file_type": "csv"
-}
-```
-
-```yaml YAML
-- block_type: file_url_parser
- label: parse_order_csv
- file_url: "{{order_file_url}}"
- file_type: csv
-```
-</CodeGroup>
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `file_url` | string | — | **Required.** URL of the file to parse. |
-| `file_type` | string | — | **Required.** One of: `csv`, `excel`, `pdf`. |
-| `json_schema` | object | — | Schema for structured extraction. |
-
----
-
-## PDF Parser
-
-<Warning>
-Deprecated. Use [File Parser](#file-parser) with `file_type: "pdf"` instead. This block will be removed in a future version.
-</Warning>
-
-Parse a PDF file specifically for text extraction.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "pdf_parser",
- "label": "parse_resume",
- "file_url": "{{resume}}"
-}
-```
-
-```yaml YAML
-- block_type: pdf_parser
- label: parse_resume
- file_url: "{{resume}}"
-```
-</CodeGroup>
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `file_url` | string | — | **Required.** URL of the PDF file. |
-| `json_schema` | object | — | Schema for structured extraction from PDF. |
-
----
-
-## Download to S3
-
-Download a file from a URL directly to S3 storage.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "download_to_s3",
- "label": "save_report",
- "url": "https://example.com/report.pdf"
-}
-```
-
-```yaml YAML
-- block_type: download_to_s3
- label: save_report
- url: "https://example.com/report.pdf"
-```
-</CodeGroup>
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `url` | string | — | **Required.** URL of the file to download. |
-
----
-
-## Upload to S3
-
-Upload files from the workflow to S3 storage.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "upload_to_s3",
- "label": "upload_results",
- "path": "{{download_report_output}}"
-}
-```
-
-```yaml YAML
-- block_type: upload_to_s3
- label: upload_results
- path: "{{download_report_output}}"
-```
-</CodeGroup>
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `path` | string | — | Path to the file to upload. |
-
----
-
-## File Upload
-
-Upload downloaded files to AWS S3 or Azure Blob storage.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "file_upload",
- "label": "upload_to_s3",
- "storage_type": "s3",
- "aws_access_key_id": "{{aws_access_key}}",
- "aws_secret_access_key": "{{aws_secret_key}}",
- "s3_bucket": "company-invoices",
- "region_name": "us-west-2",
- "path": "SKYVERN_DOWNLOAD_DIRECTORY"
-}
-```
-
-```yaml YAML
-- block_type: file_upload
- label: upload_to_s3
- storage_type: s3
- aws_access_key_id: "{{aws_access_key}}"
- aws_secret_access_key: "{{aws_secret_key}}"
- s3_bucket: "company-invoices"
- region_name: us-west-2
- path: SKYVERN_DOWNLOAD_DIRECTORY
-```
-</CodeGroup>
-
-**S3 Parameters:**
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `storage_type` | string | — | Set to `"s3"` for AWS S3. |
-| `aws_access_key_id` | string | — | AWS access key. |
-| `aws_secret_access_key` | string | — | AWS secret key. |
-| `s3_bucket` | string | — | Target S3 bucket name. |
-| `region_name` | string | — | AWS region. |
-| `path` | string | — | Path to the file to upload. |
-
-**Azure Parameters:**
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `storage_type` | string | — | Set to `"azure"` for Azure Blob Storage. |
-| `azure_storage_account_name` | string | — | Azure storage account name. |
-| `azure_storage_account_key` | string | — | Azure storage account key. |
-| `azure_blob_container_name` | string | — | Azure blob container name. |
-| `azure_folder_path` | string | — | Folder path within the container. |
-| `path` | string | — | Path to the file to upload. |
-
----
-
-## HTTP Request
-
-Make HTTP API calls to external services.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "http_request",
- "label": "post_to_webhook",
- "method": "POST",
- "url": "https://api.example.com/webhook",
- "headers": {
- "Authorization": "Bearer {{api_token}}",
- "Content-Type": "application/json"
- },
- "body": {
- "data": "{{extracted_data}}"
- },
- "timeout": 30
-}
-```
-
-```yaml YAML
-- block_type: http_request
- label: post_to_webhook
- method: POST
- url: "https://api.example.com/webhook"
- headers:
- Authorization: "Bearer {{api_token}}"
- Content-Type: application/json
- body:
- data: "{{extracted_data}}"
- timeout: 30
-```
-</CodeGroup>
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `url` | string | — | URL to make the request to. |
-| `method` | string | `"GET"` | HTTP method: GET, POST, PUT, DELETE, etc. |
-| `headers` | object | — | HTTP headers as key-value pairs. |
-| `body` | object | — | Request body (for POST, PUT, etc.). |
-| `files` | object | — | Files to upload as multipart form data. |
-| `timeout` | integer | `30` | Request timeout in seconds. |
-| `follow_redirects` | boolean | `true` | Whether to follow HTTP redirects. |
-| `download_filename` | string | — | Filename for downloaded response. |
-| `save_response_as_file` | boolean | `false` | Save response body as a file. |
-| `parameter_keys` | array | — | Parameters this block can access. |
-
----
-
-## Send Email
-
-Send an email with optional attachments.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "send_email",
- "label": "send_confirmation",
- "smtp_host_secret_parameter_key": "smtp_host",
- "smtp_port_secret_parameter_key": "smtp_port",
- "smtp_username_secret_parameter_key": "smtp_username",
- "smtp_password_secret_parameter_key": "smtp_password",
- "sender": "[email protected]",
- "recipients": ["{{recipient_email}}", "[email protected]"],
- "subject": "EIN Registration Complete - {{company_name}}",
- "body": "Your EIN registration has been completed. See attached for details.",
- "file_attachments": ["SKYVERN_DOWNLOAD_DIRECTORY"]
-}
-```
-
-```yaml YAML
-- block_type: send_email
- label: send_confirmation
- smtp_host_secret_parameter_key: smtp_host
- smtp_port_secret_parameter_key: smtp_port
- smtp_username_secret_parameter_key: smtp_username
- smtp_password_secret_parameter_key: smtp_password
- recipients:
- - "{{recipient_email}}"
- subject: "EIN Registration Complete - {{company_name}}"
- body: |
- Your EIN registration has been completed.
- EIN: {{extract_ein_output.ein_number}}
- file_attachments:
- - SKYVERN_DOWNLOAD_DIRECTORY
-```
-</CodeGroup>
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `smtp_host_secret_parameter_key` | string | — | **Required.** Parameter key for SMTP host. |
-| `smtp_port_secret_parameter_key` | string | — | **Required.** Parameter key for SMTP port. |
-| `smtp_username_secret_parameter_key` | string | — | **Required.** Parameter key for SMTP username. |
-| `smtp_password_secret_parameter_key` | string | — | **Required.** Parameter key for SMTP password. |
-| `sender` | string | — | **Required.** Sender email address. |
-| `recipients` | array | — | **Required.** List of recipient email addresses. |
-| `subject` | string | — | **Required.** Email subject line. |
-| `body` | string | — | **Required.** Email body content. |
-| `file_attachments` | array | — | Files to attach. Use `SKYVERN_DOWNLOAD_DIRECTORY` for downloaded files. |
-
----
-
-## Code
-
-Execute custom Python code for data transformation or browser control.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "code",
- "label": "calculate_price_diff",
- "parameter_keys": ["alibaba_price", "amazon_price"],
- "code": "if amazon_price and alibaba_price:\n result = {'difference': alibaba_price - amazon_price}\nelse:\n result = None"
-}
-```
-
-```yaml YAML
-- block_type: code
- label: calculate_price_diff
- parameter_keys:
- - alibaba_price
- - amazon_price
- code: |
- if amazon_price and alibaba_price:
- result = {
- "difference": alibaba_price - amazon_price,
- "percentage": ((alibaba_price - amazon_price) / amazon_price) * 100
- }
- else:
- result = None
-```
-</CodeGroup>
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `code` | string | — | **Required.** Python code to execute. Store result in `result` variable. |
-| `parameter_keys` | array | — | Parameters available to the code. |
-
-Available objects: `skyvern_page` (Playwright page object for browser control).
-
-<Note>
-Code Block with browser control is invite-only on Skyvern Cloud. Contact [email protected] for access.
-</Note>
-
----
-
-## Text Prompt
-
-Make an LLM call for text generation or analysis.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "text_prompt",
- "label": "summarize_credentials",
- "llm_key": "OPENAI_GPT4O",
- "parameter_keys": ["extract_credentials_output"],
- "prompt": "Analyze these professional credentials and provide a summary including current status, any concerns, and recommended actions: {{extract_credentials_output}}",
- "json_schema": {
- "type": "object",
- "properties": {
- "status_summary": { "type": "string" },
- "concerns": { "type": "array", "items": { "type": "string" } }
- }
- }
-}
-```
-
-```yaml YAML
-- block_type: text_prompt
- label: summarize_credentials
- llm_key: OPENAI_GPT4O
- parameter_keys:
- - extract_credentials_output
- prompt: |
- Analyze these professional credentials and provide a summary:
- {{extract_credentials_output}}
-
- Include: Current status, any concerns, recommended actions
- json_schema:
- type: object
- properties:
- status_summary:
- type: string
- concerns:
- type: array
- items:
- type: string
-```
-</CodeGroup>
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `prompt` | string | — | **Required.** The prompt to send to the LLM. |
-| `parameter_keys` | array | — | Parameters available in the prompt. |
-| `llm_key` | string | — | Model to use (e.g., `OPENAI_GPT4O`). |
-| `json_schema` | object | — | Schema for structured output. |
-
----
-
-## Print Page
-
-Save the current browser page as a PDF file.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "print_page",
- "label": "save_receipt",
- "custom_filename": "receipt_{{order_id}}",
- "format": "Letter",
- "landscape": false,
- "print_background": true
-}
-```
-
-```yaml YAML
-- block_type: print_page
- label: save_receipt
- custom_filename: "receipt_{{order_id}}"
- format: Letter
- landscape: false
- print_background: true
-```
-</CodeGroup>
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `custom_filename` | string | — | Custom filename for the PDF. |
-| `format` | string | `"A4"` | Page format: `A4`, `Letter`, `Legal`, or `Tabloid`. |
-| `landscape` | boolean | `false` | Print in landscape orientation. |
-| `print_background` | boolean | `true` | Include background colors and images. |
-| `include_timestamp` | boolean | `true` | Include timestamp in filename. |
-| `parameter_keys` | array | — | Parameters this block can access. |
-
-<Note>
-The `print_page` block works via the REST API and TypeScript SDK, but the Python SDK's generated types do not yet include it. If you use the Python SDK, pass the block definition through `json_definition` or `yaml_definition` — the API will accept it.
-</Note>
-
----
-
-## Wait
-
-Pause workflow execution for a specified duration.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "wait",
- "label": "wait_for_processing",
- "wait_sec": 30
-}
-```
-
-```yaml YAML
-- block_type: wait
- label: wait_for_processing
- wait_sec: 30
-```
-</CodeGroup>
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `wait_sec` | integer | `0` | Seconds to wait. |
-
----
-
-## Human Interaction
-
-Pause the workflow and send an email requesting human approval before continuing.
-
-<CodeGroup>
-```json JSON
-{
- "block_type": "human_interaction",
- "label": "request_approval",
- "instructions": "Please review the extracted data and approve or reject to continue.",
- "positive_descriptor": "Approve",
- "negative_descriptor": "Reject",
- "timeout_seconds": 7200,
- "sender": "[email protected]",
- "recipients": ["[email protected]"],
- "subject": "Approval Required - Order Processing",
- "body": "An order requires your approval before processing can continue."
-}
-```
-
-```yaml YAML
-- block_type: human_interaction
- label: request_approval
- instructions: Please review the extracted data and approve or reject to continue.
- positive_descriptor: Approve
- negative_descriptor: Reject
- timeout_seconds: 7200
- recipients:
- subject: "Approval Required - Order Processing"
- body: |
- An order requires your approval before processing can continue.
-
- Order details: {{order_details}}
-```
-</CodeGroup>
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `timeout_seconds` | integer | — | **Required.** How long to wait for a response (in seconds). |
-| `sender` | string | — | **Required.** Email address to send from. |
-| `recipients` | array | — | **Required.** List of email addresses to notify. |
-| `subject` | string | — | **Required.** Email subject line. |
-| `body` | string | — | **Required.** Email body content. |
-| `instructions` | string | `"Please review and approve or reject to continue the workflow."` | Instructions shown in the approval interface. |
-| `positive_descriptor` | string | `"Approve"` | Label for the approval button. |
-| `negative_descriptor` | string | `"Reject"` | Label for the rejection button. |
-
----
-
-## Next steps
-
-<CardGroup cols={2}>
- <Card
- title="Build a Workflow"
- icon="hammer"
- href="/multi-step-automations/build-a-workflow"
- >
- Create and run your first workflow
- </Card>
- <Card
- title="Workflow Parameters"
- icon="sliders"
- href="/multi-step-automations/workflow-parameters"
- >
- Pass data between blocks with parameters
- </Card>
- <Card
- title="File Operations"
- icon="file"
- href="/multi-step-automations/file-operations"
- >
- Parse, download, and upload files
- </Card>
- <Card
- title="Webhooks"
- icon="bell"
- href="/going-to-production/webhooks"
- >
- Get notified when workflows complete
- </Card>
-</CardGroup>
diff --git a/docs/multi-step-automations/workflow-parameters.mdx b/docs/multi-step-automations/workflow-parameters.mdx
deleted file mode 100644
index 931cad7a4..000000000
--- a/docs/multi-step-automations/workflow-parameters.mdx
+++ /dev/null
@@ -1,832 +0,0 @@
----
-title: Workflow Parameters
-subtitle: Configure how your workflow runs
-description: Full reference for all workflow creation and run parameters including title, definition, proxy location, webhooks, browser sessions, browser profiles, and credential parameters.
-slug: multi-step-automations/workflow-parameters
-keywords:
- - workflow_id
- - parameters
- - proxy_location
- - webhook_url
- - browser_session_id
- - browser_profile_id
- - max_steps_override
- - template
- - title
----
-
-This page covers all parameters you can pass when creating and running workflows.
-
----
-
-## Quick reference: Creating a workflow
-
-| Parameter | Type | Use this to |
-|-----------|------|-------------|
-| [`title`](#title) **(Required)** | string | Name the workflow for identification |
-| [`workflow_definition`](#workflow_definition) **(Required)** | object | Define blocks, parameters, and logic |
-| [`description`](#description) | string | Document what the workflow does |
-| [`proxy_location`](#proxy_location-create) | string or object | Set default proxy for all blocks |
-| [`webhook_callback_url`](#webhook_callback_url) | string | Get notified when any run of this workflow completes |
-| [`persist_browser_session`](#persist_browser_session) | boolean | Keep the browser session alive across blocks |
-
----
-
-## Quick reference: Running a workflow
-
-| Parameter | Type | Use this to |
-|-----------|------|-------------|
-| [`workflow_id`](#workflow_id) **(Required)** | string | Specify which workflow to run |
-| [`parameters`](#parameters) | object | Pass values for workflow input parameters |
-| [`title`](#title-run) | string | Name this specific workflow run |
-| [`proxy_location`](#proxy_location-run) | string or object | Override the default proxy location |
-| [`webhook_url`](#webhook_url) | string | Get notified when the workflow completes |
-| [`browser_session_id`](#browser_session_id) | string | Reuse a persistent browser session |
-| [`browser_profile_id`](#browser_profile_id) | string | Reuse a browser profile (cookies, storage) |
-
----
-
-## Creating a workflow
-
-<Info>
-All create parameters (`title`, `workflow_definition`, `description`, `proxy_location`, etc.) are nested inside a **`json_definition`** object — not passed at the top level. You can alternatively use `yaml_definition` (a YAML string) instead.
-</Info>
-
-<CodeGroup>
-```python Python
-workflow = await client.create_workflow(
- json_definition={
- "title": "...",
- "workflow_definition": {...}
- }
-)
-```
-
-```typescript TypeScript
-const workflow = await client.createWorkflow({
- body: {
- json_definition: {
- title: "...",
- workflow_definition: {...},
- },
- },
-});
-```
-
-```bash cURL
-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": "...",
- "workflow_definition": {...}
- }
- }'
-```
-</CodeGroup>
-
-### `title`
-
-**Required.** Display name for the workflow. This field goes inside the `json_definition` object.
-
-<CodeGroup>
-```python Python
-workflow = await client.create_workflow(
- json_definition={
- "title": "Invoice Downloader",
- "workflow_definition": {...}
- }
-)
-```
-
-```typescript TypeScript
-const workflow = await client.createWorkflow({
- body: {
- json_definition: {
- title: "Invoice Downloader",
- workflow_definition: {...},
- },
- },
-});
-```
-
-```bash cURL
-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",
- "workflow_definition": {...}
- }
- }'
-```
-</CodeGroup>
-
----
-
-### `workflow_definition`
-
-**Required.** The workflow structure containing parameters and blocks.
-
-```json
-{
- "workflow_definition": {
- "parameters": [...],
- "blocks": [...]
- }
-}
-```
-
-#### `parameters`
-
-Input parameters the workflow accepts. Each parameter has:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `key` | string | Parameter name, used to reference via `{{ key }}` |
-| `parameter_type` | string | Always `"workflow"` for input parameters |
-| `workflow_parameter_type` | string | Data type: `string`, `integer`, `float`, `boolean`, `json`, `file_url`, `credential_id` |
-| `default_value` | any | Optional default value |
-| `description` | string | Optional description |
-
-<CodeGroup>
-```python Python
-workflow = await client.create_workflow(
- json_definition={
- "title": "Job Application Workflow",
- "workflow_definition": {
- "parameters": [
- {
- "key": "resume",
- "parameter_type": "workflow",
- "workflow_parameter_type": "file_url",
- "description": "URL to the resume PDF"
- },
- {
- "key": "job_urls",
- "parameter_type": "workflow",
- "workflow_parameter_type": "json",
- "default_value": []
- },
- {
- "key": "cover_letter",
- "parameter_type": "workflow",
- "workflow_parameter_type": "string",
- "default_value": ""
- }
- ],
- "blocks": [...]
- }
- }
-)
-```
-
-```typescript TypeScript
-const workflow = await client.createWorkflow({
- body: {
- json_definition: {
- title: "Job Application Workflow",
- workflow_definition: {
- parameters: [
- {
- key: "resume",
- parameter_type: "workflow",
- workflow_parameter_type: "file_url",
- description: "URL to the resume PDF",
- },
- {
- key: "job_urls",
- parameter_type: "workflow",
- workflow_parameter_type: "json",
- default_value: [],
- },
- {
- key: "cover_letter",
- parameter_type: "workflow",
- workflow_parameter_type: "string",
- default_value: "",
- },
- ],
- blocks: [...],
- },
- },
- },
-});
-```
-
-```bash cURL
-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": "Job Application Workflow",
- "workflow_definition": {
- "parameters": [
- {
- "key": "resume",
- "parameter_type": "workflow",
- "workflow_parameter_type": "file_url",
- "description": "URL to the resume PDF"
- },
- {
- "key": "job_urls",
- "parameter_type": "workflow",
- "workflow_parameter_type": "json",
- "default_value": []
- },
- {
- "key": "cover_letter",
- "parameter_type": "workflow",
- "workflow_parameter_type": "string",
- "default_value": ""
- }
- ],
- "blocks": [...]
- }
- }
- }'
-```
-</CodeGroup>
-
-**Parameter types:**
-
-| Type | Description | Example |
-|------|-------------|---------|
-| `string` | Text value | `"John Smith"` |
-| `integer` | Whole number | `42` |
-| `float` | Decimal number | `99.99` |
-| `boolean` | True/false | `true` |
-| `json` | JSON object or array | `{"key": "value"}` or `["a", "b"]` |
-| `file_url` | URL to a file | `"https://example.com/resume.pdf"` |
-| `credential_id` | Reference to a stored credential | `"cred_abc123"` |
-
-#### `blocks`
-
-Array of blocks that execute in sequence. See [Workflow Blocks Reference](/multi-step-automations/workflow-blocks-reference) for all block types.
-
----
-
-### `description`
-
-Optional description of what the workflow does.
-
-<CodeGroup>
-```python Python
-workflow = await client.create_workflow(
- json_definition={
- "title": "Invoice Downloader",
- "description": "Downloads all invoices from the vendor portal since a given date",
- "workflow_definition": {...}
- }
-)
-```
-
-```typescript TypeScript
-const workflow = await client.createWorkflow({
- body: {
- json_definition: {
- title: "Invoice Downloader",
- description: "Downloads all invoices from the vendor portal since a given date",
- workflow_definition: {...},
- },
- },
-});
-```
-
-```bash cURL
-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",
- "description": "Downloads all invoices from the vendor portal since a given date",
- "workflow_definition": {...}
- }
- }'
-```
-</CodeGroup>
-
----
-
-### `proxy_location` (create)
-
-Default proxy location for all blocks in the workflow. Individual blocks can override this.
-
-See [Proxy & Geo Targeting](/going-to-production/proxy-geolocation) for all available locations.
-
-<CodeGroup>
-```python Python
-workflow = await client.create_workflow(
- json_definition={
- "title": "UK Price Checker",
- "proxy_location": "RESIDENTIAL_GB",
- "workflow_definition": {...}
- }
-)
-```
-
-```typescript TypeScript
-const workflow = await client.createWorkflow({
- body: {
- json_definition: {
- title: "UK Price Checker",
- proxy_location: "RESIDENTIAL_GB",
- workflow_definition: {...},
- },
- },
-});
-```
-
-```bash cURL
-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": "UK Price Checker",
- "proxy_location": "RESIDENTIAL_GB",
- "workflow_definition": {...}
- }
- }'
-```
-</CodeGroup>
-
----
-
-### `webhook_callback_url`
-
-URL to receive a POST request whenever any run of this workflow completes. This is set at the workflow level and applies to all runs. To set a webhook for a single run instead, use [`webhook_url`](#webhook_url) when running the workflow.
-
-<CodeGroup>
-```python Python
-workflow = await client.create_workflow(
- json_definition={
- "title": "Invoice Downloader",
- "webhook_callback_url": "https://your-server.com/webhook",
- "workflow_definition": {...}
- }
-)
-```
-
-```typescript TypeScript
-const workflow = await client.createWorkflow({
- body: {
- json_definition: {
- title: "Invoice Downloader",
- webhook_callback_url: "https://your-server.com/webhook",
- workflow_definition: {...},
- },
- },
-});
-```
-
-```bash cURL
-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": {...}
- }
- }'
-```
-</CodeGroup>
-
----
-
-### `persist_browser_session`
-
-If `true`, the browser session is kept alive across all blocks in the workflow. This means blocks share the same browser context including cookies, local storage, and login state.
-
-Defaults to `false`.
-
-<CodeGroup>
-```python Python
-workflow = await client.create_workflow(
- json_definition={
- "title": "Multi-Step Portal Scraper",
- "persist_browser_session": True,
- "workflow_definition": {...}
- }
-)
-```
-
-```typescript TypeScript
-const workflow = await client.createWorkflow({
- body: {
- json_definition: {
- title: "Multi-Step Portal Scraper",
- persist_browser_session: true,
- workflow_definition: {...},
- },
- },
-});
-```
-
-```bash cURL
-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": "Multi-Step Portal Scraper",
- "persist_browser_session": true,
- "workflow_definition": {...}
- }
- }'
-```
-</CodeGroup>
-
-<Info>
-Additional advanced parameters are available when creating a workflow, including `totp_verification_url`, `totp_identifier`, `model`, and `extra_http_headers`. See the [API Reference](/api-reference) for the full list.
-</Info>
-
----
-
-## Running a workflow
-
-### `workflow_id`
-
-**Required.** The ID of the workflow to run. This is the `workflow_permanent_id` returned when creating the workflow.
-
-<CodeGroup>
-```python Python
-run = await client.run_workflow(
- workflow_id="wpid_123456789",
- parameters={...}
-)
-```
-
-```typescript TypeScript
-const run = await client.runWorkflow({
- body: {
- workflow_id: "wpid_123456789",
- parameters: {...},
- },
-});
-```
-
-```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": {...}
- }'
-```
-</CodeGroup>
-
----
-
-### `parameters`
-
-Values for the workflow's input parameters. Keys must match the `key` field in the workflow's parameter definitions.
-
-<CodeGroup>
-```python Python
-run = await client.run_workflow(
- workflow_id="wpid_123456789",
- parameters={
- "resume": "https://example.com/resume.pdf",
- "job_urls": [
- "https://jobs.lever.co/company/position-1",
- "https://jobs.lever.co/company/position-2"
- ],
- "cover_letter": "I am excited to apply for this position..."
- }
-)
-```
-
-```typescript TypeScript
-const run = await client.runWorkflow({
- body: {
- workflow_id: "wpid_123456789",
- parameters: {
- resume: "https://example.com/resume.pdf",
- job_urls: [
- "https://jobs.lever.co/company/position-1",
- "https://jobs.lever.co/company/position-2",
- ],
- cover_letter: "I am excited to apply for this position...",
- },
- },
-});
-```
-
-```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_urls": [
- "https://jobs.lever.co/company/position-1",
- "https://jobs.lever.co/company/position-2"
- ],
- "cover_letter": "I am excited to apply for this position..."
- }
- }'
-```
-</CodeGroup>
-
-Parameters with `default_value` in the workflow definition are optional. Parameters without defaults are required.
-
----
-
-### `proxy_location` (run)
-
-Override the workflow's default proxy location for this run.
-
-<CodeGroup>
-```python Python
-run = await client.run_workflow(
- workflow_id="wpid_123456789",
- parameters={...},
- proxy_location="RESIDENTIAL_CA"
-)
-```
-
-```typescript TypeScript
-const run = await client.runWorkflow({
- body: {
- workflow_id: "wpid_123456789",
- parameters: {...},
- proxy_location: "RESIDENTIAL_CA",
- },
-});
-```
-
-```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": {...},
- "proxy_location": "RESIDENTIAL_CA"
- }'
-```
-</CodeGroup>
-
-**Proxy locations:**
-
-| Value | Location |
-|-------|----------|
-| `RESIDENTIAL` | United States **(default)** |
-| `RESIDENTIAL_ISP` | United States (static ISP IPs) |
-| `RESIDENTIAL_AR` | Argentina |
-| `RESIDENTIAL_AU` | Australia |
-| `RESIDENTIAL_BR` | Brazil |
-| `RESIDENTIAL_CA` | Canada |
-| `RESIDENTIAL_DE` | Germany |
-| `RESIDENTIAL_ES` | Spain |
-| `RESIDENTIAL_FR` | France |
-| `RESIDENTIAL_GB` | United Kingdom |
-| `RESIDENTIAL_IE` | Ireland |
-| `RESIDENTIAL_IN` | India |
-| `RESIDENTIAL_IT` | Italy |
-| `RESIDENTIAL_JP` | Japan |
-| `RESIDENTIAL_MX` | Mexico |
-| `RESIDENTIAL_NL` | Netherlands |
-| `RESIDENTIAL_NZ` | New Zealand |
-| `RESIDENTIAL_PH` | Philippines |
-| `RESIDENTIAL_KR` | South Korea |
-| `RESIDENTIAL_SA` | Saudi Arabia |
-| `RESIDENTIAL_TR` | Türkiye |
-| `RESIDENTIAL_ZA` | South Africa |
-| `NONE` | No proxy |
-
-For US state or city-level targeting, pass a `GeoTarget` object instead:
-
-```json
-{
- "proxy_location": {
- "country": "US",
- "subdivision": "CA",
- "city": "San Francisco"
- }
-}
-```
-
-`country` is required (ISO 3166-1 alpha-2 code). `subdivision` and `city` are optional.
-
-See [Proxy & Geo Targeting](/going-to-production/proxy-geolocation) for more details.
-
----
-
-### `webhook_url`
-
-URL to receive a POST request when the workflow completes.
-
-<CodeGroup>
-```python Python
-run = await client.run_workflow(
- workflow_id="wpid_123456789",
- parameters={...},
- webhook_url="https://your-server.com/webhook"
-)
-```
-
-```typescript TypeScript
-const run = await client.runWorkflow({
- body: {
- workflow_id: "wpid_123456789",
- parameters: {...},
- 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": {...},
- "webhook_url": "https://your-server.com/webhook"
- }'
-```
-</CodeGroup>
-
-The webhook payload contains the same data as the polling response. See [Webhooks](/going-to-production/webhooks) for authentication and retry options.
-
----
-
-### `title` (run)
-
-Optional display name for this specific workflow run. Useful for distinguishing runs in the UI and API responses.
-
-<CodeGroup>
-```python Python
-run = await client.run_workflow(
- workflow_id="wpid_123456789",
- title="January 2025 Invoice Batch",
- parameters={...}
-)
-```
-
-```typescript TypeScript
-const run = await client.runWorkflow({
- body: {
- workflow_id: "wpid_123456789",
- title: "January 2025 Invoice Batch",
- parameters: {...},
- },
-});
-```
-
-```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",
- "title": "January 2025 Invoice Batch",
- "parameters": {...}
- }'
-```
-</CodeGroup>
-
----
-
-### `browser_session_id`
-
-ID of an existing Skyvern browser session to reuse. The workflow run continues from the current screen state of that session. Browser session IDs start with `pbs_`.
-
-<CodeGroup>
-```python Python
-run = await client.run_workflow(
- workflow_id="wpid_123456789",
- browser_session_id="pbs_abc123",
- parameters={...}
-)
-```
-
-```typescript TypeScript
-const run = await client.runWorkflow({
- body: {
- workflow_id: "wpid_123456789",
- browser_session_id: "pbs_abc123",
- parameters: {...},
- },
-});
-```
-
-```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",
- "browser_session_id": "pbs_abc123",
- "parameters": {...}
- }'
-```
-</CodeGroup>
-
----
-
-### `browser_profile_id`
-
-ID of a browser profile to reuse. Browser profiles persist cookies, local storage, and other browser state across runs. Profile IDs start with `bp_`.
-
-<CodeGroup>
-```python Python
-run = await client.run_workflow(
- workflow_id="wpid_123456789",
- browser_profile_id="bp_xyz789",
- parameters={...}
-)
-```
-
-```typescript TypeScript
-const run = await client.runWorkflow({
- body: {
- workflow_id: "wpid_123456789",
- browser_profile_id: "bp_xyz789",
- parameters: {...},
- },
-});
-```
-
-```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",
- "browser_profile_id": "bp_xyz789",
- "parameters": {...}
- }'
-```
-</CodeGroup>
-
-<Info>
-Additional advanced parameters are available when running a workflow, including `totp_url`, `totp_identifier`, `browser_address`, `extra_http_headers`, and `max_screenshot_scrolls`. See the [API Reference](/api-reference) for the full list.
-</Info>
-
----
-
-## Run response
-
-When you run a workflow, the response contains:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `run_id` | string | Unique ID for this run (starts with `wr_`). |
-| `status` | string | One of: `created`, `queued`, `running`, `completed`, `failed`, `terminated`, `timed_out`, `canceled`. |
-| `output` | object/array/string/null | Extracted data from the workflow, if any. |
-| `failure_reason` | string/null | Why the run failed, if applicable. |
-| `errors` | array/null | List of errors encountered during the run. |
-| `downloaded_files` | array/null | Files downloaded during the run. |
-| `recording_url` | string/null | URL to the browser recording. |
-| `screenshot_urls` | array/null | Latest screenshots in reverse chronological order. |
-| `app_url` | string/null | Link to view this run in the Skyvern UI. |
-| `created_at` | datetime | When the run was created. |
-| `started_at` | datetime/null | When execution started. |
-| `finished_at` | datetime/null | When execution finished. |
-
----
-
-## Next steps
-
-<CardGroup cols={2}>
- <Card
- title="Build a Workflow"
- icon="hammer"
- href="/multi-step-automations/build-a-workflow"
- >
- Create and run your first workflow
- </Card>
- <Card
- title="Workflow Blocks Reference"
- icon="cube"
- href="/multi-step-automations/workflow-blocks-reference"
- >
- Detailed documentation for all block types
- </Card>
- <Card
- title="Proxy & Geo Targeting"
- icon="globe"
- href="/going-to-production/proxy-geolocation"
- >
- Full list of proxy locations
- </Card>
- <Card
- title="Webhooks"
- icon="webhook"
- href="/going-to-production/webhooks"
- >
- Handle webhook authentication and retries
- </Card>
-</CardGroup>
diff --git a/docs/optimization/browser-tunneling.mdx b/docs/optimization/browser-tunneling.mdx
index 3614d159b..e13fae0f7 100644
--- a/docs/optimization/browser-tunneling.mdx
+++ b/docs/optimization/browser-tunneling.mdx
@@ -13,7 +13,7 @@ keywords:
- 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.
+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)
@@ -31,7 +31,7 @@ One command starts Chrome on your machine and creates a tunnel so Skyvern Cloud
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.
+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.
diff --git a/docs/optimization/cost-control.mdx b/docs/optimization/cost-control.mdx
index 06af504c4..4ad8d6708 100644
--- a/docs/optimization/cost-control.mdx
+++ b/docs/optimization/cost-control.mdx
@@ -125,7 +125,7 @@ If runs consistently time out, increase `max_steps` or simplify the task. If `st
## 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.
+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.
@@ -203,7 +203,7 @@ curl -X POST "https://api.skyvern.com/v1/run/tasks" \
</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](/multi-step-automations/scheduling-workflows).
+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>
---
diff --git a/docs/running-automations/task-parameters.mdx b/docs/running-automations/task-parameters.mdx
deleted file mode 100644
index 6c5a67a5b..000000000
--- a/docs/running-automations/task-parameters.mdx
+++ /dev/null
@@ -1,902 +0,0 @@
----
-title: Task Parameters
-subtitle: Configure how your task runs
-description: Full reference for all task parameters including prompt, URL, engine, data extraction schema, proxy location, browser sessions, TOTP, webhooks, and cost control options.
-slug: running-automations/task-parameters
-keywords:
- - prompt
- - url
- - engine
- - data_extraction_schema
- - max_steps
- - proxy_location
- - browser_session_id
- - totp_identifier
- - webhook_url
- - error_code_mapping
- - user_agent
----
-
-This page covers all parameters you can pass to `run_task`.
-
-Only `prompt` is a required parameter.
-
-
----
-
-## Quick reference
-
-| Parameter | Type | Use this to |
-|-----------|------|-------------|
-| [`prompt`](#prompt) **(Required)** | string | Give natural language instructions for the AI |
-| [`url`](#url) | string | Give a starting URL for the task |
-| [`engine`](#engine) | string | Choose a different Agent model |
-| [`data_extraction_schema`](#data_extraction_schema) | object | Get consistent, structured JSON output |
-| [`max_steps`](#max_steps) | integer | Limit how long the Agent runs and cap costs |
-| [`proxy_location`](#proxy_location) | string \| object | Access geo-restricted content or reduce bot detection |
-| [`browser_session_id`](#browser_session_id) | string | Maintain state (cookies, login) across multiple tasks |
-| [`totp_identifier`](#totp_identifier) | string | Handle 2FA when pushing codes to Skyvern |
-| [`totp_url`](#totp_url) | string | Have Skyvern fetch 2FA codes from your endpoint |
-| [`error_code_mapping`](#error_code_mapping) | object | Get custom error codes for programmatic handling |
-| [`webhook_url`](#webhook_url) | string | Get notified when the task completes |
-| [`title`](#title) | string | Label the task in the Skyvern UI |
-| [`extra_http_headers`](#extra_http_headers) | object | Add custom headers (e.g., Authorization) to browser requests |
-| [`publish_workflow`](#publish_workflow) | boolean | Convert this task into a reusable workflow |
-| [`max_screenshot_scrolls`](#max_screenshot_scrolls) | integer | Capture lazy-loaded content in screenshots |
-| [`browser_address`](#browser_address) | string | Connect to your own browser for local development |
-| [`include_action_history_in_verification`](#include_action_history_in_verification) | boolean | Improve verification accuracy for multi-step forms |
-| [`run_with`](#run_with) | string | Choose whether to run with the AI agent or generated code |
-| [`model`](#model) | object | Configure model settings (e.g., temperature) |
-
----
-
-## `prompt`
-
-**Required.** Natural language instructions describing what the AI should do.
-
-<CodeGroup>
-```python Python
-result = await client.run_task(
- prompt="Find the cheapest flight from NYC to LAX on March 15"
-)
-```
-
-```typescript TypeScript
-const result = await client.runTask({
- body: {
- prompt: "Find the cheapest flight from NYC to LAX on March 15",
- },
-});
-```
-
-```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": "Find the cheapest flight from NYC to LAX on March 15"
- }'
-```
-</CodeGroup>
-
-Be specific about your goal and what data you want extracted. The more detailed your prompt, the better the results.
-
----
-
-## `url`
-
-The starting page for the automation. Skyvern navigates from here based on your prompt.
-
-<CodeGroup>
-```python Python
-result = await client.run_task(
- prompt="Get the top headline",
- url="https://news.ycombinator.com"
-)
-```
-
-```typescript TypeScript
-const result = await client.runTask({
- body: {
- prompt: "Get the top headline",
- url: "https://news.ycombinator.com",
- },
-});
-```
-
-```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 headline",
- "url": "https://news.ycombinator.com"
- }'
-```
-</CodeGroup>
-
-If not provided, Skyvern attempts to determine an appropriate starting URL from your prompt.
-
----
-
-## `engine`
-
-The AI engine that powers the task. These are not iterations—they're suited for different purposes.
-
-| Engine | Description |
-|--------|-------------|
-| `skyvern-1.0` | **Default.** Single objective, precise, faster, cheaper. Best for simple tasks like form filling or single-page extraction. |
-| `skyvern-2.0` | Multi-objective, flexible, handles complex multi-step tasks. 85.85% on WebVoyager benchmark. Slower and more expensive. |
-| `openai-cua` | OpenAI's Computer Use Agent |
-| `anthropic-cua` | Anthropic Claude Sonnet with computer use |
-| `ui-tars` | UI-TARS model (Seed1.5-VL) via Doubao API |
-
-<Tip>
-The default engine `skyvern-1.0` works well for clear, single-goal tasks with faster, cheaper execution. Switch to `skyvern-2.0` when the task requires flexibility or multiple steps.
-</Tip>
-
-<CodeGroup>
-```python Python
-result = await client.run_task(
- prompt="Fill out the contact form",
- engine="skyvern-1.0"
-)
-```
-
-```typescript TypeScript
-const result = await client.runTask({
- body: {
- prompt: "Fill out the contact form",
- engine: "skyvern-1.0",
- },
-});
-```
-
-```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",
- "engine": "skyvern-1.0"
- }'
-```
-</CodeGroup>
-
----
-
-## `data_extraction_schema`
-
-A [JSON Schema](https://json-schema.org/) defining the structure of output data.
-
-Use this when you need consistent, typed responses.
-
-<CodeGroup>
-```python Python
-result = await client.run_task(
- prompt="Find the top post on Hacker News",
- data_extraction_schema={
- "type": "object",
- "properties": {
- "title": {
- "type": "string",
- "description": "The title of the top post"
- },
- "points": {
- "type": "integer",
- "description": "Number of points"
- }
- }
- }
-)
-```
-
-```typescript TypeScript
-const result = await client.runTask({
- body: {
- prompt: "Find the top post on Hacker News",
- data_extraction_schema: {
- type: "object",
- properties: {
- title: {
- type: "string",
- description: "The title of the top post",
- },
- points: {
- type: "integer",
- description: "Number of points",
- },
- },
- },
- },
-});
-```
-
-```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": "Find the top post on Hacker News",
- "data_extraction_schema": {
- "type": "object",
- "properties": {
- "title": {
- "type": "string",
- "description": "The title of the top post"
- },
- "points": {
- "type": "integer",
- "description": "Number of points"
- }
- }
- }
- }'
-```
-</CodeGroup>
-
-Without a schema, output format varies based on what the AI extracts. With a schema, output matches your defined structure.
-
----
-
-## `max_steps`
-
-Maximum number of steps the task can take. The task fails if it exceeds this limit.
-
-<CodeGroup>
-```python Python
-result = await client.run_task(
- prompt="Get the current stock price of AAPL",
- max_steps=10
-)
-```
-
-```typescript TypeScript
-const result = await client.runTask({
- body: {
- prompt: "Get the current stock price of AAPL",
- max_steps: 10,
- },
-});
-```
-
-```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 stock price of AAPL",
- "max_steps": 10
- }'
-```
-</CodeGroup>
-
-On the cloud-hosted version, you're billed per step. Set this to a reasonable value during development to cap costs.
-
-<Warning>
-Set `max_steps` during development to avoid runaway costs. A task that loops or gets stuck will keep consuming steps until it hits this limit.
-</Warning>
-
----
-
-## `proxy_location`
-
-Route browser traffic through a residential proxy in a specific location.
-
-Use this for geo-restricted content or to reduce bot detection.
-
-**Country-level pools:**
-
-| Value | Location |
-|-------|----------|
-| `RESIDENTIAL` | Random US residential (default) |
-| `RESIDENTIAL_GB` | United Kingdom |
-| `RESIDENTIAL_DE` | Germany |
-| `RESIDENTIAL_FR` | France |
-| `RESIDENTIAL_ES` | Spain |
-| `RESIDENTIAL_IE` | Ireland |
-| `RESIDENTIAL_IN` | India |
-| `RESIDENTIAL_JP` | Japan |
-| `RESIDENTIAL_AU` | Australia |
-| `RESIDENTIAL_CA` | Canada |
-| `RESIDENTIAL_BR` | Brazil |
-| `RESIDENTIAL_MX` | Mexico |
-| `RESIDENTIAL_AR` | Argentina |
-| `RESIDENTIAL_NZ` | New Zealand |
-| `RESIDENTIAL_ZA` | South Africa |
-| `RESIDENTIAL_IT` | Italy |
-| `RESIDENTIAL_NL` | Netherlands |
-| `RESIDENTIAL_PH` | Philippines |
-| `RESIDENTIAL_KR` | South Korea |
-| `RESIDENTIAL_SA` | Saudi Arabia |
-| `RESIDENTIAL_TR` | Turkey |
-| `RESIDENTIAL_ISP` | ISP proxy |
-| `US-CA` | California, US |
-| `US-NY` | New York, US |
-| `US-TX` | Texas, US |
-| `US-FL` | Florida, US |
-| `US-WA` | Washington, US |
-| `NONE` | No proxy |
-
-<CodeGroup>
-```python Python
-result = await client.run_task(
- prompt="Get UK-specific pricing",
- proxy_location="RESIDENTIAL_GB"
-)
-```
-
-```typescript TypeScript
-const result = await client.runTask({
- body: {
- prompt: "Get UK-specific pricing",
- proxy_location: "RESIDENTIAL_GB",
- },
-});
-```
-
-```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 UK-specific pricing",
- "proxy_location": "RESIDENTIAL_GB"
- }'
-```
-</CodeGroup>
-
-**Granular targeting (state/city level):**
-
-<CodeGroup>
-```python Python
-result = await client.run_task(
- prompt="Get California pricing",
- proxy_location={
- "country": "US",
- "subdivision": "CA",
- "city": "San Francisco"
- }
-)
-```
-
-```typescript TypeScript
-const result = await client.runTask({
- body: {
- prompt: "Get California pricing",
- proxy_location: {
- country: "US",
- subdivision: "CA",
- city: "San Francisco",
- },
- },
-});
-```
-
-```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 California pricing",
- "proxy_location": {
- "country": "US",
- "subdivision": "CA",
- "city": "San Francisco"
- }
- }'
-```
-</CodeGroup>
-
-The full list of available proxy locations is shown above. Use `NONE` to disable proxies.
-
-<Warning>
-For geo-restricted sites, `proxy_location` is required—without it, you'll get blocked or see wrong regional content (e.g., US prices instead of UK prices).
-</Warning>
-
----
-
-## `browser_session_id`
-
-Run the task in an existing persistent browser session.
-
-Use this to maintain state (cookies, localStorage) across multiple tasks.
-
-<CodeGroup>
-```python Python
-result = await client.run_task(
- prompt="Extract account data",
- browser_session_id="pbs_123"
-)
-```
-
-```typescript TypeScript
-const result = await client.runTask({
- body: {
- prompt: "Extract account data",
- browser_session_id: "pbs_123",
- },
-});
-```
-
-```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 account data",
- "browser_session_id": "pbs_123"
- }'
-```
-</CodeGroup>
-
-Browser sessions persist cookies, localStorage, and authentication state across multiple tasks.
-
----
-
-## `totp_identifier`
-
-Identifier for TOTP codes when you push codes to Skyvern's API.
-
-Use this for two-factor authentication during task execution.
-
-<CodeGroup>
-```python Python
-result = await client.run_task(
- prompt="Log in and extract account balance",
- totp_identifier="my-2fa-credential"
-)
-```
-
-```typescript TypeScript
-const result = await client.runTask({
- body: {
- prompt: "Log in and extract account balance",
- totp_identifier: "my-2fa-credential",
- },
-});
-```
-
-```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 extract account balance",
- "totp_identifier": "my-2fa-credential"
- }'
-```
-</CodeGroup>
-
-TOTP codes are used for two-factor authentication during automated logins.
-
----
-
-## `totp_url`
-
-URL that Skyvern calls to fetch TOTP codes when needed.
-
-Use this when Skyvern should retrieve codes from your endpoint.
-
-<CodeGroup>
-```python Python
-result = await client.run_task(
- prompt="Log in and extract account balance",
- totp_url="https://your-server.com/totp"
-)
-```
-
-```typescript TypeScript
-const result = await client.runTask({
- body: {
- prompt: "Log in and extract account balance",
- totp_url: "https://your-server.com/totp",
- },
-});
-```
-
-```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 extract account balance",
- "totp_url": "https://your-server.com/totp"
- }'
-```
-</CodeGroup>
-
-TOTP codes are used for two-factor authentication during automated logins.
-
----
-
-## `error_code_mapping`
-
-Map specific error conditions to custom error codes.
-
-Use this to make programmatic error handling easier.
-
-<CodeGroup>
-```python Python
-result = await client.run_task(
- prompt="Log in and extract data",
- error_code_mapping={
- "login_failed": "The login credentials are incorrect or the account is locked",
- "maintenance_mode": "The website is down for maintenance"
- }
-)
-```
-
-```typescript TypeScript
-const result = await client.runTask({
- body: {
- prompt: "Log in and extract data",
- error_code_mapping: {
- login_failed: "The login credentials are incorrect or the account is locked",
- maintenance_mode: "The website is down for maintenance",
- },
- },
-});
-```
-
-```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 extract data",
- "error_code_mapping": {
- "login_failed": "The login credentials are incorrect or the account is locked",
- "maintenance_mode": "The website is down for maintenance"
- }
- }'
-```
-</CodeGroup>
-
-If Skyvern encounters a login failure matching your description, `output` contains `{"error": "login_failed"}` instead of a generic error message.
-
----
-
-## `webhook_url`
-
-URL to receive a POST request when the task completes.
-
-Use this instead of polling for production systems.
-
-<CodeGroup>
-```python Python
-result = await client.run_task(
- prompt="Extract pricing data",
- webhook_url="https://your-server.com/webhook"
-)
-```
-
-```typescript TypeScript
-const result = await client.runTask({
- body: {
- prompt: "Extract pricing data",
- 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": "Extract pricing data",
- "webhook_url": "https://your-server.com/webhook"
- }'
-```
-</CodeGroup>
-
-Skyvern sends a POST request with the full run data when the task completes or fails.
-
----
-
-## `title`
-
-Display name for the task in the Skyvern UI.
-
-<CodeGroup>
-```python Python
-result = await client.run_task(
- prompt="Get the top post",
- title="HN Top Post Scraper"
-)
-```
-
-```typescript TypeScript
-const result = await client.runTask({
- body: {
- prompt: "Get the top post",
- title: "HN Top Post Scraper",
- },
-});
-```
-
-```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 post",
- "title": "HN Top Post Scraper"
- }'
-```
-</CodeGroup>
-
----
-
-## `extra_http_headers`
-
-Additional HTTP headers to include in browser requests.
-
-<CodeGroup>
-```python Python
-result = await client.run_task(
- prompt="Access protected resource",
- extra_http_headers={
- "Authorization": "Bearer your-token"
- }
-)
-```
-
-```typescript TypeScript
-const result = await client.runTask({
- body: {
- prompt: "Access protected resource",
- extra_http_headers: {
- Authorization: "Bearer your-token",
- },
- },
-});
-```
-
-```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": "Access protected resource",
- "extra_http_headers": {
- "Authorization": "Bearer your-token"
- }
- }'
-```
-</CodeGroup>
-
----
-
-## `publish_workflow`
-
-Convert this task into a reusable workflow. Only available for `skyvern-2.0`.
-
-<CodeGroup>
-```python Python
-result = await client.run_task(
- prompt="Fill out the contact form with provided data",
- publish_workflow=True
-)
-```
-
-```typescript TypeScript
-const result = await client.runTask({
- body: {
- prompt: "Fill out the contact form with provided data",
- publish_workflow: 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 with provided data",
- "publish_workflow": true
- }'
-```
-</CodeGroup>
-
----
-
-## `max_screenshot_scrolls`
-
-Number of scrolls for post-action screenshots.
-
-Use this for pages with lazy-loaded content.
-
-<CodeGroup>
-```python Python
-result = await client.run_task(
- prompt="Extract all product listings",
- max_screenshot_scrolls=3
-)
-```
-
-```typescript TypeScript
-const result = await client.runTask({
- body: {
- prompt: "Extract all product listings",
- max_screenshot_scrolls: 3,
- },
-});
-```
-
-```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 all product listings",
- "max_screenshot_scrolls": 3
- }'
-```
-</CodeGroup>
-
----
-
-## `browser_address`
-
-Connect to a browser at a specific CDP address.
-
-Use this for local development only.
-
-<CodeGroup>
-```python Python
-result = await client.run_task(
- prompt="Automate my local browser",
- browser_address="http://127.0.0.1:9222"
-)
-```
-
-```typescript TypeScript
-const result = await client.runTask({
- body: {
- prompt: "Automate my local browser",
- browser_address: "http://127.0.0.1:9222",
- },
-});
-```
-
-```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": "Automate my local browser",
- "browser_address": "http://127.0.0.1:9222"
- }'
-```
-</CodeGroup>
-
----
-
-## `run_with`
-
-Choose whether the task runs with the AI agent or generated code.
-
-| Value | Description |
-|-------|-------------|
-| `agent` | Run with the AI agent (default). The agent analyzes screenshots and decides actions in real time. |
-| `code` | Run with generated code. Faster and more deterministic, but requires a previously published workflow. |
-
-<CodeGroup>
-```python Python
-result = await client.run_task(
- prompt="Fill out the contact form",
- run_with="agent"
-)
-```
-
-```typescript TypeScript
-const result = await client.runTask({
- body: {
- prompt: "Fill out the contact form",
- run_with: "agent",
- },
-});
-```
-
-```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",
- "run_with": "agent"
- }'
-```
-</CodeGroup>
-
----
-
-## `model`
-
-Optional model configuration for the task.
-
-<CodeGroup>
-```python Python
-result = await client.run_task(
- prompt="Extract data from the page",
- model={"temperature": 0.5}
-)
-```
-
-```typescript TypeScript
-const result = await client.runTask({
- body: {
- prompt: "Extract data from the page",
- model: { temperature: 0.5 },
- },
-});
-```
-
-```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 data from the page",
- "model": {"temperature": 0.5}
- }'
-```
-</CodeGroup>
-
----
-
-## `include_action_history_in_verification`
-
-Include action history when verifying task completion. Default: `false`.
-
-<CodeGroup>
-```python Python
-result = await client.run_task(
- prompt="Complete the multi-step form",
- include_action_history_in_verification=True
-)
-```
-
-```typescript TypeScript
-const result = await client.runTask({
- body: {
- prompt: "Complete the multi-step form",
- include_action_history_in_verification: 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": "Complete the multi-step form",
- "include_action_history_in_verification": true
- }'
-```
-</CodeGroup>
-
----
-
-## Next steps
-
-<CardGroup cols={2}>
- <Card
- title="Extract Structured Data"
- icon="database"
- href="/running-automations/extract-structured-data"
- >
- Define a schema to get typed JSON output
- </Card>
- <Card
- title="Run a Task"
- icon="play"
- href="/running-automations/run-a-task"
- >
- Execute tasks and retrieve results
- </Card>
-</CardGroup>
diff --git a/docs/sdk-reference/browser-automation/act.mdx b/docs/sdk-reference/browser-automation/act.mdx
new file mode 100644
index 000000000..6346ce101
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/act.mdx
@@ -0,0 +1,29 @@
+---
+title: act
+slug: sdk-reference/browser-automation/act
+---
+
+Perform a freeform AI action on the page. The AI agent interprets the prompt, identifies the relevant elements, and executes the appropriate browser actions.
+
+<CodeGroup>
+```python Python
+await page.act("Scroll down and click the 'Load More' button")
+```
+
+```typescript TypeScript
+await page.act("Scroll down and click the 'Load More' button");
+```
+</CodeGroup>
+
+```python
+await page.act("Click the login button")
+await page.act("Select 'United States' from the country dropdown")
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `prompt` | `str` / `string` | Yes | Natural language instruction describing the action to perform. |
+| `skip_refresh` / `skipRefresh` | `bool` / `boolean` | No | Skip refreshing the page state before acting. Defaults to `False`. |
+| `use_economy_tree` / `useEconomyTree` | `bool` / `boolean` | No | Use a lighter DOM representation to reduce token usage. Defaults to `False`. |
+
+Returns `None` / `void`.
diff --git a/docs/sdk-reference/browser-automation/agent-download-files.mdx b/docs/sdk-reference/browser-automation/agent-download-files.mdx
new file mode 100644
index 000000000..46b038f09
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/agent-download-files.mdx
@@ -0,0 +1,34 @@
+---
+title: agent.download_files
+slug: sdk-reference/browser-automation/agent-download-files
+---
+
+Download files in the context of the current page.
+
+<CodeGroup>
+```python Python
+result = await page.agent.download_files(
+ "Download the latest invoice PDF",
+ download_suffix=".pdf",
+ download_timeout=30,
+)
+```
+
+```typescript TypeScript
+const result = await page.agent.downloadFiles("Download the latest invoice PDF", {
+ downloadSuffix: ".pdf",
+ downloadTimeout: 30,
+});
+```
+</CodeGroup>
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `prompt` | `str` / `string` | Yes | What to download. |
+| `url` | `str` / `string` | No | URL to navigate to. Defaults to current page URL. |
+| `download_suffix` / `downloadSuffix` | `str` / `string` | No | Expected file extension. |
+| `download_timeout` / `downloadTimeout` | `float` / `number` | No | Download timeout in seconds. |
+| `max_steps_per_run` / `maxStepsPerRun` | `int` / `number` | No | Max AI steps. |
+| `timeout` | `float` / `number` | No | Max wait time in seconds. Default: `1800`. |
+
+Returns `WorkflowRunResponse`.
diff --git a/docs/sdk-reference/browser-automation/agent-login.mdx b/docs/sdk-reference/browser-automation/agent-login.mdx
new file mode 100644
index 000000000..18a252aea
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/agent-login.mdx
@@ -0,0 +1,88 @@
+---
+title: agent.login
+slug: sdk-reference/browser-automation/agent-login
+---
+
+Run a login workflow in the context of the current page. Supports multiple credential providers.
+
+## Parameters
+
+| Parameter (Python) | Parameter (TS) | Type | Required | Default | Description |
+|-------------------|----------------|------|----------|---------|-------------|
+| `credential_type` | first positional arg | `CredentialType` / `string` | Yes | - | Provider type: `skyvern`, `bitwarden`, `onepassword`, `azure_vault`. |
+| `url` | `url` | `str` / `string` | No | `None` / `undefined` | URL to navigate to before logging in. |
+| `credential_id` | `credentialId` | `str` / `string` | No | `None` / `undefined` | Skyvern credential ID. Required when `credential_type` is `skyvern`. |
+| `prompt` | `prompt` | `str` / `string` | No | `None` / `undefined` | Additional natural-language login instructions. |
+| `webhook_url` | `webhookUrl` | `str` / `string` | No | `None` / `undefined` | URL to receive a callback when login completes. |
+| `totp_identifier` | `totpIdentifier` | `str` / `string` | No | `None` / `undefined` | Identifier for TOTP-based two-factor authentication. |
+| `totp_url` | `totpUrl` | `str` / `string` | No | `None` / `undefined` | URL for TOTP secret retrieval. |
+| `extra_http_headers` | `extraHttpHeaders` | `dict` / `object` | No | `None` / `undefined` | Additional HTTP headers to set on the browser context. |
+| `timeout` | `timeout` | `float` / `number` | No | `1800` | Maximum time in seconds to wait for login to complete. |
+
+<Note>
+Provider-specific parameters (`bitwarden_item_id`, `onepassword_vault_id`, etc.) are required based on the `credential_type` chosen. See the examples below for each provider.
+</Note>
+
+## Examples
+
+<CodeGroup>
+```python Python
+from skyvern.schemas.run_blocks import CredentialType
+
+# Skyvern credentials
+await page.agent.login(
+ credential_type=CredentialType.skyvern,
+ credential_id="cred_123",
+)
+
+# Bitwarden
+await page.agent.login(
+ credential_type=CredentialType.bitwarden,
+ bitwarden_item_id="item_id",
+ bitwarden_collection_id="collection_id",
+)
+
+# 1Password
+await page.agent.login(
+ credential_type=CredentialType.onepassword,
+ onepassword_vault_id="vault_id",
+ onepassword_item_id="item_id",
+)
+
+# Azure Vault
+await page.agent.login(
+ credential_type=CredentialType.azure_vault,
+ azure_vault_name="vault_name",
+ azure_vault_username_key="username_key",
+ azure_vault_password_key="password_key",
+)
+```
+
+```typescript TypeScript
+// Skyvern credentials
+await page.agent.login("skyvern", {
+ credentialId: "cred_123",
+});
+
+// Bitwarden
+await page.agent.login("bitwarden", {
+ bitwardenItemId: "item_id",
+ bitwardenCollectionId: "collection_id",
+});
+
+// 1Password
+await page.agent.login("1password", {
+ onepasswordVaultId: "vault_id",
+ onepasswordItemId: "item_id",
+});
+
+// Azure Vault
+await page.agent.login("azure_vault", {
+ azureVaultName: "vault_name",
+ azureVaultUsernameKey: "username_key",
+ azureVaultPasswordKey: "password_key",
+});
+```
+</CodeGroup>
+
+Returns `WorkflowRunResponse`.
diff --git a/docs/sdk-reference/browser-automation/agent-run-task.mdx b/docs/sdk-reference/browser-automation/agent-run-task.mdx
new file mode 100644
index 000000000..1cf986b74
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/agent-run-task.mdx
@@ -0,0 +1,51 @@
+---
+title: agent.run_task
+slug: sdk-reference/browser-automation/agent-run-task
+---
+
+Run a complete AI task in the context of the current page.
+
+<CodeGroup>
+```python Python
+result = await page.agent.run_task(
+ "Fill out the contact form and submit it",
+ data_extraction_schema={
+ "type": "object",
+ "properties": {
+ "confirmation_number": {"type": "string"},
+ },
+ },
+)
+print(result.output)
+```
+
+```typescript TypeScript
+const result = await page.agent.runTask("Fill out the contact form and submit it", {
+ dataExtractionSchema: {
+ type: "object",
+ properties: {
+ confirmation_number: { type: "string" },
+ },
+ },
+});
+console.log(result.output);
+```
+</CodeGroup>
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `prompt` | `str` / `string` | Yes | Natural language task description. |
+| `engine` | `RunEngine` | No | AI engine to use. Default: `skyvern_v1`. |
+| `model` | `dict` / `Record<string, unknown>` | No | LLM model configuration. |
+| `url` | `str` / `string` | No | URL to navigate to. Defaults to current page URL. |
+| `data_extraction_schema` / `dataExtractionSchema` | `dict \| str` | No | JSON schema for output. |
+| `max_steps` / `maxSteps` | `int` / `number` | No | Maximum AI steps. |
+| `timeout` | `float` / `number` | No | Max wait time in seconds. Default: `1800`. |
+| `webhook_url` / `webhookUrl` | `str` / `string` | No | Webhook URL for notifications. |
+| `totp_identifier` / `totpIdentifier` | `str` / `string` | No | TOTP identifier. |
+| `totp_url` / `totpUrl` | `str` / `string` | No | TOTP URL. |
+| `title` | `str` / `string` | No | Run display name. |
+| `user_agent` | `str` / `string` | No | Custom User-Agent header for the browser. |
+| `error_code_mapping` / `errorCodeMapping` | `dict` / `Record<string, string>` | No | Custom error code mapping. |
+
+Returns `TaskRunResponse`.
diff --git a/docs/sdk-reference/browser-automation/agent-run-workflow.mdx b/docs/sdk-reference/browser-automation/agent-run-workflow.mdx
new file mode 100644
index 000000000..93473da5d
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/agent-run-workflow.mdx
@@ -0,0 +1,33 @@
+---
+title: agent.run_workflow
+slug: sdk-reference/browser-automation/agent-run-workflow
+---
+
+Run a pre-defined workflow in the context of the current page.
+
+<CodeGroup>
+```python Python
+result = await page.agent.run_workflow(
+ "wpid_abc123",
+ parameters={"company_name": "Acme Corp"},
+)
+print(result.output)
+```
+
+```typescript TypeScript
+const result = await page.agent.runWorkflow("wpid_abc123", {
+ parameters: { company_name: "Acme Corp" },
+});
+console.log(result.output);
+```
+</CodeGroup>
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `workflow_id` / `workflowId` | `str` / `string` | Yes | The workflow permanent ID. |
+| `parameters` | `dict` / `Record<string, unknown>` | No | Workflow input parameters. |
+| `template` | `bool` / `boolean` | No | Whether it's a template. |
+| `title` | `str` / `string` | No | Run display name. |
+| `timeout` | `float` / `number` | No | Max wait time in seconds. Default: `1800`. |
+
+Returns `WorkflowRunResponse`.
diff --git a/docs/sdk-reference/browser-automation/click.mdx b/docs/sdk-reference/browser-automation/click.mdx
new file mode 100644
index 000000000..857d4a0cf
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/click.mdx
@@ -0,0 +1,39 @@
+---
+title: click
+slug: sdk-reference/browser-automation/click
+---
+
+Click an element using a CSS selector, an AI prompt, or both. When both are given, the selector is tried first; if it fails, AI takes over.
+
+<CodeGroup>
+```python Python
+# Standard Playwright click
+await page.click("#submit-button")
+
+# AI-powered click (no selector needed)
+await page.click(prompt="Click the 'Submit' button")
+
+# Selector with AI fallback
+await page.click("#submit-button", prompt="Click the 'Submit' button")
+```
+
+```typescript TypeScript
+// Standard Playwright click
+await page.click("#submit-button");
+
+// AI-powered click (no selector needed)
+await page.click({ prompt: "Click the 'Submit' button" });
+
+// Selector with AI fallback
+await page.click("#submit-button", { prompt: "Click the 'Submit' button" });
+```
+</CodeGroup>
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `selector` | `str` / `string` | No | CSS selector for the target element. |
+| `prompt` | `str` / `string` | No | Natural language description of the element to click. |
+| `ai` | `str` / `string` | No | Controls AI behavior. `"fallback"` (default) tries the selector first, then AI. `None` / `null` disables AI. |
+| `**kwargs` | | No | Standard Playwright click options (e.g., `timeout`, `force`, `position`). |
+
+Returns `str | None` / `string | null` -- the resolved selector used, or `None` if AI handled the click without a selector.
diff --git a/docs/sdk-reference/browser-automation/close.mdx b/docs/sdk-reference/browser-automation/close.mdx
new file mode 100644
index 000000000..43ff6cfce
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/close.mdx
@@ -0,0 +1,18 @@
+---
+title: close
+slug: sdk-reference/browser-automation/close
+---
+
+Close the browser and release resources. If connected to a cloud session, also closes the session.
+
+<CodeGroup>
+```python Python
+await browser.close()
+```
+
+```typescript TypeScript
+await browser.close();
+```
+</CodeGroup>
+
+## Returns `None`
diff --git a/docs/sdk-reference/browser-automation/complete-example.mdx b/docs/sdk-reference/browser-automation/complete-example.mdx
new file mode 100644
index 000000000..21f7e9861
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/complete-example.mdx
@@ -0,0 +1,79 @@
+---
+title: Complete Example
+slug: sdk-reference/browser-automation/complete-example
+---
+
+<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 with Playwright
+ await page.goto("https://app.example.com")
+
+ # Login with AI
+ await page.agent.login(
+ credential_type="skyvern",
+ credential_id="cred_abc123",
+ )
+
+ # Mix Playwright and AI
+ await page.click("#billing-tab")
+ data = await page.extract(
+ "Extract all invoice numbers and amounts",
+ schema={
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "invoice_number": {"type": "string"},
+ "amount": {"type": "string"},
+ },
+ },
+ },
+ )
+ print(data)
+
+ await browser.close()
+
+asyncio.run(main())
+```
+
+```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();
+
+// Navigate with Playwright
+await page.goto("https://app.example.com");
+
+// Login with AI
+await page.agent.login("skyvern", { credentialId: "cred_abc123" });
+
+// Extract data with AI
+const data = await page.extract({
+ prompt: "Extract all invoice numbers and amounts from the billing page",
+ schema: {
+ type: "array",
+ items: {
+ type: "object",
+ properties: {
+ invoice_number: { type: "string" },
+ amount: { type: "string" },
+ },
+ },
+ },
+});
+console.log(data);
+
+// Clean up
+await browser.close();
+```
+</CodeGroup>
diff --git a/docs/sdk-reference/browser-automation/connect-to-browser-over-cdp.mdx b/docs/sdk-reference/browser-automation/connect-to-browser-over-cdp.mdx
new file mode 100644
index 000000000..a8ba502b5
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/connect-to-browser-over-cdp.mdx
@@ -0,0 +1,26 @@
+---
+title: connect_to_browser_over_cdp
+slug: sdk-reference/browser-automation/connect-to-browser-over-cdp
+---
+
+Connect to any browser running with Chrome DevTools Protocol (CDP) enabled, whether local or remote.
+
+<CodeGroup>
+```python Python
+browser = await skyvern.connect_to_browser_over_cdp("http://localhost:9222")
+page = await browser.get_working_page()
+```
+
+```typescript TypeScript
+const browser = await skyvern.connectToBrowserOverCdp("http://localhost:9222");
+const page = await browser.getWorkingPage();
+```
+</CodeGroup>
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `cdp_url` / `cdpUrl` | `str` / `string` | Yes | The CDP WebSocket URL (e.g., `"http://localhost:9222"`). |
+
+## Returns `SkyvernBrowser`
diff --git a/docs/sdk-reference/browser-automation/connect-to-cloud-browser-session.mdx b/docs/sdk-reference/browser-automation/connect-to-cloud-browser-session.mdx
new file mode 100644
index 000000000..943ee54e5
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/connect-to-cloud-browser-session.mdx
@@ -0,0 +1,26 @@
+---
+title: connect_to_cloud_browser_session
+slug: sdk-reference/browser-automation/connect-to-cloud-browser-session
+---
+
+Connect to an existing cloud browser session by ID.
+
+<CodeGroup>
+```python Python
+browser = await skyvern.connect_to_cloud_browser_session("pbs_abc123")
+page = await browser.get_working_page()
+```
+
+```typescript TypeScript
+const browser = await skyvern.connectToCloudBrowserSession("pbs_abc123");
+const page = await browser.getWorkingPage();
+```
+</CodeGroup>
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `browser_session_id` / `browserSessionId` | `str` / `string` | Yes | The ID of the cloud browser session. |
+
+## Returns `SkyvernBrowser`
diff --git a/docs/sdk-reference/browser-automation/extract-form-fields.mdx b/docs/sdk-reference/browser-automation/extract-form-fields.mdx
new file mode 100644
index 000000000..fa4e914f5
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/extract-form-fields.mdx
@@ -0,0 +1,15 @@
+---
+title: extract_form_fields
+slug: sdk-reference/browser-automation/extract-form-fields
+---
+
+Extract all form fields with metadata from the current page.
+
+```python
+fields = await page.extract_form_fields()
+# Returns list of dicts with field name, type, options, etc.
+```
+
+## Returns `list[dict[str, Any]]`
+
+Each dict contains field name, type, options, and other metadata.
diff --git a/docs/sdk-reference/browser-automation/extract.mdx b/docs/sdk-reference/browser-automation/extract.mdx
new file mode 100644
index 000000000..23a2021dc
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/extract.mdx
@@ -0,0 +1,50 @@
+---
+title: extract
+slug: sdk-reference/browser-automation/extract
+---
+
+Extract structured data from the current page.
+
+<CodeGroup>
+```python Python
+data = await page.extract(
+ "Extract all product names and prices",
+ schema={
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "name": {"type": "string"},
+ "price": {"type": "number"},
+ },
+ },
+ },
+)
+print(data)
+```
+
+```typescript 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" },
+ },
+ },
+ },
+});
+console.log(data);
+```
+</CodeGroup>
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `prompt` | `str` / `string` | Yes | What to extract. |
+| `schema` | `dict \| list \| str` / `Record<string, unknown>` | No | JSON schema for output. |
+| `error_code_mapping` / `errorCodeMapping` | `dict` / `Record<string, string>` | No | Custom error codes. |
+
+Returns `dict | list | str | None` / `Record<string, unknown> | unknown[] | string | null`.
diff --git a/docs/sdk-reference/browser-automation/fill-autocomplete.mdx b/docs/sdk-reference/browser-automation/fill-autocomplete.mdx
new file mode 100644
index 000000000..5151d79d1
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/fill-autocomplete.mdx
@@ -0,0 +1,30 @@
+---
+title: fill_autocomplete
+slug: sdk-reference/browser-automation/fill-autocomplete
+---
+
+Fill an input with autocomplete/typeahead handling.
+
+```python
+await page.fill_autocomplete(
+ selector="#city",
+ value="San Francisco",
+ option_selector=".autocomplete-option",
+)
+```
+
+## Parameters
+
+| 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 | Controls AI behavior. `"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`
+
+The resolved selector used.
diff --git a/docs/sdk-reference/browser-automation/fill-form.mdx b/docs/sdk-reference/browser-automation/fill-form.mdx
new file mode 100644
index 000000000..f5fbebc03
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/fill-form.mdx
@@ -0,0 +1,25 @@
+---
+title: fill_form
+slug: sdk-reference/browser-automation/fill-form
+---
+
+Fill a single-page form using AI. Pass a `data` dict describing the values to fill.
+
+```python
+await page.fill_form(
+ data={"name": "John Doe", "email": "[email protected]", "role": "Engineer"},
+)
+
+# With a custom prompt to guide the AI
+await page.fill_form(
+ data={"name": "John Doe", "email": "[email protected]"},
+ 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`
diff --git a/docs/sdk-reference/browser-automation/fill-from-mapping.mdx b/docs/sdk-reference/browser-automation/fill-from-mapping.mdx
new file mode 100644
index 000000000..cbdcd9347
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/fill-from-mapping.mdx
@@ -0,0 +1,23 @@
+---
+title: fill_from_mapping
+slug: sdk-reference/browser-automation/fill-from-mapping
+---
+
+Fill form fields using an explicit index-based mapping produced by `extract_form_fields`.
+
+```python
+fields = await page.extract_form_fields()
+await page.fill_from_mapping(
+ form_fields=fields,
+ mapping={0: "John", 1: "Doe"}, # keys are field indices from extract_form_fields
+ data={"name": "John Doe"},
+)
+```
+
+| 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`
diff --git a/docs/sdk-reference/browser-automation/fill-multipage-form.mdx b/docs/sdk-reference/browser-automation/fill-multipage-form.mdx
new file mode 100644
index 000000000..f4d5f3c63
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/fill-multipage-form.mdx
@@ -0,0 +1,24 @@
+---
+title: fill_multipage_form
+slug: sdk-reference/browser-automation/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": "[email protected]", "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.
diff --git a/docs/sdk-reference/browser-automation/fill.mdx b/docs/sdk-reference/browser-automation/fill.mdx
new file mode 100644
index 000000000..a6bae4562
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/fill.mdx
@@ -0,0 +1,45 @@
+---
+title: fill
+slug: sdk-reference/browser-automation/fill
+---
+
+Fill an input field using a CSS selector, an AI prompt, or both. Supports TOTP code injection for 2FA fields.
+
+<CodeGroup>
+```python Python
+# Standard Playwright fill
+await page.fill("#email", value="[email protected]")
+
+# AI-powered fill
+await page.fill(prompt="Fill '[email protected]' in the email field")
+
+# Selector with AI fallback
+await page.fill("#email", value="[email protected]",
+ prompt="Fill the email address field")
+```
+
+```typescript TypeScript
+// Standard Playwright fill
+await page.fill("#email", "[email protected]");
+
+// AI-powered fill
+await page.fill({ prompt: "Fill '[email protected]' in the email field" });
+
+// Selector with AI fallback
+await page.fill("#email", "[email protected]", {
+ prompt: "Fill the email address field",
+});
+```
+</CodeGroup>
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `selector` | `str` / `string` | No | CSS selector for the input field. |
+| `value` | `str` / `string` | No | The text value to fill into the field. |
+| `prompt` | `str` / `string` | No | Natural language description of the field and the value to enter. |
+| `ai` | `str` / `string` | No | Controls AI behavior. `"fallback"` (default) tries the selector first, then AI. `None` / `null` disables AI. |
+| `totp_identifier` / `totpIdentifier` | `str` / `string` | No | Identifier for a stored TOTP secret to generate a one-time code. |
+| `totp_url` / `totpUrl` | `str` / `string` | No | TOTP provisioning URL (`otpauth://...`) to generate a one-time code on the fly. |
+| `**kwargs` | | No | Standard Playwright fill options (e.g., `timeout`, `force`). |
+
+Returns `str` / `string` -- the resolved selector used.
diff --git a/docs/sdk-reference/browser-automation/frame-list.mdx b/docs/sdk-reference/browser-automation/frame-list.mdx
new file mode 100644
index 000000000..61091e846
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/frame-list.mdx
@@ -0,0 +1,14 @@
+---
+title: frame_list
+slug: sdk-reference/browser-automation/frame-list
+---
+
+List all frames on the current page with metadata.
+
+```python
+frames = await page.frame_list()
+```
+
+## Returns `list[dict[str, Any]]`
+
+Metadata for each frame on the page.
diff --git a/docs/sdk-reference/browser-automation/frame-main.mdx b/docs/sdk-reference/browser-automation/frame-main.mdx
new file mode 100644
index 000000000..4d9d777e2
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/frame-main.mdx
@@ -0,0 +1,12 @@
+---
+title: frame_main
+slug: sdk-reference/browser-automation/frame-main
+---
+
+Switch back to the main page frame.
+
+```python
+page.frame_main()
+```
+
+## Returns `dict[str, str]`
diff --git a/docs/sdk-reference/browser-automation/frame-switch.mdx b/docs/sdk-reference/browser-automation/frame-switch.mdx
new file mode 100644
index 000000000..ad6599360
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/frame-switch.mdx
@@ -0,0 +1,33 @@
+---
+title: frame_switch
+slug: sdk-reference/browser-automation/frame-switch
+---
+
+Switch the working context to an iframe. Exactly one parameter is required.
+
+```python
+# By CSS selector
+await page.frame_switch(selector="#payment-iframe")
+
+# By frame name
+await page.frame_switch(name="checkout")
+
+# By index
+await page.frame_switch(index=0)
+```
+
+## Parameters
+
+| 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.
diff --git a/docs/sdk-reference/browser-automation/get-page-for.mdx b/docs/sdk-reference/browser-automation/get-page-for.mdx
new file mode 100644
index 000000000..9b371f374
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/get-page-for.mdx
@@ -0,0 +1,18 @@
+---
+title: get_page_for
+slug: sdk-reference/browser-automation/get-page-for
+---
+
+Wrap an existing Playwright `Page` with Skyvern AI capabilities.
+
+```python
+skyvern_page = await browser.get_page_for(existing_playwright_page)
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `page` | `Page` | Yes | An existing Playwright `Page` object to wrap. |
+
+## Returns `SkyvernBrowserPage`
diff --git a/docs/sdk-reference/browser-automation/get-working-page.mdx b/docs/sdk-reference/browser-automation/get-working-page.mdx
new file mode 100644
index 000000000..092f47210
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/get-working-page.mdx
@@ -0,0 +1,18 @@
+---
+title: get_working_page
+slug: sdk-reference/browser-automation/get-working-page
+---
+
+Get the most recent page or create a new one if none exists.
+
+<CodeGroup>
+```python Python
+page = await browser.get_working_page()
+```
+
+```typescript TypeScript
+const page = await browser.getWorkingPage();
+```
+</CodeGroup>
+
+Returns a `SkyvernBrowserPage` - a Playwright `Page` with AI methods added.
diff --git a/docs/sdk-reference/browser-automation/hover.mdx b/docs/sdk-reference/browser-automation/hover.mdx
new file mode 100644
index 000000000..3f77c2ec5
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/hover.mdx
@@ -0,0 +1,26 @@
+---
+title: hover
+slug: sdk-reference/browser-automation/hover
+---
+
+Move the mouse over an element. Python only.
+
+```python
+# Hover over a menu item
+await page.hover("#menu-item")
+
+# Hover with a hold duration
+await page.hover("#tooltip-trigger", hold_seconds=1.5)
+
+# Hover with intention logging
+await page.hover("#menu-item", intention="Hover over the main menu")
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `selector` | `str` | Yes | CSS or XPath selector for the target element. |
+| `timeout` | `float` | No | Maximum time in milliseconds to wait 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` - the resolved selector used.
diff --git a/docs/sdk-reference/browser-automation/launch-cloud-browser.mdx b/docs/sdk-reference/browser-automation/launch-cloud-browser.mdx
new file mode 100644
index 000000000..c3bfb9416
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/launch-cloud-browser.mdx
@@ -0,0 +1,47 @@
+---
+title: launch_cloud_browser
+slug: sdk-reference/browser-automation/launch-cloud-browser
+---
+
+Create a new cloud browser session and connect to it. Returns a `SkyvernBrowser` with a live Playwright context.
+
+<Note>
+Python uses `snake_case` (e.g., `launch_cloud_browser`, `get_working_page`); TypeScript uses `camelCase` (e.g., `launchCloudBrowser`, `getWorkingPage`). Some features - form automation, iframe management, `AILocator`, and local browser launch - are Python-only and clearly marked below.
+</Note>
+
+---
+
+<CodeGroup>
+```python Python
+browser = await skyvern.launch_cloud_browser()
+page = await browser.get_working_page()
+
+await page.goto("https://example.com")
+await page.agent.run_task("Fill out the contact form and submit it")
+
+await browser.close()
+```
+
+```typescript TypeScript
+const browser = await skyvern.launchCloudBrowser();
+const page = await browser.getWorkingPage();
+
+await page.goto("https://example.com");
+await page.agent.runTask("Fill out the contact form and submit it");
+
+await browser.close();
+```
+</CodeGroup>
+
+## Parameters
+
+| Parameter (Python) | Parameter (TS) | Type | Required | Default | Description |
+|-------------------|----------------|------|----------|---------|-------------|
+| `timeout` | `timeout` | `int` / `number` | No | `60` | Session timeout in minutes (5–1440). |
+| `proxy_location` | `proxyLocation` | `ProxyLocation` | No | `None` / `undefined` | Geographic proxy location for browser traffic. |
+
+## Returns `SkyvernBrowser`
+
+<Note>
+Cloud browser sessions are only available with `SkyvernEnvironment.CLOUD` / `.Cloud` or `SkyvernEnvironment.STAGING` / `.Staging`.
+</Note>
diff --git a/docs/sdk-reference/browser-automation/launch-local-browser.mdx b/docs/sdk-reference/browser-automation/launch-local-browser.mdx
new file mode 100644
index 000000000..c272d82de
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/launch-local-browser.mdx
@@ -0,0 +1,27 @@
+---
+title: launch_local_browser
+slug: sdk-reference/browser-automation/launch-local-browser
+---
+
+Launch a local Chromium browser with CDP enabled. Only available in embedded mode (`Skyvern.local()`).
+
+```python
+skyvern = Skyvern.local()
+browser = await skyvern.launch_local_browser(headless=False)
+page = await browser.get_working_page()
+```
+
+## Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `headless` | `bool` | No | `False` | Run browser without a visible window. |
+| `port` | `int` | No | `9222` | CDP port. |
+| `args` | `list[str]` | No | `None` | Additional Chromium launch arguments. |
+| `user_data_dir` | `str` | No | `None` | Custom user data directory for the browser. |
+
+## Returns `SkyvernBrowser`
+
+<Note>
+`launch_local_browser` only works in embedded mode because a remote server cannot reach localhost. TypeScript SDK does not support local mode.
+</Note>
diff --git a/docs/sdk-reference/browser-automation/locator.mdx b/docs/sdk-reference/browser-automation/locator.mdx
new file mode 100644
index 000000000..363c29ea4
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/locator.mdx
@@ -0,0 +1,48 @@
+---
+title: locator
+slug: sdk-reference/browser-automation/locator
+---
+
+Locate an element using a CSS/XPath selector, an AI prompt, or both. When called with a `prompt` parameter, returns an `AILocator` - a lazy Playwright `Locator` that resolves the element's position via AI on first use.
+
+```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()
+```
+
+<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>
+
+```python
+# Standard Playwright selector - no AI, identical to vanilla Playwright
+locator = page.locator("#submit-btn")
+await locator.click()
+
+# Combine both: use the selector first, fall back to AI if it fails
+locator = page.locator("#submit-btn", prompt="the submit button")
+await locator.click()
+```
+
+| 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 | Controls AI behavior. Default `"fallback"` 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
+
+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`)
diff --git a/docs/sdk-reference/browser-automation/new-page.mdx b/docs/sdk-reference/browser-automation/new-page.mdx
new file mode 100644
index 000000000..5157af44b
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/new-page.mdx
@@ -0,0 +1,18 @@
+---
+title: new_page
+slug: sdk-reference/browser-automation/new-page
+---
+
+Create a new page (tab) in the browser context.
+
+<CodeGroup>
+```python Python
+page = await browser.new_page()
+```
+
+```typescript TypeScript
+const page = await browser.newPage();
+```
+</CodeGroup>
+
+Returns a `SkyvernBrowserPage` - a Playwright `Page` with AI methods added.
diff --git a/docs/sdk-reference/browser-automation/prompt.mdx b/docs/sdk-reference/browser-automation/prompt.mdx
new file mode 100644
index 000000000..ee753613a
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/prompt.mdx
@@ -0,0 +1,32 @@
+---
+title: prompt
+slug: sdk-reference/browser-automation/prompt
+---
+
+Send a prompt to the LLM and get a structured response about the current page.
+
+<CodeGroup>
+```python Python
+result = await page.prompt(
+ "What is the main heading on this page?",
+ schema={"heading": {"type": "string"}},
+)
+print(result)
+```
+
+```typescript TypeScript
+const result = await page.prompt(
+ "What is the main heading on this page?",
+ { heading: { type: "string" } },
+);
+console.log(result);
+```
+</CodeGroup>
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `prompt` | `str` / `string` | Yes | The question or instruction to send to the LLM about the current page. |
+| `schema` | `dict` / `Record<string, unknown>` | No | JSON schema that constrains the response shape. When provided, the LLM returns data matching this schema. |
+| `model` | `dict` / `Record<string, unknown>` | No | LLM model configuration override. Use to select a different model for this call. |
+
+Returns `dict | list | str | None` / `Record<string, unknown> | unknown[] | string | null`.
diff --git a/docs/sdk-reference/browser-automation/scroll.mdx b/docs/sdk-reference/browser-automation/scroll.mdx
new file mode 100644
index 000000000..bb1cfbfe2
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/scroll.mdx
@@ -0,0 +1,18 @@
+---
+title: scroll
+slug: sdk-reference/browser-automation/scroll
+---
+
+Scroll the page by a given number of pixels along the x and y axes.
+
+```python
+# Scroll down 500px
+await page.scroll(0, 500)
+```
+
+| 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`.
diff --git a/docs/sdk-reference/browser-automation/select-option.mdx b/docs/sdk-reference/browser-automation/select-option.mdx
new file mode 100644
index 000000000..ce4b434d7
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/select-option.mdx
@@ -0,0 +1,43 @@
+---
+title: select_option
+slug: sdk-reference/browser-automation/select-option
+---
+
+Select an option from a dropdown using a CSS selector, an AI prompt, or both.
+
+<CodeGroup>
+```python Python
+# Standard Playwright select
+await page.select_option("#country", value="us")
+
+# AI-powered select
+await page.select_option(prompt="Select 'United States' from the country dropdown")
+
+# Selector with AI fallback
+await page.select_option("#country", value="us",
+ prompt="Select United States from country")
+```
+
+```typescript TypeScript
+// Standard Playwright select
+await page.selectOption("#country", "us");
+
+// AI-powered select
+await page.selectOption({ prompt: "Select 'United States' from the country dropdown" });
+
+// Selector with AI fallback
+await page.selectOption("#country", "us", {
+ prompt: "Select United States from country",
+});
+```
+</CodeGroup>
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `selector` | `str` / `string` | No | CSS selector for the `<select>` element. |
+| `value` | `str` / `string` | No | The option value to select. |
+| `prompt` | `str` / `string` | No | Natural language description of the dropdown and the option to select. |
+| `ai` | `str` / `string` | No | Controls AI behavior. `"fallback"` (default) tries the selector first, then AI. `None` / `null` disables AI. |
+| `**kwargs` | | No | Standard Playwright select options (e.g., `timeout`, `force`). |
+
+Returns `list[str]` / `string[]` -- the selected option values.
diff --git a/docs/sdk-reference/browser-automation/type.mdx b/docs/sdk-reference/browser-automation/type.mdx
new file mode 100644
index 000000000..ecac09977
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/type.mdx
@@ -0,0 +1,31 @@
+---
+title: type
+slug: sdk-reference/browser-automation/type
+---
+
+Type text character-by-character into an input field. Unlike `fill`, this triggers keystroke events for each character - use it for fields that react to individual key presses (search autocomplete, OTP inputs). Python only.
+
+```python
+# Character-by-character input
+await page.type("#search", value="query text")
+
+# 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
+await page.type("#otp", totp_identifier="my-app", totp_url="otpauth://totp/...")
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `selector` | `str` | No | CSS or XPath selector for the input field. |
+| `value` | `str` | No | Text to type character-by-character. |
+| `ai` | `str` | No | Controls AI behavior. Default `"fallback"` tries the selector first, then AI. |
+| `prompt` | `str` | No | Natural-language description of the target field. |
+| `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` - the resolved selector used.
diff --git a/docs/sdk-reference/browser-automation/upload-file.mdx b/docs/sdk-reference/browser-automation/upload-file.mdx
new file mode 100644
index 000000000..07f6ea0c4
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/upload-file.mdx
@@ -0,0 +1,30 @@
+---
+title: upload_file
+slug: sdk-reference/browser-automation/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
+await page.upload_file(prompt="Upload the resume to the file input")
+
+# Selector with AI fallback
+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 | Controls AI behavior. Default `"fallback"` tries the selector first, then AI. |
+
+Returns `str` - the resolved selector used.
diff --git a/docs/sdk-reference/browser-automation/use-cloud-browser.mdx b/docs/sdk-reference/browser-automation/use-cloud-browser.mdx
new file mode 100644
index 000000000..d24126ffb
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/use-cloud-browser.mdx
@@ -0,0 +1,29 @@
+---
+title: use_cloud_browser
+slug: sdk-reference/browser-automation/use-cloud-browser
+---
+
+Get or create a cloud browser session. Reuses the most recent available session if one exists, otherwise creates a new one.
+
+<CodeGroup>
+```python Python
+browser = await skyvern.use_cloud_browser()
+page = await browser.get_working_page()
+```
+
+```typescript TypeScript
+const browser = await skyvern.useCloudBrowser();
+const page = await browser.getWorkingPage();
+```
+</CodeGroup>
+
+## Parameters
+
+Same parameters as `launch_cloud_browser` / `launchCloudBrowser`. Options are only used when creating a new session.
+
+| Parameter (Python) | Parameter (TS) | Type | Required | Default | Description |
+|-------------------|----------------|------|----------|---------|-------------|
+| `timeout` | `timeout` | `int` / `number` | No | `60` | Session timeout in minutes (5--1440). |
+| `proxy_location` | `proxyLocation` | `ProxyLocation` | No | `None` / `undefined` | Geographic proxy location for browser traffic. |
+
+## Returns `SkyvernBrowser`
diff --git a/docs/sdk-reference/browser-automation/validate-mapping.mdx b/docs/sdk-reference/browser-automation/validate-mapping.mdx
new file mode 100644
index 000000000..7e533c30a
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/validate-mapping.mdx
@@ -0,0 +1,23 @@
+---
+title: validate_mapping
+slug: sdk-reference/browser-automation/validate-mapping
+---
+
+Validate that 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 \| None` | Yes | Instruction describing what to validate. |
+
+Returns `bool` -- `True` if the mapping is valid, `False` otherwise.
diff --git a/docs/sdk-reference/browser-automation/validate.mdx b/docs/sdk-reference/browser-automation/validate.mdx
new file mode 100644
index 000000000..2f08695ac
--- /dev/null
+++ b/docs/sdk-reference/browser-automation/validate.mdx
@@ -0,0 +1,22 @@
+---
+title: validate
+slug: sdk-reference/browser-automation/validate
+---
+
+Validate the current page state with AI.
+
+<CodeGroup>
+```python Python
+is_logged_in = await page.validate("Check if the user is logged in")
+print(is_logged_in) # True or False
+```
+
+```typescript TypeScript
+const isLoggedIn = await page.validate("Check if the user is logged in");
+console.log(isLoggedIn); // true or false
+```
+</CodeGroup>
+
+## Returns `bool` / `boolean`
+
+`True` if the condition holds, `False` otherwise.
diff --git a/docs/sdk-reference/browser-profiles.mdx b/docs/sdk-reference/browser-profiles.mdx
deleted file mode 100644
index 2515b2f2a..000000000
--- a/docs/sdk-reference/browser-profiles.mdx
+++ /dev/null
@@ -1,140 +0,0 @@
----
-title: Browser Profiles
-subtitle: Save and reuse browser state across runs
-description: Save and reuse browser state snapshots using the Skyvern Python SDK. Covers create_browser_profile(), list_browser_profiles(), get_browser_profile(), and delete_browser_profile() for persisting cookies and session data across runs.
-slug: sdk-reference/browser-profiles
-keywords:
- - create_browser_profile
- - list_browser_profiles
- - get_browser_profile
- - delete_browser_profile
- - cookies
- - session snapshot
- - persistent state
- - reuse
----
-
-A browser profile is a snapshot of browser state — cookies, local storage, session data. Create a profile from a completed run, then load it into future workflow runs to skip login and setup steps.
-
-For conceptual background, see [Browser Profiles](/optimization/browser-profiles).
-
----
-
-## `create_browser_profile`
-
-Create a profile from a completed workflow run.
-
-```python
-profile = await client.create_browser_profile(
- name="production-login",
- workflow_run_id="wr_abc123",
-)
-print(profile.browser_profile_id) # bpf_abc123
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `name` | `str` | Yes | Display name for the profile. |
-| `description` | `str` | No | Optional description. |
-| `workflow_run_id` | `str` | Conditional | The workflow run ID to snapshot. The run must have used `persist_browser_session=True`. Required if `browser_session_id` is not provided. |
-| `browser_session_id` | `str` | Conditional | The browser session ID to snapshot. Required if `workflow_run_id` is not provided. |
-
-You must provide either `workflow_run_id` or `browser_session_id`.
-
-### Returns `BrowserProfile`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `browser_profile_id` | `str` | Unique ID. Starts with `bpf_`. |
-| `name` | `str` | Profile name. |
-| `description` | `str \| None` | Profile description. |
-| `created_at` | `datetime` | When the profile was created. |
-
-### Example: Create a profile from a login workflow
-
-```python
-# Step 1: Run a workflow with persist_browser_session
-run = await client.run_workflow(
- workflow_id="wpid_login_flow",
- parameters={"username": "[email protected]"},
- wait_for_completion=True,
-)
-
-# Step 2: Create a profile from the run
-profile = await client.create_browser_profile(
- name="demo-account-login",
- workflow_run_id=run.run_id,
-)
-
-# Step 3: Use the profile in future runs (skip login)
-result = await client.run_workflow(
- workflow_id="wpid_extract_invoices",
- browser_profile_id=profile.browser_profile_id,
- wait_for_completion=True,
-)
-```
-
-<Info>
-Session archiving is asynchronous. If `create_browser_profile` fails immediately after a workflow completes, wait a few seconds and retry.
-</Info>
-
----
-
-## `list_browser_profiles`
-
-List all browser profiles.
-
-```python
-profiles = await client.list_browser_profiles()
-for p in profiles:
- print(f"{p.name} ({p.browser_profile_id})")
-```
-
-### Parameters
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `include_deleted` | `bool` | No | `None` | Include soft-deleted profiles in the results. |
-
-### Returns `list[BrowserProfile]`
-
----
-
-## `get_browser_profile`
-
-Get a single profile by ID.
-
-```python
-profile = await client.get_browser_profile("bpf_abc123")
-print(profile.name)
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `profile_id` | `str` | Yes | The browser profile ID. |
-
-### Returns `BrowserProfile`
-
----
-
-## `delete_browser_profile`
-
-Delete a browser profile.
-
-```python
-await client.delete_browser_profile("bpf_abc123")
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `profile_id` | `str` | Yes | The browser profile ID to delete. |
-
-<Warning>
-`browser_profile_id` only works with `run_workflow`, not `run_task`. If you pass it to `run_task`, it will be silently ignored.
-</Warning>
diff --git a/docs/sdk-reference/browser-profiles/create-browser-profile.mdx b/docs/sdk-reference/browser-profiles/create-browser-profile.mdx
new file mode 100644
index 000000000..c78d99b6d
--- /dev/null
+++ b/docs/sdk-reference/browser-profiles/create-browser-profile.mdx
@@ -0,0 +1,150 @@
+---
+title: "create_browser_profile"
+slug: sdk-reference/browser-profiles/create-browser-profile
+---
+
+A browser profile is a snapshot of browser state: cookies, local storage, session data. Create a profile from a completed run, then load it into future workflow runs to skip login and setup steps.
+
+For conceptual background, see [Browser Profiles](/optimization/browser-profiles).
+
+<Note>
+Python uses `snake_case` (e.g., `create_browser_profile`); TypeScript uses `camelCase` (e.g., `createBrowserProfile`). Parameter tables show Python names. TypeScript names are the camelCase equivalents.
+</Note>
+
+Create a profile from a completed workflow run.
+
+<CodeGroup>
+```python Python
+profile = await client.create_browser_profile(
+ name="production-login",
+ workflow_run_id="wr_abc123",
+)
+print(profile.browser_profile_id) # bpf_abc123
+```
+
+```typescript TypeScript
+const profile = await skyvern.createBrowserProfile({
+ name: "production-login",
+ workflow_run_id: "wr_abc123",
+});
+console.log(profile.browser_profile_id); // bpf_abc123
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | `str` | Yes | Display name for the profile. |
+| `description` | `str` | No | Optional description. |
+| `workflow_run_id` | `str` | Conditional | The workflow run ID to snapshot. The run must have used `persist_browser_session=True`. Required if `browser_session_id` is not provided. |
+| `browser_session_id` | `str` | Conditional | The browser session ID to snapshot. Required if `workflow_run_id` is not provided. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+You must provide either `workflow_run_id` or `browser_session_id`.
+
+### Returns `BrowserProfile`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `browser_profile_id` | `str` | Unique ID. Starts with `bpf_`. |
+| `name` | `str` | Profile name. |
+| `description` | `str \| None` | Profile description. |
+| `created_at` | `datetime` | When the profile was created. |
+
+### Example: Create a profile from a login workflow
+
+<CodeGroup>
+```python Python
+# Step 1: Run a workflow with persist_browser_session
+run = await client.run_workflow(
+ workflow_id="wpid_login_flow",
+ parameters={"username": "[email protected]"},
+ wait_for_completion=True,
+)
+
+# Step 2: Create a profile from the run
+profile = await client.create_browser_profile(
+ name="demo-account-login",
+ workflow_run_id=run.run_id,
+)
+
+# Step 3: Use the profile in future runs (skip login)
+result = await client.run_workflow(
+ workflow_id="wpid_extract_invoices",
+ browser_profile_id=profile.browser_profile_id,
+ wait_for_completion=True,
+)
+```
+
+```typescript TypeScript
+// Step 1: Run a workflow with persist_browser_session
+const run = await skyvern.runWorkflow({
+ body: {
+ workflow_id: "wpid_login_flow",
+ parameters: { username: "[email protected]" },
+ },
+ waitForCompletion: true,
+});
+
+// Step 2: Create a profile from the run
+const profile = await skyvern.createBrowserProfile({
+ name: "demo-account-login",
+ workflow_run_id: run.run_id,
+});
+
+// Step 3: Use the profile in future runs (skip login)
+const result = await skyvern.runWorkflow({
+ body: {
+ workflow_id: "wpid_extract_invoices",
+ browser_profile_id: profile.browser_profile_id,
+ },
+ waitForCompletion: true,
+});
+```
+</CodeGroup>
+
+<Info>
+Session archiving is asynchronous. If `create_browser_profile` fails immediately after a workflow completes, wait a few seconds and retry.
+</Info>
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/browser-profiles/delete-browser-profile.mdx b/docs/sdk-reference/browser-profiles/delete-browser-profile.mdx
new file mode 100644
index 000000000..e916f71ba
--- /dev/null
+++ b/docs/sdk-reference/browser-profiles/delete-browser-profile.mdx
@@ -0,0 +1,68 @@
+---
+title: "delete_browser_profile"
+slug: sdk-reference/browser-profiles/delete-browser-profile
+---
+
+Delete a browser profile.
+
+<CodeGroup>
+```python Python
+await client.delete_browser_profile("bpf_abc123")
+```
+
+```typescript TypeScript
+await skyvern.deleteBrowserProfile("bpf_abc123");
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `profile_id` | `str` | Yes | The browser profile ID to delete. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+<Warning>
+`browser_profile_id` only works with `run_workflow`, not `run_task`. If you pass it to `run_task`, it will be silently ignored.
+</Warning>
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/browser-profiles/get-browser-profile.mdx b/docs/sdk-reference/browser-profiles/get-browser-profile.mdx
new file mode 100644
index 000000000..48abd3ac8
--- /dev/null
+++ b/docs/sdk-reference/browser-profiles/get-browser-profile.mdx
@@ -0,0 +1,68 @@
+---
+title: "get_browser_profile"
+slug: sdk-reference/browser-profiles/get-browser-profile
+---
+
+Get a single profile by ID.
+
+<CodeGroup>
+```python Python
+profile = await client.get_browser_profile("bpf_abc123")
+print(profile.name)
+```
+
+```typescript TypeScript
+const profile = await skyvern.getBrowserProfile("bpf_abc123");
+console.log(profile.name);
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `profile_id` | `str` | Yes | The browser profile ID. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+### Returns `BrowserProfile`
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/browser-profiles/list-browser-profiles.mdx b/docs/sdk-reference/browser-profiles/list-browser-profiles.mdx
new file mode 100644
index 000000000..21ae492d5
--- /dev/null
+++ b/docs/sdk-reference/browser-profiles/list-browser-profiles.mdx
@@ -0,0 +1,71 @@
+---
+title: "list_browser_profiles"
+slug: sdk-reference/browser-profiles/list-browser-profiles
+---
+
+List all browser profiles.
+
+<CodeGroup>
+```python Python
+profiles = await client.list_browser_profiles()
+for p in profiles:
+ print(f"{p.name} ({p.browser_profile_id})")
+```
+
+```typescript TypeScript
+const profiles = await skyvern.listBrowserProfiles({});
+for (const p of profiles) {
+ console.log(`${p.name} (${p.browser_profile_id})`);
+}
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `include_deleted` | `bool` | No | `None` | Include soft-deleted profiles in the results. |
+| `request_options` | `RequestOptions` | No | | Per-request configuration (see below). |
+
+### Returns `list[BrowserProfile]`
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/browser-sessions.mdx b/docs/sdk-reference/browser-sessions.mdx
deleted file mode 100644
index 30398eced..000000000
--- a/docs/sdk-reference/browser-sessions.mdx
+++ /dev/null
@@ -1,129 +0,0 @@
----
-title: Browser Sessions
-subtitle: Maintain live browser state between API calls
-description: Create, manage, and close persistent browser sessions using the Skyvern Python SDK. Covers create_browser_session(), get_browser_session(), get_browser_sessions(), and close_browser_session() for chaining tasks in a single browser.
-slug: sdk-reference/browser-sessions
-keywords:
- - create_browser_session
- - get_browser_session
- - close_browser_session
- - persistent browser
- - session chaining
- - cookies
- - login state
- - proxy
----
-
-A browser session is a persistent browser instance that stays alive between API calls. Use sessions to chain multiple tasks in the same browser without losing cookies, local storage, or login state.
-
-For conceptual background, see [Browser Sessions](/optimization/browser-sessions).
-
----
-
-## `create_browser_session`
-
-Spin up a new cloud browser session.
-
-```python
-session = await client.create_browser_session(timeout=60)
-print(session.browser_session_id) # pbs_abc123
-```
-
-### Parameters
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `timeout` | `int` | No | `60` | Session timeout in minutes (5–1440). Timer starts after the session is ready. |
-| `proxy_location` | `ProxyLocation` | No | `None` | Route browser traffic through a geographic proxy. |
-| `extensions` | `list[Extensions]` | No | `None` | Browser extensions to install. Options: `"ad-blocker"`, `"captcha-solver"`. |
-| `browser_type` | `PersistentBrowserType` | No | `None` | Browser type. Options: `"chrome"`, `"msedge"`. |
-
-### Returns `BrowserSessionResponse`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `browser_session_id` | `str` | Unique ID. Starts with `pbs_`. |
-| `status` | `str \| None` | Current session status. |
-| `browser_address` | `str \| None` | CDP address for connecting to the browser. |
-| `app_url` | `str \| None` | Link to the live browser view in the Cloud UI. |
-| `timeout` | `int \| None` | Configured timeout in minutes. |
-| `started_at` | `datetime \| None` | When the session became ready. |
-| `created_at` | `datetime` | When the session was requested. |
-
-### Example: Chain multiple tasks in one session
-
-```python
-session = await client.create_browser_session()
-
-# Step 1: Log in
-await client.run_task(
- prompt="Log in with username [email protected]",
- url="https://app.example.com/login",
- browser_session_id=session.browser_session_id,
- wait_for_completion=True,
-)
-
-# Step 2: Extract data (same browser, already logged in)
-result = await client.run_task(
- prompt="Go to the invoices page and extract all invoice numbers",
- browser_session_id=session.browser_session_id,
- wait_for_completion=True,
-)
-print(result.output)
-
-# Clean up
-await client.close_browser_session(session.browser_session_id)
-```
-
----
-
-## `get_browser_session`
-
-Get the status and details of a session.
-
-```python
-session = await client.get_browser_session("pbs_abc123")
-print(session.status, session.browser_address)
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `browser_session_id` | `str` | Yes | The session ID. |
-
-### Returns `BrowserSessionResponse`
-
----
-
-## `get_browser_sessions`
-
-List all active browser sessions.
-
-```python
-sessions = await client.get_browser_sessions()
-for s in sessions:
- print(f"{s.browser_session_id} — {s.status}")
-```
-
-### Returns `list[BrowserSessionResponse]`
-
----
-
-## `close_browser_session`
-
-Close a browser session and release its resources.
-
-```python
-await client.close_browser_session("pbs_abc123")
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `browser_session_id` | `str` | Yes | The session ID to close. |
-
-<Warning>
-Closing a session is irreversible. Any unsaved state (cookies, local storage) is lost unless you created a [browser profile](/sdk-reference/browser-profiles) from it.
-</Warning>
diff --git a/docs/sdk-reference/browser-sessions/close-browser-session.mdx b/docs/sdk-reference/browser-sessions/close-browser-session.mdx
new file mode 100644
index 000000000..5e69f4173
--- /dev/null
+++ b/docs/sdk-reference/browser-sessions/close-browser-session.mdx
@@ -0,0 +1,68 @@
+---
+title: "close_browser_session"
+slug: sdk-reference/browser-sessions/close-browser-session
+---
+
+Close a browser session and release its resources.
+
+<CodeGroup>
+```python Python
+await client.close_browser_session("pbs_abc123")
+```
+
+```typescript TypeScript
+await skyvern.closeBrowserSession("pbs_abc123");
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `browser_session_id` | `str` | Yes | The session ID to close. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+<Warning>
+Closing a session is irreversible. Any unsaved state (cookies, local storage) is lost unless you created a [browser profile](/sdk-reference/browser-profiles) from it.
+</Warning>
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/browser-sessions/create-browser-session.mdx b/docs/sdk-reference/browser-sessions/create-browser-session.mdx
new file mode 100644
index 000000000..e9d390a6a
--- /dev/null
+++ b/docs/sdk-reference/browser-sessions/create-browser-session.mdx
@@ -0,0 +1,144 @@
+---
+title: "create_browser_session"
+slug: sdk-reference/browser-sessions/create-browser-session
+---
+
+A browser session is a persistent browser instance that stays alive between API calls. Use sessions to chain multiple tasks in the same browser without losing cookies, local storage, or login state.
+
+For conceptual background, see [Browser Sessions](/optimization/browser-sessions).
+
+<Note>
+Python uses `snake_case` (e.g., `create_browser_session`); TypeScript uses `camelCase` (e.g., `createBrowserSession`). Parameter tables show Python names. TypeScript names are the camelCase equivalents.
+</Note>
+
+Spin up a new cloud browser session.
+
+<CodeGroup>
+```python Python
+session = await client.create_browser_session(timeout=60)
+print(session.browser_session_id) # pbs_abc123
+```
+
+```typescript TypeScript
+const session = await skyvern.createBrowserSession({ timeout: 60 });
+console.log(session.browser_session_id); // pbs_abc123
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `timeout` | `int` | No | `60` | Session timeout in minutes (5–1440). Timer starts after the session is ready. |
+| `proxy_location` | `ProxyLocation` | No | `None` | Route browser traffic through a geographic proxy. |
+| `extensions` | `list[Extensions]` | No | `None` | Browser extensions to install. Options: `"ad-blocker"`, `"captcha-solver"`. |
+| `browser_type` | `PersistentBrowserType` | No | `None` | Browser type. Options: `"chrome"`, `"msedge"`. |
+| `browser_profile_id` | `str` | No | `None` | Load a browser profile (cookies, localStorage) into this session. ID starts with `bpf_`. |
+| `request_options` | `RequestOptions` | No | | Per-request configuration (see below). |
+
+### Returns `BrowserSessionResponse`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `browser_session_id` | `str` | Unique ID. Starts with `pbs_`. |
+| `status` | `str \| None` | Current session status. |
+| `browser_address` | `str \| None` | CDP address for connecting to the browser. |
+| `app_url` | `str \| None` | Link to the live browser view in the Cloud UI. |
+| `timeout` | `int \| None` | Configured timeout in minutes. |
+| `started_at` | `datetime \| None` | When the session became ready. |
+| `created_at` | `datetime` | When the session was requested. |
+
+### Example: Chain multiple tasks in one session
+
+<CodeGroup>
+```python Python
+session = await client.create_browser_session()
+
+# Step 1: Log in
+await client.run_task(
+ prompt="Log in with username [email protected]",
+ url="https://app.example.com/login",
+ browser_session_id=session.browser_session_id,
+ wait_for_completion=True,
+)
+
+# Step 2: Extract data (same browser, already logged in)
+result = await client.run_task(
+ prompt="Go to the invoices page and extract all invoice numbers",
+ browser_session_id=session.browser_session_id,
+ wait_for_completion=True,
+)
+print(result.output)
+
+# Clean up
+await client.close_browser_session(session.browser_session_id)
+```
+
+```typescript TypeScript
+const session = await skyvern.createBrowserSession({});
+
+// Step 1: Log in
+await skyvern.runTask({
+ body: {
+ prompt: "Log in with username [email protected]",
+ url: "https://app.example.com/login",
+ browser_session_id: session.browser_session_id,
+ },
+ waitForCompletion: true,
+});
+
+// Step 2: Extract data (same browser, already logged in)
+const result = await skyvern.runTask({
+ body: {
+ prompt: "Go to the invoices page and extract all invoice numbers",
+ browser_session_id: session.browser_session_id,
+ },
+ waitForCompletion: true,
+});
+console.log(result.output);
+
+// Clean up
+await skyvern.closeBrowserSession(session.browser_session_id);
+```
+</CodeGroup>
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/browser-sessions/get-browser-session.mdx b/docs/sdk-reference/browser-sessions/get-browser-session.mdx
new file mode 100644
index 000000000..67bf17127
--- /dev/null
+++ b/docs/sdk-reference/browser-sessions/get-browser-session.mdx
@@ -0,0 +1,68 @@
+---
+title: "get_browser_session"
+slug: sdk-reference/browser-sessions/get-browser-session
+---
+
+Get the status and details of a session.
+
+<CodeGroup>
+```python Python
+session = await client.get_browser_session("pbs_abc123")
+print(session.status, session.browser_address)
+```
+
+```typescript TypeScript
+const session = await skyvern.getBrowserSession("pbs_abc123");
+console.log(session.status, session.browser_address);
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `browser_session_id` | `str` | Yes | The session ID. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+### Returns `BrowserSessionResponse`
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/browser-sessions/get-browser-sessions.mdx b/docs/sdk-reference/browser-sessions/get-browser-sessions.mdx
new file mode 100644
index 000000000..2e0910b64
--- /dev/null
+++ b/docs/sdk-reference/browser-sessions/get-browser-sessions.mdx
@@ -0,0 +1,70 @@
+---
+title: "get_browser_sessions"
+slug: sdk-reference/browser-sessions/get-browser-sessions
+---
+
+List all active browser sessions.
+
+<CodeGroup>
+```python Python
+sessions = await client.get_browser_sessions()
+for s in sessions:
+ print(f"{s.browser_session_id} - {s.status}")
+```
+
+```typescript TypeScript
+const sessions = await skyvern.getBrowserSessions();
+for (const s of sessions) {
+ console.log(`${s.browser_session_id} - ${s.status}`);
+}
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+### Returns `list[BrowserSessionResponse]`
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/complete-reference.mdx b/docs/sdk-reference/complete-reference.mdx
index e30098f91..7f07dab8e 100644
--- a/docs/sdk-reference/complete-reference.mdx
+++ b/docs/sdk-reference/complete-reference.mdx
@@ -20,11 +20,20 @@ keywords:
## Install and initialize
-```bash
+<CodeGroup>
+```bash Python
+# Requires Python 3.11+
pip install skyvern
```
-```python
+```bash TypeScript
+# Requires Node.js 18+
+npm install @skyvern/client
+```
+</CodeGroup>
+
+<CodeGroup>
+```python Python
import asyncio
from skyvern import Skyvern
@@ -40,406 +49,356 @@ async def main():
asyncio.run(main())
```
+```typescript TypeScript
+import { Skyvern } from "@skyvern/client";
+
+const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
+
+const result = await skyvern.runTask({
+ body: {
+ prompt: "Get the title of the top post on Hacker News",
+ url: "https://news.ycombinator.com",
+ },
+ waitForCompletion: true,
+});
+console.log(result.output);
+```
+</CodeGroup>
+
**Constructor:**
-```python
+<CodeGroup>
+```python Python
Skyvern(
api_key: str, # Required
base_url: str | None = None, # Override for self-hosted deployments
- environment: SkyvernEnvironment = CLOUD,# CLOUD or LOCAL
+ environment: SkyvernEnvironment = CLOUD,# CLOUD, STAGING, or LOCAL
timeout: float | None = None, # HTTP request timeout (seconds)
)
-```
-
-**Local mode** (runs entirely on your machine, reads `.env`):
-```python
+# Local mode (Python only - runs entirely on your machine, reads .env)
client = Skyvern.local()
```
-All methods are async. Use `await` inside `async def`, with `asyncio.run()` as entry point.
+```typescript TypeScript
+new Skyvern({
+ apiKey: string, // Required
+ baseUrl?: string, // Override for self-hosted deployments
+ environment?: SkyvernEnvironment | string, // Cloud (default), Staging, or Local
+ timeoutInSeconds?: number, // HTTP request timeout (default: 60)
+ maxRetries?: number, // Retry count (default: 2)
+ headers?: Record<string, string>, // Additional headers
+})
+```
+</CodeGroup>
---
-## Browser control
+## Browser Automation
-The SDK can launch and connect to browsers directly, giving you a Playwright-compatible page with AI capabilities layered on top. This is separate from the API-level browser session methods — here you get a live `SkyvernBrowser` and `SkyvernBrowserPage` you can script against.
+### SkyvernBrowser
-### `launch_local_browser`
+<CodeGroup>
+```python Python
+# Launch / connect
+browser = await client.launch_cloud_browser(timeout=60, proxy_location=None)
+browser = await client.use_cloud_browser(timeout=60, proxy_location=None)
+browser = await client.connect_to_cloud_browser_session("pbs_abc123")
+browser = await client.connect_to_browser_over_cdp("http://localhost:9222")
+browser = await client.launch_local_browser(headless=False, port=9222) # Python only
-Launch a local Chromium browser with CDP enabled. Requires local mode (`Skyvern.local()`).
-
-```python
-browser = await client.launch_local_browser(
- headless: bool = False, # Run headless or with a visible window.
- port: int = 9222, # CDP port.
- args: list[str] | None = None, # Extra Chromium flags.
- user_data_dir: str | None = None,# Persistent profile directory.
-) -> SkyvernBrowser
+# Get pages
+page = await browser.get_working_page() # Most recent page, or creates one
+page = await browser.new_page() # Always creates a new tab
+page = await browser.get_page_for(pw_page) # Wrap existing Playwright Page (Python only)
+await browser.close() # Close browser and cloud session
```
-### `connect_to_browser_over_cdp`
-
-Connect to any running browser via Chrome DevTools Protocol.
+```typescript TypeScript
+// Launch / connect
+const browser = await skyvern.launchCloudBrowser({ timeout: 60 });
+const browser = await skyvern.useCloudBrowser({ timeout: 60 });
+const browser = await skyvern.connectToCloudBrowserSession("pbs_abc123");
+const browser = await skyvern.connectToBrowserOverCdp("http://localhost:9222");
+// launch_local_browser - Python only, no TS equivalent
-```python
-browser = await client.connect_to_browser_over_cdp(
- cdp_url: str, # e.g. "http://localhost:9222"
-) -> SkyvernBrowser
+// Get pages
+const page = await browser.getWorkingPage(); // Most recent page, or creates one
+const page = await browser.newPage(); // Always creates a new tab
+// get_page_for - Python only, no TS equivalent
+await browser.close(); // Close browser and cloud session
```
+</CodeGroup>
-### `connect_to_cloud_browser_session`
+### SkyvernPage
-Connect to an existing cloud browser session by ID.
+AI-enhanced Playwright methods - pass a selector for standard Playwright, add a prompt for AI fallback, or use prompt alone for pure AI.
-```python
-browser = await client.connect_to_cloud_browser_session(
- browser_session_id: str,
-) -> SkyvernBrowser
-```
+<CodeGroup>
+```python Python
+# act - freeform AI action
+await page.act("Click the login button")
-### `launch_cloud_browser`
+# extract - structured data extraction
+data = await page.extract("Extract all products", schema={...})
-Create a new cloud browser session and connect to it.
+# validate - page state assertion, returns bool
+ok = await page.validate("User is logged in")
-```python
-browser = await client.launch_cloud_browser(
- timeout: int | None = None, # Minutes (5-1440). Default 60.
- proxy_location: ProxyLocation | None = None,
-) -> SkyvernBrowser
-```
+# prompt - ask LLM about the page
+result = await page.prompt("What is the heading?", schema={...})
-### `use_cloud_browser`
+# locator - AI element locator returning chainable AILocator (Python only)
+locator = page.locator(prompt="the submit button")
+await locator.click()
-Reuse the most recent available cloud session, or create a new one if none exists.
+# click - selector, AI, or both with fallback
+await page.click("#submit-btn")
+await page.click(prompt="Click the submit button")
+await page.click("#submit-btn", prompt="Click submit")
-```python
-browser = await client.use_cloud_browser(
- timeout: int | None = None,
- proxy_location: ProxyLocation | None = None,
-) -> SkyvernBrowser
-```
+# fill - selector, AI, or both with fallback
+await page.fill("#email", value="[email protected]")
+await page.fill(prompt="Fill email with [email protected]")
-### Getting a page
+# select_option - selector, AI, or both with fallback
+await page.select_option("#country", value="us")
+await page.select_option(prompt="Select United States")
-```python
-page = await browser.get_working_page() # Most recent page, or creates one
-page = await browser.new_page() # Always creates a new tab
-```
+# type - character-by-character input (Python only)
+await page.type("#search", value="query")
-Both return a `SkyvernBrowserPage` — a Playwright `Page` with AI methods added.
+# hover (Python only)
+await page.hover("#menu-item", intention="Hover over the menu")
----
+# scroll (Python only)
+await page.scroll(0, 500)
-## Page-level AI methods
+# upload_file (Python only)
+await page.upload_file("#file-input", files="/path/to/file.pdf")
-`SkyvernBrowserPage` extends Playwright's `Page`. You can use all standard Playwright methods (`goto`, `fill`, `locator`, `screenshot`, etc.) plus these AI-powered methods.
+# fill_form - AI full form fill (Python only)
+await page.fill_form(data={"name": "John", "email": "[email protected]"})
-### `page.act`
+# fill_multipage_form - across page transitions (Python only)
+await page.fill_multipage_form(data={...}, max_pages=5)
-Perform an action described in natural language.
+# fill_from_mapping - explicit field→value mapping (Python only)
+await page.fill_from_mapping(form_fields=fields, mapping={0: "John"}, data={...})
-```python
-await page.act(prompt: str) -> None
-```
+# extract_form_fields - get all fields with metadata (Python only)
+fields = await page.extract_form_fields()
-```python
-await page.act("Click the login button")
-await page.act("Select 'United States' from the country dropdown")
-```
-
-### `page.click` (AI-enhanced)
+# validate_mapping - verify mapping works (Python only)
+is_valid = await page.validate_mapping(form_fields=fields, mapping={...}, prompt="Validate fields")
-Click an element using a CSS selector, an AI prompt, or both with fallback.
+# fill_autocomplete - typeahead handling (Python only)
+await page.fill_autocomplete(selector="#city", value="San Francisco")
-```python
-await page.click(
- selector: str | None = None, # CSS selector.
- prompt: str | None = None, # Natural language target description.
- ai: str | None = "fallback", # "fallback" (try selector, then AI) or None.
- **kwargs, # Standard Playwright click options.
-) -> str | None
+# frame_switch - switch iframe context (Python only)
+await page.frame_switch(selector="#payment-iframe")
+page.frame_main() # back to main frame
+frames = await page.frame_list() # list all frames
```
-```python
-# Selector only
-await page.click("#submit-btn")
+```typescript TypeScript
+// act - freeform AI action
+await page.act("Click the login button");
-# AI only
-await page.click(prompt="Click the 'Submit Order' button")
+// extract - structured data extraction
+const data = await page.extract({ prompt: "Extract all products", schema: {...} });
-# Selector with AI fallback
-await page.click("#submit-btn", prompt="Click the submit button")
-```
+// validate - page state assertion, returns boolean
+const ok = await page.validate("User is logged in");
-### `page.extract`
+// prompt - ask LLM about the page
+const result = await page.prompt("What is the heading?", { heading: { type: "string" } });
-Extract structured data from the current page using AI.
+// find / AILocator - Python only, no TS equivalent
-```python
-result = await page.extract(
- prompt: str, # What to extract.
- schema: dict | list | str | None = None, # JSON Schema for the output.
- error_code_mapping: dict[str, str] | None = None,
-) -> dict | list | str | None
-```
-
-```python
-products = await page.extract(
- prompt="Extract all products with name and price",
- schema={
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "name": {"type": "string"},
- "price": {"type": "number"},
- },
- },
- },
-)
-```
+// click - selector, AI, or both with fallback
+await page.click("#submit-btn");
+await page.click({ prompt: "Click the submit button" });
+await page.click("#submit-btn", { prompt: "Click submit" });
-### `page.agent.run_task`
+// fill - selector, AI, or both with fallback
+await page.fill("#email", "[email protected]");
+await page.fill({ prompt: "Fill email with [email protected]" });
-Run an AI task in the context of the current page. Always waits for completion.
+// selectOption - selector, AI, or both with fallback
+await page.selectOption("#country", "us");
+await page.selectOption({ prompt: "Select United States" });
-```python
-result = await page.agent.run_task(
- prompt: str,
- engine: RunEngine = RunEngine.skyvern_v2,
- url: str | None = None, # Defaults to current page URL.
- data_extraction_schema: dict | str | None = None,
- max_steps: int | None = None,
- timeout: float = 1800,
- # Plus: model, webhook_url, totp_identifier, totp_url, title, error_code_mapping, user_agent
-) -> TaskRunResponse
+// type, hover, scroll, upload_file - Python only
+// fill_form, fill_multipage_form, fill_from_mapping - Python only
+// extract_form_fields, validate_mapping, fill_autocomplete - Python only
+// frame_switch, frame_main, frame_list - Python only
```
+</CodeGroup>
-### `page.agent.login`
+### Page Agent
-Run a login workflow in the context of the current page. Supports all credential types.
+Full task/workflow execution in the context of the current page. Always waits for completion.
-```python
-# Skyvern credentials
-await page.agent.login(
- credential_type=CredentialType.skyvern,
- credential_id="cred_123",
-)
+<CodeGroup>
+```python Python
+# run_task
+result = await page.agent.run_task("Fill out the form", data_extraction_schema={...}, max_steps=10, timeout=1800)
-# Bitwarden
-await page.agent.login(
- credential_type=CredentialType.bitwarden,
- bitwarden_item_id="item_id",
-)
+# login - supports skyvern, bitwarden, onepassword, azure_vault
+await page.agent.login(credential_type=CredentialType.skyvern, credential_id="cred_123")
-# 1Password
-await page.agent.login(
- credential_type=CredentialType.onepassword,
- onepassword_vault_id="vault_id",
- onepassword_item_id="item_id",
-)
+# download_files
+result = await page.agent.download_files("Download the invoice PDF", download_suffix=".pdf")
-# Azure Key Vault
-await page.agent.login(
- credential_type=CredentialType.azure_vault,
- azure_vault_name="vault_name",
- azure_vault_username_key="username_key",
- azure_vault_password_key="password_key",
-)
+# run_workflow
+result = await page.agent.run_workflow("wpid_abc123", parameters={"key": "value"})
```
-### `page.agent.download_files`
+```typescript TypeScript
+// runTask
+const result = await page.agent.runTask("Fill out the form", {
+ dataExtractionSchema: {...}, maxSteps: 10, timeout: 1800,
+});
-Download files using AI navigation, in the context of the current page.
-
-```python
-result = await page.agent.download_files(
- prompt: str,
- url: str | None = None,
- download_suffix: str | None = None,
- download_timeout: float | None = None,
- max_steps_per_run: int | None = None,
- timeout: float = 1800,
-) -> WorkflowRunResponse
-```
+// login - supports skyvern, bitwarden, 1password, azure_vault
+await page.agent.login("skyvern", { credentialId: "cred_123" });
-### `page.agent.run_workflow`
+// downloadFiles
+const result = await page.agent.downloadFiles("Download the invoice PDF", {
+ downloadSuffix: ".pdf",
+});
-Run a workflow in the context of the current page.
-
-```python
-result = await page.agent.run_workflow(
- workflow_id: str,
- parameters: dict | None = None,
- timeout: float = 1800,
-) -> WorkflowRunResponse
-```
-
-### Full example
-
-```python
-from skyvern import Skyvern
-from skyvern.schemas.run_blocks import CredentialType
-
-async def main():
- client = Skyvern(api_key="YOUR_API_KEY")
- browser = await client.launch_cloud_browser()
- page = await browser.get_working_page()
-
- # Navigate and log in with AI
- await page.goto("https://app.example.com")
- await page.agent.login(
- credential_type=CredentialType.skyvern,
- credential_id="cred_123",
- )
-
- # Mix Playwright and AI
- await page.click("#invoices-tab")
- data = await page.extract(
- prompt="Extract all invoice numbers and amounts",
- schema={
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "invoice_number": {"type": "string"},
- "amount": {"type": "number"},
- },
- },
- },
- )
- print(data)
-
- await browser.close()
-
-import asyncio
-asyncio.run(main())
-```
-
----
-
-## Imports
-
-```python
-from skyvern import Skyvern
-from skyvern.client import SkyvernEnvironment # CLOUD, LOCAL
-from skyvern.client.core import ApiError, RequestOptions # Base error, per-request config
-from skyvern.client.errors import ( # HTTP error subclasses
- BadRequestError, # 400
- ForbiddenError, # 403
- NotFoundError, # 404
- ConflictError, # 409
- UnprocessableEntityError, # 422
-)
-from skyvern.schemas.runs import RunEngine # skyvern_v1, skyvern_v2, openai_cua, anthropic_cua, ui_tars
-from skyvern.schemas.run_blocks import CredentialType # skyvern, bitwarden, onepassword, azure_vault
+// runWorkflow
+const result = await page.agent.runWorkflow("wpid_abc123", {
+ parameters: { key: "value" },
+});
```
-
-**Important:** `ApiError` lives in `skyvern.client.core`, not `skyvern.client.errors`. The subclasses (`NotFoundError`, etc.) live in `skyvern.client.errors`.
+</CodeGroup>
---
## Tasks
-### `run_task`
+### run_task
-```python
+<CodeGroup>
+```python Python
result = await client.run_task(
- prompt: str, # Required. Natural language instructions.
- url: str | None = None, # Starting page URL.
- engine: RunEngine = RunEngine.skyvern_v2, # AI engine.
- wait_for_completion: bool = False, # Block until finished.
- timeout: float = 1800, # Max wait (seconds). Only with wait_for_completion.
- max_steps: int | None = None, # Cap AI steps to limit cost.
- data_extraction_schema: dict | str | None = None, # JSON Schema constraining output shape.
- browser_session_id: str | None = None, # Run in existing session.
- publish_workflow: bool = False, # Save generated code as reusable workflow.
+ prompt: str, # Required
+ url: str | None = None,
+ engine: RunEngine = RunEngine.skyvern_v2,
+ wait_for_completion: bool = False,
+ timeout: float = 1800,
+ max_steps: int | None = None,
+ data_extraction_schema: dict | str | None = None,
+ browser_session_id: str | None = None,
+ publish_workflow: bool = False,
proxy_location: ProxyLocation | None = None,
webhook_url: str | None = None,
error_code_mapping: dict[str, str] | None = None,
totp_identifier: str | None = None,
totp_url: str | None = None,
title: str | None = None,
+ model: dict | None = None,
user_agent: str | None = None,
extra_http_headers: dict[str, str] | None = None,
+ include_action_history_in_verification: bool | None = None,
+ max_screenshot_scrolls: int | None = None,
browser_address: str | None = None,
+ run_with: str | None = None,
) -> TaskRunResponse
```
-**`TaskRunResponse` fields:**
+```typescript TypeScript
+const result = await skyvern.runTask({
+ body: {
+ prompt: string, // Required
+ url?: string,
+ engine?: RunEngine, // "skyvern_v2" default
+ max_steps?: number,
+ data_extraction_schema?: Record<string, unknown> | string,
+ browser_session_id?: string,
+ publish_workflow?: boolean,
+ proxy_location?: ProxyLocation,
+ webhook_url?: string,
+ error_code_mapping?: Record<string, string>,
+ totp_identifier?: string,
+ totp_url?: string,
+ title?: string,
+ model?: Record<string, unknown>,
+ user_agent?: string,
+ extra_http_headers?: Record<string, string>,
+ browser_address?: string,
+ run_with?: string,
+ },
+ waitForCompletion?: boolean,
+ timeout?: number, // Default: 1800
+}): Promise<TaskRunResponse>
+```
+</CodeGroup>
-| Field | Type | Description |
-|-------|------|-------------|
-| `run_id` | `str` | Unique ID (`tsk_...`). |
-| `status` | `str` | `created` \| `queued` \| `running` \| `completed` \| `failed` \| `terminated` \| `timed_out` \| `canceled` |
-| `output` | `dict \| list \| None` | Extracted data. `None` until completed. |
-| `failure_reason` | `str \| None` | Error description if failed. |
-| `downloaded_files` | `list[FileInfo] \| None` | Files downloaded during the run. |
-| `recording_url` | `str \| None` | Session recording video URL. |
-| `screenshot_urls` | `list[str] \| None` | Final screenshots. |
-| `app_url` | `str \| None` | Link to run in Skyvern UI. |
-| `step_count` | `int \| None` | Number of AI steps taken. |
-| `created_at` | `datetime` | When the run was created. |
-| `finished_at` | `datetime \| None` | When the run finished. |
+**TaskRunResponse:** `run_id`, `status`, `output`, `failure_reason`, `downloaded_files`, `recording_url`, `screenshot_urls`, `app_url`, `step_count`, `script_run`, `created_at`, `finished_at`
-### `get_run`
+### get_run
-```python
-run = await client.get_run(run_id: str) -> GetRunResponse
+```
+get_run(run_id) → GetRunResponse
```
-Returns status and results for any run (task or workflow).
+### cancel_run
+
+```
+cancel_run(run_id)
+```
-### `cancel_run`
+### get_run_timeline
-```python
-await client.cancel_run(run_id: str)
+```
+get_run_timeline(run_id) → list[WorkflowRunTimeline]
```
-### `get_run_timeline`
+### get_run_artifacts
-```python
-timeline = await client.get_run_timeline(run_id: str) -> list[WorkflowRunTimeline]
+```
+get_run_artifacts(run_id, artifact_type?) → list[Artifact]
```
-### `get_run_artifacts`
+### get_artifact
-```python
-artifacts = await client.get_run_artifacts(
- run_id: str,
- artifact_type: ArtifactType | list[ArtifactType] | None = None,
-) -> list[Artifact]
+```
+get_artifact(artifact_id) → Artifact
```
-### `get_artifact`
+### get_runs_v2
-```python
-artifact = await client.get_artifact(artifact_id: str) -> Artifact
+```
+get_runs_v2(page?, page_size?, status?, search_key?) → list[TaskRunListItem]
```
-### `retry_run_webhook`
+### retry_run_webhook
-```python
-await client.retry_run_webhook(run_id: str)
+```
+retry_run_webhook(run_id, webhook_url?)
```
---
## Workflows
-### `run_workflow`
+### run_workflow
-```python
+<CodeGroup>
+```python Python
result = await client.run_workflow(
workflow_id: str, # Required. Permanent ID (wpid_...).
- parameters: dict | None = None, # Input params matching workflow definition.
+ parameters: dict | None = None,
wait_for_completion: bool = False,
timeout: float = 1800,
- run_with: str | None = None, # "code" (cached Playwright) or "agent" (AI).
- ai_fallback: bool | None = None, # Fall back to AI if code fails.
+ run_with: str | None = None, # "code" or "agent"
+ ai_fallback: bool | None = None,
browser_session_id: str | None = None,
- browser_profile_id: str | None = None, # Load saved browser state.
+ browser_profile_id: str | None = None,
proxy_location: ProxyLocation | None = None,
max_steps_override: int | None = None,
webhook_url: str | None = None,
@@ -449,338 +408,222 @@ result = await client.run_workflow(
totp_url: str | None = None,
user_agent: str | None = None,
extra_http_headers: dict[str, str] | None = None,
+ max_screenshot_scrolls: int | None = None,
browser_address: str | None = None,
) -> WorkflowRunResponse
```
-**`WorkflowRunResponse` fields:** Same as `TaskRunResponse` plus `run_with`, `ai_fallback`, `script_run`.
-
-### `create_workflow`
-
-```python
-workflow = await client.create_workflow(
- json_definition: dict | None = None,
- yaml_definition: str | None = None,
- folder_id: str | None = None,
-) -> Workflow
-```
-
-Provide either `json_definition` or `yaml_definition`. Example:
-
-```python
-workflow = await client.create_workflow(
- json_definition={
- "title": "Extract Products",
- "workflow_definition": {
- "parameters": [
- {
- "key": "target_url",
- "parameter_type": "workflow",
- "workflow_parameter_type": "string",
- "description": "URL to scrape",
- }
- ],
- "blocks": [
- {
- "block_type": "task",
- "label": "extract",
- "prompt": "Extract the top 3 products with name and price",
- "url": "{{ target_url }}",
- }
- ],
- },
- },
-)
-print(workflow.workflow_permanent_id) # wpid_... — use this to run it
+```typescript TypeScript
+const result = await skyvern.runWorkflow({
+ body: {
+ workflow_id: string, // Required
+ parameters?: Record<string, unknown>,
+ browser_session_id?: string,
+ browser_profile_id?: string,
+ proxy_location?: ProxyLocation,
+ webhook_url?: string,
+ title?: string,
+ totp_identifier?: string,
+ totp_url?: string,
+ user_agent?: string,
+ extra_http_headers?: Record<string, string>,
+ browser_address?: string,
+ ai_fallback?: boolean,
+ run_with?: string,
+ },
+ template?: boolean,
+ waitForCompletion?: boolean,
+ timeout?: number, // Default: 1800
+}): Promise<WorkflowRunResponse>
```
+</CodeGroup>
-**`Workflow` fields:** `workflow_id`, `workflow_permanent_id`, `version`, `title`, `workflow_definition`, `status`, `created_at`
+**WorkflowRunResponse:** Same as TaskRunResponse plus `run_with`, `ai_fallback`, `script_run`.
-### `get_workflows`
+### create_workflow
-```python
-workflows = await client.get_workflows(
- page: int | None = None,
- page_size: int | None = None,
- only_saved_tasks: bool | None = None,
- only_workflows: bool | None = None,
- title: str | None = None,
- search_key: str | None = None,
- folder_id: str | None = None,
- status: WorkflowStatus | list[WorkflowStatus] | None = None,
-) -> list[Workflow]
```
-
-### `get_workflow`
-
-```python
-workflow = await client.get_workflow(
- workflow_permanent_id: str,
- version: int | None = None,
- template: bool | None = None,
-) -> Workflow
+create_workflow(json_definition?, yaml_definition?, folder_id?) → Workflow
```
-### `get_workflow_versions`
+### get_workflow
-```python
-versions = await client.get_workflow_versions(
- workflow_permanent_id: str,
- template: bool | None = None,
-) -> list[Workflow]
```
-
-### `update_workflow`
-
-```python
-updated = await client.update_workflow(
- workflow_id: str, # The permanent ID (wpid_...).
- json_definition: dict | None = None,
- yaml_definition: str | None = None,
-) -> Workflow
+get_workflow(workflow_permanent_id, version?, template?) → Workflow
```
-### `delete_workflow`
+### get_workflows
-```python
-await client.delete_workflow(workflow_id: str)
+```
+get_workflows(page?, page_size?, only_saved_tasks?, only_workflows?, only_templates?, title?, search_key?, folder_id?, status?, template?) → list[Workflow]
```
----
-
-## Browser sessions
+### get_workflow_versions
-A persistent browser instance that stays alive between API calls. Use to chain tasks without losing cookies or login state.
+```
+get_workflow_versions(workflow_permanent_id, template?) → list[Workflow]
+```
-### `create_browser_session`
+### update_workflow
-```python
-session = await client.create_browser_session(
- timeout: int | None = 60, # Minutes (5-1440).
- proxy_location: ProxyLocation | None = None,
- extensions: list[Extensions] | None = None, # "ad-blocker", "captcha-solver"
- browser_type: PersistentBrowserType | None = None, # "chrome", "msedge"
-) -> BrowserSessionResponse
+```
+update_workflow(workflow_id, json_definition?, yaml_definition?) → Workflow
```
-**`BrowserSessionResponse` fields:** `browser_session_id`, `status`, `browser_address`, `app_url`, `timeout`, `started_at`, `created_at`
-
-### `get_browser_session`
+### delete_workflow
-```python
-session = await client.get_browser_session(browser_session_id: str) -> BrowserSessionResponse
+```
+delete_workflow(workflow_id)
```
-### `get_browser_sessions`
+### get_workflow_runs
-```python
-sessions = await client.get_browser_sessions() -> list[BrowserSessionResponse]
+```
+get_workflow_runs(page?, page_size?, status?, search_key?, error_code?) → list[WorkflowRun]
```
-### `close_browser_session`
+### update_workflow_folder
-```python
-await client.close_browser_session(browser_session_id: str)
+```
+update_workflow_folder(workflow_permanent_id, folder_id?) → Workflow
```
-### Session chaining example
+**Workflow fields:** `workflow_id`, `workflow_permanent_id`, `version`, `title`, `workflow_definition`, `status`, `created_at`
-```python
-session = await client.create_browser_session()
+---
-# Step 1: Log in
-await client.run_task(
- prompt="Log in with username [email protected]",
- url="https://app.example.com/login",
- browser_session_id=session.browser_session_id,
- wait_for_completion=True,
-)
+## Browser Sessions
-# Step 2: Extract data (same browser, already logged in)
-result = await client.run_task(
- prompt="Go to the invoices page and extract all invoice numbers",
- browser_session_id=session.browser_session_id,
- wait_for_completion=True,
-)
-print(result.output)
+### create_browser_session
-# Clean up
-await client.close_browser_session(session.browser_session_id)
+```
+create_browser_session(timeout?, proxy_location?, extensions?, browser_type?, browser_profile_id?) → BrowserSessionResponse
```
----
+### get_browser_session
-## Browser profiles
+```
+get_browser_session(browser_session_id) → BrowserSessionResponse
+```
+
+### get_browser_sessions
-A saved snapshot of browser state (cookies, local storage). Persists indefinitely. Create from a completed workflow run, then reuse to skip login.
+```
+get_browser_sessions() → list[BrowserSessionResponse]
+```
-### `create_browser_profile`
+### close_browser_session
-```python
-profile = await client.create_browser_profile(
- name: str,
- description: str | None = None,
- workflow_run_id: str | None = None, # Run must have used persist_browser_session=True.
- browser_session_id: str | None = None, # One of workflow_run_id or browser_session_id is required.
-) -> BrowserProfile
+```
+close_browser_session(browser_session_id)
```
-**`BrowserProfile` fields:** `browser_profile_id`, `name`, `description`, `created_at`
+**BrowserSessionResponse fields:** `browser_session_id`, `status`, `browser_address`, `app_url`, `timeout`, `started_at`, `created_at`
-### `list_browser_profiles`
+---
-```python
-profiles = await client.list_browser_profiles(
- include_deleted: bool | None = None,
-) -> list[BrowserProfile]
-```
+## Browser Profiles
-### `get_browser_profile`
+### create_browser_profile
-```python
-profile = await client.get_browser_profile(profile_id: str) -> BrowserProfile
+```
+create_browser_profile(name, description?, workflow_run_id?, browser_session_id?) → BrowserProfile
```
-### `delete_browser_profile`
+### list_browser_profiles
-```python
-await client.delete_browser_profile(profile_id: str)
+```
+list_browser_profiles(include_deleted?) → list[BrowserProfile]
```
-### Profile workflow example
+### get_browser_profile
-```python
-# Step 1: Run a login workflow
-run = await client.run_workflow(
- workflow_id="wpid_login_flow",
- parameters={"username": "[email protected]"},
- wait_for_completion=True,
-)
+```
+get_browser_profile(profile_id) → BrowserProfile
+```
-# Step 2: Create a profile from the run
-profile = await client.create_browser_profile(
- name="demo-account-login",
- workflow_run_id=run.run_id,
-)
+### delete_browser_profile
-# Step 3: Use the profile in future runs (skip login)
-result = await client.run_workflow(
- workflow_id="wpid_extract_invoices",
- browser_profile_id=profile.browser_profile_id,
- wait_for_completion=True,
-)
```
+delete_browser_profile(profile_id)
+```
+
+**BrowserProfile fields:** `browser_profile_id`, `name`, `description`, `created_at`
---
## Credentials
-Store login information securely. Reference by ID instead of passing secrets in code.
+### create_credential
-### `create_credential`
-
-```python
-credential = await client.create_credential(
- name: str,
- credential_type: CredentialType, # e.g. "password"
- credential: dict, # Password: {"username": "...", "password": "..."}
-) -> CredentialResponse
+```
+create_credential(name, credential_type, credential, vault_type?) → CredentialResponse
```
-### `get_credentials`
+### get_credential
-```python
-creds = await client.get_credentials(
- page: int | None = None,
- page_size: int | None = None,
-) -> list[CredentialResponse]
+```
+get_credential(credential_id) → CredentialResponse
```
-### `get_credential`
+### get_credentials
-```python
-cred = await client.get_credential(credential_id: str) -> CredentialResponse
+```
+get_credentials(page?, page_size?, vault_type?) → list[CredentialResponse]
```
-### `delete_credential`
+### update_credential
-```python
-await client.delete_credential(credential_id: str)
+```
+update_credential(credential_id, name, credential_type, credential, vault_type?) → CredentialResponse
```
-### `send_totp_code`
-
-Send a TOTP code to Skyvern during a run that requires 2FA.
+### delete_credential
-```python
-await client.send_totp_code(
- totp_identifier: str,
- content: str, # The TOTP code value.
- task_id: str | None = None,
- workflow_id: str | None = None,
- workflow_run_id: str | None = None,
- source: str | None = None,
- expired_at: datetime | None = None,
-) -> TotpCode
+```
+delete_credential(credential_id)
```
----
+### send_totp_code
-## Helper methods
+```
+send_totp_code(totp_identifier, content, task_id?, workflow_id?, workflow_run_id?, source?, expired_at?, type?) → TotpCode
+```
-### `login`
+---
-Automate logging into a website using stored credentials.
+## Helpers
-```python
-from skyvern.schemas.run_blocks import CredentialType
+### login
-result = await client.login(
- credential_type: CredentialType, # Required. skyvern, bitwarden, onepassword, azure_vault.
- url: str | None = None,
- credential_id: str | None = None, # When using CredentialType.skyvern.
- prompt: str | None = None,
- browser_session_id: str | None = None,
- wait_for_completion: bool = False,
- timeout: float = 1800,
- # Bitwarden: bitwarden_collection_id, bitwarden_item_id
- # 1Password: onepassword_vault_id, onepassword_item_id
- # Azure: azure_vault_name, azure_vault_username_key, azure_vault_password_key, azure_vault_totp_secret_key
-) -> WorkflowRunResponse
+```
+login(credential_type, url?, credential_id?, prompt?, browser_session_id?, browser_profile_id?, browser_address?, proxy_location?, webhook_url?, totp_identifier?, totp_url?, extra_http_headers?, max_screenshot_scrolling_times?, wait_for_completion?, timeout?) → WorkflowRunResponse
```
-### `download_files`
+Credential-specific parameters: `bitwarden_collection_id`, `bitwarden_item_id`, `onepassword_vault_id`, `onepassword_item_id`, `azure_vault_name`, `azure_vault_username_key`, `azure_vault_password_key`, `azure_vault_totp_secret_key`.
-Does **not** support `wait_for_completion`. Returns immediately — poll with `get_run()`.
+### download_files
-```python
-result = await client.download_files(
- navigation_goal: str, # Required. What to download.
- url: str | None = None,
- browser_session_id: str | None = None,
- browser_profile_id: str | None = None,
- download_suffix: str | None = None, # Expected extension, e.g. ".pdf"
- download_timeout: float | None = None,
- max_steps_per_run: int | None = None,
-) -> WorkflowRunResponse
```
+download_files(navigation_goal, url?, browser_session_id?, browser_profile_id?, proxy_location?, webhook_url?, download_suffix?, download_timeout?, max_steps_per_run?, extra_http_headers?, totp_identifier?, totp_url?, browser_address?, max_screenshot_scrolling_times?) → WorkflowRunResponse
+```
+
+Python does not support `wait_for_completion` - poll with `get_run()`. TypeScript supports `waitForCompletion`.
-### `upload_file`
+### upload_file
-```python
-with open("data.csv", "rb") as f:
- upload = await client.upload_file(file=f)
- print(upload.s3uri) # s3://skyvern-uploads/...
- print(upload.presigned_url) # https://...signed download URL
+```
+upload_file(file) → UploadFileResponse
```
-Returns `UploadFileResponse` with fields: `s3uri`, `presigned_url`.
+Returns `s3uri` and `presigned_url`.
---
-## Error handling
+## Error Handling
-```python
+<CodeGroup>
+```python Python
from skyvern.client.core import ApiError
from skyvern.client.errors import NotFoundError
@@ -792,77 +635,60 @@ except ApiError as e:
print(e.status_code, e.body) # Any other HTTP error
```
-**Error types:** `BadRequestError` (400), `ForbiddenError` (403), `NotFoundError` (404), `ConflictError` (409), `UnprocessableEntityError` (422). All inherit from `ApiError`.
+```typescript TypeScript
+import { SkyvernError, SkyvernTimeoutError, SkyvernApi } from "@skyvern/client";
-**Completion timeout** raises Python's built-in `TimeoutError`:
-
-```python
-try:
- result = await client.run_task(
- prompt="...", url="...", wait_for_completion=True, timeout=300,
- )
-except TimeoutError:
- print("Task didn't complete in time")
+try {
+ const run = await skyvern.getRun("tsk_nonexistent");
+} catch (e) {
+ if (e instanceof SkyvernApi.NotFoundError) {
+ console.log(e.statusCode, e.body); // 404
+ } else if (e instanceof SkyvernError) {
+ console.log(e.statusCode, e.body); // Any other HTTP error
+ }
+}
```
+</CodeGroup>
-**Run failure** is not an exception — check `result.status`:
+**Error types:** `BadRequestError` (400), `ForbiddenError` (403), `NotFoundError` (404), `ConflictError` (409), `UnprocessableEntityError` (422). All inherit from `ApiError` (Python) or `SkyvernError` (TypeScript).
-```python
-if result.status == "failed":
- print(result.failure_reason)
-elif result.status == "completed":
- print(result.output)
-```
+Run failure is not an exception - check `result.status` (`completed`, `failed`, `terminated`, `timed_out`, `canceled`).
---
## Request options
-Override timeout, retries, or headers per-request:
+Every method accepts `request_options` (Python) or a second options argument (TypeScript) for per-request overrides:
-```python
+<CodeGroup>
+```python Python
from skyvern.client.core import RequestOptions
-result = await client.run_task(
- prompt="...",
- url="...",
- request_options=RequestOptions(
- timeout_in_seconds=120,
- max_retries=3,
- additional_headers={"x-custom-header": "value"},
- ),
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
)
```
----
-
-## Polling pattern
-
-When not using `wait_for_completion`:
-
-```python
-import asyncio
-
-task = await client.run_task(prompt="...", url="...")
-
-while True:
- run = await client.get_run(task.run_id)
- if run.status in ("completed", "failed", "terminated", "timed_out", "canceled"):
- break
- await asyncio.sleep(5)
-
-print(run.output)
+```typescript TypeScript
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+ abortSignal: controller.signal, // TypeScript only
+ apiKey: "override-key", // TypeScript only
+}
```
+</CodeGroup>
---
## Key constraints
-- `browser_profile_id` works with `run_workflow` only — silently ignored by `run_task`.
-- `download_files` does not support `wait_for_completion` — poll manually or use webhooks.
+- `browser_profile_id` works with `run_workflow` only - silently ignored by `run_task`.
+- Python `download_files` does not support `wait_for_completion` - poll manually or use webhooks.
- Only workflow runs with `persist_browser_session=True` produce archives for profile creation.
-- Session archiving is async — profile creation may need a short retry delay after a run completes.
-- `engine` accepts `RunEngine` enum values: `skyvern_v1`, `skyvern_v2`, `openai_cua`, `anthropic_cua`, `ui_tars`.
-- `launch_local_browser` only works in local mode (`Skyvern.local()`). Cloud browser methods (`launch_cloud_browser`, `use_cloud_browser`, `connect_to_cloud_browser_session`) require cloud environment.
-- `page.agent` methods always wait for completion — they don't support `wait_for_completion=False`.
-- TypeScript SDK does not support browser control (local or cloud) — use the Python SDK for browser automation.
+- `launch_local_browser` requires Python local mode (`Skyvern.local()`).
+- `page.agent` methods always wait for completion.
+- Python-only features: `launch_local_browser`, `get_page_for`, `locator`/`AILocator`, `type`, `hover`, `scroll`, `upload_file` (page-level), form automation (`fill_form`, `fill_multipage_form`, `fill_from_mapping`, `extract_form_fields`, `validate_mapping`, `fill_autocomplete`), iframe management (`frame_switch`, `frame_main`, `frame_list`).
diff --git a/docs/sdk-reference/credentials.mdx b/docs/sdk-reference/credentials.mdx
deleted file mode 100644
index afaea7161..000000000
--- a/docs/sdk-reference/credentials.mdx
+++ /dev/null
@@ -1,131 +0,0 @@
----
-title: Credentials
-subtitle: Store and manage authentication credentials securely
-description: Store and manage login credentials and TOTP secrets using the Skyvern Python SDK. Covers create_credential(), get_credentials(), get_credential(), delete_credential(), and send_totp_code() for secure authentication management.
-slug: sdk-reference/credentials
-keywords:
- - credential
- - password
- - TOTP
- - 2FA
- - authentication
- - create_credential
- - get_credentials
- - delete_credential
- - send_totp_code
- - secret
----
-
-Credentials let you store login information (username/password, TOTP secrets) securely in Skyvern's vault. Reference them by ID in tasks and workflows instead of passing secrets in your code.
-
----
-
-## `create_credential`
-
-Store a new credential.
-
-```python
-credential = await client.create_credential(
- name="my-app-login",
- credential_type="password",
- credential={
- "username": "[email protected]",
- "password": "s3cur3-p4ss",
- },
-)
-print(credential.credential_id)
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `name` | `str` | Yes | Display name for the credential. |
-| `credential_type` | `CredentialType` | Yes | Type of credential. |
-| `credential` | `CreateCredentialRequestCredential` | Yes | The credential data. Shape depends on `credential_type`. |
-
-### Returns `CredentialResponse`
-
----
-
-## `get_credentials`
-
-List all credentials. Credential values are never returned — only metadata.
-
-```python
-creds = await client.get_credentials()
-for c in creds:
- print(f"{c.name} ({c.credential_id})")
-```
-
-### Parameters
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `page` | `int` | No | `None` | Page number. |
-| `page_size` | `int` | No | `None` | Results per page. |
-
-### Returns `list[CredentialResponse]`
-
----
-
-## `get_credential`
-
-Get a single credential's metadata by ID.
-
-```python
-cred = await client.get_credential("cred_abc123")
-print(cred.name, cred.credential_type)
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `credential_id` | `str` | Yes | The credential ID. |
-
-### Returns `CredentialResponse`
-
----
-
-## `delete_credential`
-
-Delete a credential.
-
-```python
-await client.delete_credential("cred_abc123")
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `credential_id` | `str` | Yes | The credential ID to delete. |
-
----
-
-## `send_totp_code`
-
-Send a TOTP (time-based one-time password) code to Skyvern during a run that requires 2FA. Call this when your webhook or polling detects that Skyvern is waiting for a TOTP code.
-
-```python
-await client.send_totp_code(
- totp_identifier="[email protected]",
- content="123456",
-)
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `totp_identifier` | `str` | Yes | The identifier matching the `totp_identifier` used in the task/workflow. |
-| `content` | `str` | Yes | The TOTP code value. |
-| `task_id` | `str` | No | Associate with a specific task run. |
-| `workflow_id` | `str` | No | Associate with a specific workflow. |
-| `workflow_run_id` | `str` | No | Associate with a specific workflow run. |
-| `source` | `str` | No | Source of the TOTP code. |
-| `expired_at` | `datetime` | No | When this code expires. |
-| `type` | `OtpType` | No | OTP type. |
-
-### Returns `TotpCode`
diff --git a/docs/sdk-reference/credentials/create-credential.mdx b/docs/sdk-reference/credentials/create-credential.mdx
new file mode 100644
index 000000000..83ffe4be4
--- /dev/null
+++ b/docs/sdk-reference/credentials/create-credential.mdx
@@ -0,0 +1,91 @@
+---
+title: "create_credential"
+slug: sdk-reference/credentials/create-credential
+---
+
+Credentials let you store login information (username/password, TOTP secrets) securely in Skyvern's vault. Reference them by ID in tasks and workflows instead of passing secrets in your code.
+
+<Note>
+Python uses `snake_case` (e.g., `create_credential`); TypeScript uses `camelCase` (e.g., `createCredential`). Parameter tables show Python names. TypeScript names are the camelCase equivalents.
+</Note>
+
+Store a new credential.
+
+<CodeGroup>
+```python Python
+credential = await client.create_credential(
+ name="my-app-login",
+ credential_type="password",
+ credential={
+ "username": "[email protected]",
+ "password": "s3cur3-p4ss",
+ },
+)
+print(credential.credential_id)
+```
+
+```typescript TypeScript
+const credential = await skyvern.createCredential({
+ name: "my-app-login",
+ credential_type: "password",
+ credential: {
+ username: "[email protected]",
+ password: "s3cur3-p4ss",
+ },
+});
+console.log(credential.credential_id);
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | `str` | Yes | Display name for the credential. |
+| `credential_type` | `CredentialType` | Yes | Type of credential. |
+| `credential` | `CreateCredentialRequestCredential` | Yes | The credential data. Shape depends on `credential_type`. |
+| `vault_type` | `CredentialVaultType` | No | Which vault to store this credential in. If omitted, uses the default. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+### Returns `CredentialResponse`
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/credentials/delete-credential.mdx b/docs/sdk-reference/credentials/delete-credential.mdx
new file mode 100644
index 000000000..1d3a45ff0
--- /dev/null
+++ b/docs/sdk-reference/credentials/delete-credential.mdx
@@ -0,0 +1,64 @@
+---
+title: "delete_credential"
+slug: sdk-reference/credentials/delete-credential
+---
+
+Delete a credential.
+
+<CodeGroup>
+```python Python
+await client.delete_credential("cred_abc123")
+```
+
+```typescript TypeScript
+await skyvern.deleteCredential("cred_abc123");
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `credential_id` | `str` | Yes | The credential ID to delete. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/credentials/get-credential.mdx b/docs/sdk-reference/credentials/get-credential.mdx
new file mode 100644
index 000000000..cd0309441
--- /dev/null
+++ b/docs/sdk-reference/credentials/get-credential.mdx
@@ -0,0 +1,68 @@
+---
+title: "get_credential"
+slug: sdk-reference/credentials/get-credential
+---
+
+Get a single credential's metadata by ID.
+
+<CodeGroup>
+```python Python
+cred = await client.get_credential("cred_abc123")
+print(cred.name, cred.credential_type)
+```
+
+```typescript TypeScript
+const cred = await skyvern.getCredential("cred_abc123");
+console.log(cred.name, cred.credential_type);
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `credential_id` | `str` | Yes | The credential ID. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+### Returns `CredentialResponse`
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/credentials/get-credentials.mdx b/docs/sdk-reference/credentials/get-credentials.mdx
new file mode 100644
index 000000000..6b1af0f8f
--- /dev/null
+++ b/docs/sdk-reference/credentials/get-credentials.mdx
@@ -0,0 +1,73 @@
+---
+title: "get_credentials"
+slug: sdk-reference/credentials/get-credentials
+---
+
+List all credentials. Credential values are never returned - only metadata.
+
+<CodeGroup>
+```python Python
+creds = await client.get_credentials()
+for c in creds:
+ print(f"{c.name} ({c.credential_id})")
+```
+
+```typescript TypeScript
+const creds = await skyvern.getCredentials({});
+for (const c of creds) {
+ console.log(`${c.name} (${c.credential_id})`);
+}
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `page` | `int` | No | `None` | Page number. |
+| `page_size` | `int` | No | `None` | Results per page. |
+| `vault_type` | `CredentialVaultType` | No | `None` | Filter credentials by vault type (e.g. `"custom"`, `"bitwarden"`, `"azure_vault"`). |
+| `request_options` | `RequestOptions` | No | `None` | Per-request configuration (see below). |
+
+### Returns `list[CredentialResponse]`
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/credentials/send-totp-code.mdx b/docs/sdk-reference/credentials/send-totp-code.mdx
new file mode 100644
index 000000000..1a265b6cb
--- /dev/null
+++ b/docs/sdk-reference/credentials/send-totp-code.mdx
@@ -0,0 +1,79 @@
+---
+title: "send_totp_code"
+slug: sdk-reference/credentials/send-totp-code
+---
+
+Send a TOTP (time-based one-time password) code to Skyvern during a run that requires 2FA. Call this when your webhook or polling detects that Skyvern is waiting for a TOTP code.
+
+<CodeGroup>
+```python Python
+await client.send_totp_code(
+ totp_identifier="[email protected]",
+ content="123456",
+)
+```
+
+```typescript TypeScript
+await skyvern.sendTotpCode({
+ totp_identifier: "[email protected]",
+ content: "123456",
+});
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `totp_identifier` | `str` | Yes | The identifier matching the `totp_identifier` used in the task/workflow. |
+| `content` | `str` | Yes | The TOTP code value. |
+| `task_id` | `str` | No | Associate with a specific task run. |
+| `workflow_id` | `str` | No | Associate with a specific workflow. |
+| `workflow_run_id` | `str` | No | Associate with a specific workflow run. |
+| `source` | `str` | No | Source of the TOTP code. |
+| `expired_at` | `datetime` | No | When this code expires. |
+| `type` | `OtpType` | No | OTP type. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+### Returns `TotpCode`
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/credentials/update-credential.mdx b/docs/sdk-reference/credentials/update-credential.mdx
new file mode 100644
index 000000000..1c51385b2
--- /dev/null
+++ b/docs/sdk-reference/credentials/update-credential.mdx
@@ -0,0 +1,85 @@
+---
+title: "update_credential"
+slug: sdk-reference/credentials/update-credential
+---
+
+Overwrite the stored credential data (e.g. username/password) while keeping the same credential ID.
+
+<CodeGroup>
+```python Python
+updated = await client.update_credential(
+ "cred_abc123",
+ name="Updated Login",
+ credential_type="password",
+ credential={
+ "username": "[email protected]",
+ "password": "new_password",
+ },
+)
+```
+
+```typescript TypeScript
+const updated = await skyvern.updateCredential("cred_abc123", {
+ name: "Updated Login",
+ credential_type: "password",
+ credential: {
+ username: "[email protected]",
+ password: "new_password",
+ },
+});
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `credential_id` | `str` | Yes | The credential ID to update. |
+| `name` | `str` | Yes | Name of the credential. |
+| `credential_type` | `str` | Yes | Type of credential (`"password"`, `"credit_card"`, `"secret"`). |
+| `credential` | `dict` | Yes | The new credential data. |
+| `vault_type` | `CredentialVaultType` | No | Vault provider. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+### Returns `CredentialResponse`
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/error-handling.mdx b/docs/sdk-reference/error-handling.mdx
index 70064cd69..14fcf0d96 100644
--- a/docs/sdk-reference/error-handling.mdx
+++ b/docs/sdk-reference/error-handling.mdx
@@ -16,7 +16,7 @@ keywords:
- failure
---
-The SDK raises typed exceptions for API errors. All errors extend `ApiError` and include the HTTP status code, response headers, and body.
+The SDK raises typed exceptions for API errors. In Python, all errors extend `ApiError`. In TypeScript, all errors extend `SkyvernError`. Both include the HTTP status code, response body, and headers.
---
@@ -29,11 +29,13 @@ The SDK raises typed exceptions for API errors. All errors extend `ApiError` and
| `NotFoundError` | 404 | Resource (run, workflow, session) not found. |
| `ConflictError` | 409 | Resource conflict (e.g., duplicate creation). |
| `UnprocessableEntityError` | 422 | Request validation failed. |
-| `ApiError` | Any | Base class for all API errors. Catch this as a fallback. |
+| `ApiError` (Python) / `SkyvernError` (TS) | Any | Base class for all API errors. Catch this as a fallback. |
+| `SkyvernTimeoutError` (TS only) | - | HTTP request timed out. |
-The specific error classes live in `skyvern.client.errors`. The base `ApiError` class lives in `skyvern.client.core`:
+Import errors from the package:
-```python
+<CodeGroup>
+```python Python
from skyvern.client.core import ApiError
from skyvern.client.errors import (
BadRequestError,
@@ -44,11 +46,34 @@ from skyvern.client.errors import (
)
```
+```typescript TypeScript
+import { SkyvernError, SkyvernTimeoutError, SkyvernApi } from "@skyvern/client";
+
+// Base errors are top-level exports:
+// SkyvernError - base class for all API errors
+// SkyvernTimeoutError - HTTP request timed out
+
+// HTTP status error subclasses are accessed via the SkyvernApi namespace:
+// SkyvernApi.BadRequestError - 400
+// SkyvernApi.ForbiddenError - 403
+// SkyvernApi.NotFoundError - 404
+// SkyvernApi.ConflictError - 409
+// SkyvernApi.UnprocessableEntityError - 422
+```
+</CodeGroup>
+
+The specific Python error classes live in `skyvern.client.errors`. The base `ApiError` class lives in `skyvern.client.core`.
+
+<Warning>
+**TypeScript:** `SkyvernError` and `SkyvernTimeoutError` are top-level exports. The HTTP-specific errors (`BadRequestError`, etc.) extend `SkyvernError` and are accessed via the `SkyvernApi` namespace.
+</Warning>
+
---
## Catching errors
-```python
+<CodeGroup>
+```python Python
from skyvern import Skyvern
from skyvern.client.core import ApiError
from skyvern.client.errors import NotFoundError
@@ -63,15 +88,34 @@ except ApiError as e:
print(f"API error {e.status_code}: {e.body}")
```
+```typescript TypeScript
+import { Skyvern, SkyvernError, SkyvernApi } from "@skyvern/client";
+
+const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
+
+try {
+ const run = await skyvern.getRun("tsk_nonexistent");
+} catch (e) {
+ if (e instanceof SkyvernApi.NotFoundError) {
+ console.log(`Run not found: ${e.body}`);
+ } else if (e instanceof SkyvernError) {
+ console.log(`API error ${e.statusCode}: ${e.body}`);
+ }
+}
+```
+</CodeGroup>
+
### Error properties
Every error has these attributes:
-| Property | Type | Description |
-|----------|------|-------------|
-| `status_code` | `int \| None` | HTTP status code. |
-| `body` | `Any` | Response body (usually a dict with error details). |
-| `headers` | `dict[str, str] \| None` | Response headers. |
+| Property (Python) | Property (TS) | Type | Description |
+|-------------------|---------------|------|-------------|
+| `status_code` | `statusCode` | `int \| None` | HTTP status code. |
+| `body` | `body` | `Any` | Response body (usually a dict with error details). |
+| `headers` | - | `dict[str, str] \| None` | Response headers. |
+| - | `rawResponse` | `RawResponse \| undefined` | The raw HTTP response (TS only). |
+| - | `message` | `string` | Human-readable error message (TS only). |
---
@@ -83,7 +127,8 @@ Two different timeouts apply:
Controls how long the SDK waits for the HTTP response from the Skyvern API. Set it in the constructor or per-request:
-```python
+<CodeGroup>
+```python Python
# Global timeout (applies to all requests)
client = Skyvern(api_key="YOUR_API_KEY", timeout=30.0)
@@ -96,11 +141,28 @@ result = await client.get_run(
)
```
+```typescript TypeScript
+// Global timeout (applies to all requests)
+const skyvern = new Skyvern({
+ apiKey: "YOUR_API_KEY",
+ timeoutInSeconds: 30,
+});
+
+// Per-request timeout
+const result = await skyvern.getRun("tsk_abc123", {
+ timeoutInSeconds: 10,
+});
+```
+</CodeGroup>
+
+When an HTTP request times out in TypeScript, a `SkyvernTimeoutError` is thrown.
+
### Completion timeout
-Controls how long `wait_for_completion` polls before giving up. This is separate from the HTTP timeout:
+Controls how long `wait_for_completion` / `waitForCompletion` polls before giving up. This is separate from the HTTP timeout:
-```python
+<CodeGroup>
+```python Python
try:
result = await client.run_task(
prompt="Extract data",
@@ -112,15 +174,34 @@ except TimeoutError:
print("Task didn't complete in time")
```
-The completion timeout raises Python's built-in `TimeoutError` (via `asyncio.timeout`), not `ApiError`.
+```typescript TypeScript
+try {
+ const result = await skyvern.runTask({
+ body: {
+ prompt: "Extract data",
+ url: "https://example.com",
+ },
+ waitForCompletion: true,
+ timeout: 300, // Give up after 5 minutes
+ });
+} catch (e) {
+ if (e instanceof Error && e.message.includes("Timeout")) {
+ console.log("Task didn't complete in time");
+ }
+}
+```
+</CodeGroup>
+
+The completion timeout raises Python's built-in `TimeoutError` (via `asyncio.timeout`), not `ApiError`. In TypeScript, it throws a standard `Error` with a timeout message.
---
## Retries
-Configure automatic retries for transient failures using `RequestOptions`:
+Configure automatic retries for transient failures. Set it in the constructor or per-request:
-```python
+<CodeGroup>
+```python Python
from skyvern.client.core import RequestOptions
result = await client.run_task(
@@ -130,7 +211,56 @@ result = await client.run_task(
)
```
-Retries apply to the HTTP request level (network errors, 5xx responses). They do not retry the entire task if it fails at the AI level — use `get_run` to check the status and re-run if needed.
+```typescript TypeScript
+// Global retries (default: 2)
+const skyvern = new Skyvern({
+ apiKey: "YOUR_API_KEY",
+ maxRetries: 3,
+});
+
+// Per-request retries
+const result = await skyvern.runTask(
+ {
+ body: {
+ prompt: "Extract product data",
+ url: "https://example.com/products",
+ },
+ },
+ { maxRetries: 5 },
+);
+```
+</CodeGroup>
+
+Retries apply to the HTTP request level (network errors, 5xx responses). They do not retry the entire task if it fails at the AI level - use `get_run` / `getRun` to check the status and re-run if needed.
+
+---
+
+## Abort requests (TypeScript only)
+
+Cancel in-flight requests using `AbortSignal`:
+
+```typescript
+const controller = new AbortController();
+
+// Cancel after 10 seconds
+setTimeout(() => controller.abort(), 10000);
+
+try {
+ const result = await skyvern.runTask(
+ {
+ body: {
+ prompt: "Extract data",
+ url: "https://example.com",
+ },
+ },
+ { abortSignal: controller.signal },
+ );
+} catch (e) {
+ if (e instanceof Error && e.name === "AbortError") {
+ console.log("Request was aborted");
+ }
+}
+```
---
@@ -138,9 +268,10 @@ Retries apply to the HTTP request level (network errors, 5xx responses). They do
There are two distinct failure modes:
-**API error** — The HTTP request itself failed. The SDK raises an exception.
+**API error** - The HTTP request itself failed. The SDK raises an exception.
-```python
+<CodeGroup>
+```python Python
from skyvern.client.core import ApiError
try:
@@ -149,9 +280,25 @@ except ApiError as e:
print(f"API call failed: {e.status_code}")
```
-**Run failure** — The API call succeeded, but the task/workflow failed during execution. No exception is raised. Check the `status` field:
+```typescript TypeScript
+import { SkyvernError } from "@skyvern/client";
+
+try {
+ const result = await skyvern.runTask({
+ body: { prompt: "..." },
+ });
+} catch (e) {
+ if (e instanceof SkyvernError) {
+ console.log(`API call failed: ${e.statusCode}`);
+ }
+}
+```
+</CodeGroup>
+
+**Run failure** - The API call succeeded, but the task/workflow failed during execution. No exception is raised. Check the `status` field:
-```python
+<CodeGroup>
+```python Python
result = await client.run_task(
prompt="Fill out the form",
url="https://example.com",
@@ -166,6 +313,25 @@ elif result.status == "completed":
print(f"Success: {result.output}")
```
+```typescript TypeScript
+const result = await skyvern.runTask({
+ body: {
+ prompt: "Fill out the form",
+ url: "https://example.com",
+ },
+ waitForCompletion: true,
+});
+
+if (result.status === "failed") {
+ console.log(`Task failed: ${result.failure_reason}`);
+} else if (result.status === "timed_out") {
+ console.log(`Task exceeded step limit after ${result.step_count} steps`);
+} else if (result.status === "completed") {
+ console.log(`Success: ${JSON.stringify(result.output)}`);
+}
+```
+</CodeGroup>
+
### Run statuses
| Status | Description |
diff --git a/docs/sdk-reference/helpers/download-files.mdx b/docs/sdk-reference/helpers/download-files.mdx
new file mode 100644
index 000000000..a82c79df5
--- /dev/null
+++ b/docs/sdk-reference/helpers/download-files.mdx
@@ -0,0 +1,109 @@
+---
+title: "download_files"
+slug: sdk-reference/helpers/download-files
+---
+
+Navigate to a page and download files.
+
+<Warning>
+Python's `download_files` does **not** support `wait_for_completion` - it returns immediately with a `run_id`. Poll with `get_run()` or use a webhook to know when the download finishes. The TypeScript SDK **does** support `waitForCompletion` on `downloadFiles`.
+</Warning>
+
+<CodeGroup>
+```python Python
+result = await client.download_files(
+ navigation_goal="Download the latest monthly report PDF",
+ url="https://app.example.com/reports",
+)
+
+# Poll for completion
+import asyncio
+while True:
+ run = await client.get_run(result.run_id)
+ if run.status in ("completed", "failed", "terminated", "timed_out", "canceled"):
+ break
+ await asyncio.sleep(5)
+
+for f in run.downloaded_files:
+ print(f.name)
+```
+
+```typescript TypeScript
+const result = await skyvern.downloadFiles({
+ navigation_goal: "Download the latest monthly report PDF",
+ url: "https://app.example.com/reports",
+ waitForCompletion: true,
+});
+
+for (const f of result.downloaded_files ?? []) {
+ console.log(f.name);
+}
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `navigation_goal` | `str` | Yes | - | Natural language description of what to download. |
+| `url` | `str` | No | `None` | Starting page URL. |
+| `browser_session_id` | `str` | No | `None` | Run inside an existing browser session. |
+| `browser_profile_id` | `str` | No | `None` | Load a browser profile. |
+| `proxy_location` | `ProxyLocation` | No | `None` | Route through a geographic proxy. |
+| `webhook_url` | `str` | No | `None` | URL to receive a POST when the download finishes. |
+| `download_suffix` | `str` | No | `None` | Expected file extension to wait for (e.g., `".pdf"`). |
+| `download_timeout` | `float` | No | `None` | Max time to wait for the download in seconds. |
+| `max_steps_per_run` | `int` | No | `None` | Cap AI steps. |
+| `extra_http_headers` | `dict[str, str]` | No | `None` | Additional HTTP headers. |
+| `totp_identifier` | `str` | No | `None` | Identifier for TOTP verification. |
+| `totp_url` | `str` | No | `None` | URL to receive TOTP codes. |
+| `browser_address` | `str` | No | `None` | Connect to a browser at this CDP address. |
+| `max_screenshot_scrolling_times` | `int` | No | `None` | Number of screenshot scrolls. |
+| `waitForCompletion` (TS only) | `boolean` | No | `false` | Block until the download finishes. |
+| `timeout` (TS only) | `number` | No | `1800` | Max wait time in seconds. |
+| `request_options` | `RequestOptions` | No | `None` | Per-request configuration (see below). |
+
+### Returns `WorkflowRunResponse`
+
+The `downloaded_files` field contains the list of files that were downloaded.
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/helpers.mdx b/docs/sdk-reference/helpers/login.mdx
similarity index 50%
rename from docs/sdk-reference/helpers.mdx
rename to docs/sdk-reference/helpers/login.mdx
index 5c98b2d18..558460a46 100644
--- a/docs/sdk-reference/helpers.mdx
+++ b/docs/sdk-reference/helpers/login.mdx
@@ -1,31 +1,18 @@
---
-title: Helper Methods
-subtitle: High-level methods for common automation patterns
-description: Use high-level helper methods in the Skyvern Python SDK for common automation patterns. Covers login(), download_files(), and upload_file() for streamlined authentication, file downloads, and file uploads.
-slug: sdk-reference/helpers
-keywords:
- - login
- - download_files
- - upload_file
- - Bitwarden
- - 1Password
- - Azure Key Vault
- - credential
- - authentication
- - file download
- - file upload
- - workflow
+title: "login"
+slug: sdk-reference/helpers/login
---
These methods wrap common multi-step patterns into single API calls. Under the hood, they create and run specialized workflows.
----
-
-## `login`
+<Note>
+Python uses `snake_case` (e.g., `login`, `download_files`); TypeScript uses `camelCase` (e.g., `login`, `downloadFiles`). Parameter tables show Python names. TypeScript names are the camelCase equivalents.
+</Note>
Automate logging into a website using stored credentials. This creates a login workflow, executes it, and optionally waits for completion.
-```python
+<CodeGroup>
+```python Python
from skyvern.schemas.run_blocks import CredentialType
result = await client.login(
@@ -37,13 +24,24 @@ result = await client.login(
print(result.status)
```
+```typescript TypeScript
+const result = await skyvern.login({
+ credential_type: "skyvern",
+ credential_id: "cred_abc123",
+ url: "https://app.example.com/login",
+ waitForCompletion: true,
+});
+console.log(result.status);
+```
+</CodeGroup>
+
### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
-| `credential_type` | `CredentialType` | Yes | — | How credentials are stored. Options: `skyvern`, `bitwarden`, `onepassword`, `azure_vault`. |
+| `credential_type` | `CredentialType` | Yes | - | How credentials are stored. Options: `skyvern`, `bitwarden`, `onepassword` (`"1password"` in TS), `azure_vault`. |
| `url` | `str` | No | `None` | The login page URL. |
-| `credential_id` | `str` | No | `None` | The Skyvern credential ID (when using `CredentialType.skyvern`). |
+| `credential_id` | `str` | No | `None` | The Skyvern credential ID (when using `skyvern` type). |
| `prompt` | `str` | No | `None` | Additional instructions for the AI during login. |
| `browser_session_id` | `str` | No | `None` | Run login inside an existing browser session. |
| `browser_address` | `str` | No | `None` | Connect to a browser at this CDP address. |
@@ -51,10 +49,12 @@ print(result.status)
| `webhook_url` | `str` | No | `None` | URL to receive a POST when the login finishes. |
| `totp_identifier` | `str` | No | `None` | Identifier for TOTP verification. |
| `totp_url` | `str` | No | `None` | URL to receive TOTP codes. |
-| `wait_for_completion` | `bool` | No | `False` | Block until the login finishes. |
+| `wait_for_completion` (Python) / `waitForCompletion` (TS) | `bool` | No | `False` | Block until the login finishes. |
| `timeout` | `float` | No | `1800` | Max wait time in seconds. |
| `extra_http_headers` | `dict[str, str]` | No | `None` | Additional HTTP headers. |
| `max_screenshot_scrolling_times` | `int` | No | `None` | Number of screenshot scrolls. |
+| `browser_profile_id` | `str` | No | `None` | Load a browser profile into the session. |
+| `request_options` | `RequestOptions` | No | `None` | Per-request configuration (see below). |
**Bitwarden-specific parameters:**
@@ -83,7 +83,8 @@ print(result.status)
### Example: Login then extract data
-```python
+<CodeGroup>
+```python Python
from skyvern.schemas.run_blocks import CredentialType
session = await client.create_browser_session()
@@ -106,67 +107,67 @@ result = await client.run_task(
print(result.output)
```
----
-
-## `download_files`
-
-Navigate to a page and download files. Unlike `run_task` and `run_workflow`, this method does **not** support `wait_for_completion` — it returns immediately with a `run_id`. Poll with `get_run()` or use a webhook to know when the download finishes.
-
-```python
-result = await client.download_files(
- navigation_goal="Download the latest monthly report PDF",
- url="https://app.example.com/reports",
-)
-
-# Poll for completion
-import asyncio
-while True:
- run = await client.get_run(result.run_id)
- if run.status in ("completed", "failed", "terminated", "timed_out", "canceled"):
- break
- await asyncio.sleep(5)
-
-for f in run.downloaded_files:
- print(f.name)
+```typescript TypeScript
+const session = await skyvern.createBrowserSession({});
+
+// Login
+await skyvern.login({
+ credential_type: "skyvern",
+ credential_id: "cred_abc123",
+ url: "https://app.example.com/login",
+ browser_session_id: session.browser_session_id,
+ waitForCompletion: true,
+});
+
+// Now extract data from the authenticated session
+const result = await skyvern.runTask({
+ body: {
+ prompt: "Go to the billing page and extract all invoices",
+ browser_session_id: session.browser_session_id,
+ },
+ waitForCompletion: true,
+});
+console.log(result.output);
```
+</CodeGroup>
-### Parameters
+---
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `navigation_goal` | `str` | Yes | — | Natural language description of what to download. |
-| `url` | `str` | No | `None` | Starting page URL. |
-| `browser_session_id` | `str` | No | `None` | Run inside an existing browser session. |
-| `browser_profile_id` | `str` | No | `None` | Load a browser profile. |
-| `proxy_location` | `ProxyLocation` | No | `None` | Route through a geographic proxy. |
-| `webhook_url` | `str` | No | `None` | URL to receive a POST when the download finishes. |
-| `download_suffix` | `str` | No | `None` | Expected file extension to wait for (e.g., `".pdf"`). |
-| `download_timeout` | `float` | No | `None` | Max time to wait for the download in seconds. |
-| `max_steps_per_run` | `int` | No | `None` | Cap AI steps. |
-| `extra_http_headers` | `dict[str, str]` | No | `None` | Additional HTTP headers. |
+### Request options
-### Returns `WorkflowRunResponse`
-The `downloaded_files` field contains the list of files that were downloaded.
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
----
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
-## `upload_file`
-
-Upload a file to Skyvern's storage. Returns a presigned URL and S3 URI you can reference in tasks and workflows.
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
-```python
-with open("data.csv", "rb") as f:
- upload = await client.upload_file(file=f)
- print(upload.s3uri) # s3://skyvern-uploads/...
- print(upload.presigned_url) # https://...signed download URL
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
```
+</CodeGroup>
-### Parameters
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `file` | `File` | Yes | The file to upload. Accepts file objects, byte streams, or paths. |
-| `file_storage_type` | `FileStorageType` | No | Storage backend type. |
-### Returns `UploadFileResponse`
+---
diff --git a/docs/sdk-reference/helpers/upload-file.mdx b/docs/sdk-reference/helpers/upload-file.mdx
new file mode 100644
index 000000000..c72e21b30
--- /dev/null
+++ b/docs/sdk-reference/helpers/upload-file.mdx
@@ -0,0 +1,80 @@
+---
+title: "upload_file"
+slug: sdk-reference/helpers/upload-file
+---
+
+Upload a file to Skyvern's storage. Returns a presigned URL and S3 URI you can reference in tasks and workflows.
+
+<CodeGroup>
+```python Python
+with open("data.csv", "rb") as f:
+ upload = await client.upload_file(file=f)
+ print(upload.s3uri) # s3://skyvern-uploads/...
+ print(upload.presigned_url) # https://...signed download URL
+```
+
+```typescript TypeScript
+import fs from "fs";
+
+const upload = await skyvern.uploadFile({
+ file: fs.createReadStream("data.csv"),
+});
+console.log(upload.s3_uri); // s3://skyvern-uploads/...
+console.log(upload.presigned_url); // https://...signed download URL
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `file` | `File` (Python) / `File \| ReadStream \| Blob` (TS) | Yes | The file to upload. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+### Returns `UploadFileResponse`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `s3uri` (Python) / `s3_uri` (TS) | `str` | S3 URI for the uploaded file. |
+| `presigned_url` | `str` | Pre-signed download URL. |
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/overview.mdx b/docs/sdk-reference/overview.mdx
index 402fdb449..f8a2022bc 100644
--- a/docs/sdk-reference/overview.mdx
+++ b/docs/sdk-reference/overview.mdx
@@ -1,7 +1,6 @@
---
-title: Python SDK
-subtitle: Install, authenticate, and configure the Skyvern Python client
-description: Install the Skyvern Python SDK, authenticate with your API key, and start running browser automation tasks and workflows programmatically.
+title: Overview
+subtitle: Install, authenticate, and configure the Skyvern client
slug: sdk-reference/overview
keywords:
- install
@@ -16,27 +15,40 @@ keywords:
- request options
---
-The `skyvern` package wraps the Skyvern REST API in a typed, async Python client.
+The Skyvern SDK wraps the REST API in a typed client with built-in browser automation via Playwright.
-```bash
+## Install
+
+<CodeGroup>
+```bash Python
+# Requires Python 3.11+
pip install skyvern
```
+```bash TypeScript
+# Requires Node.js 18+ (also compatible with Bun, Deno, and Cloudflare Workers)
+npm install @skyvern/client
+```
+</CodeGroup>
+
<Note>
-Requires Python 3.11+. If you hit version errors, use `pipx install skyvern` to install in an isolated environment.
+If you hit Python version errors, use `pipx install skyvern` to install in an isolated environment.
</Note>
---
## Initialize the client
-The `Skyvern` class is async — all methods are coroutines. Wrap calls in an `async` function and use `asyncio.run()` as the entry point:
+Create a `Skyvern` instance with your API key. All methods are async.
-```python
+<CodeGroup>
+```python Python
import asyncio
from skyvern import Skyvern
async def main():
+ # All methods are coroutines - wrap in async and use asyncio.run()
+ # If inside FastAPI/Django ASGI, await directly without asyncio.run()
client = Skyvern(api_key="YOUR_API_KEY")
result = await client.run_task(
@@ -49,55 +61,95 @@ async def main():
asyncio.run(main())
```
-If you're inside a framework that already runs an event loop (FastAPI, Django ASGI), `await` directly without `asyncio.run()`.
+```typescript TypeScript
+import { Skyvern } from "@skyvern/client";
+
+// All methods return promises
+const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
+
+const result = await skyvern.runTask({
+ body: {
+ prompt: "Get the title of the top post on Hacker News",
+ url: "https://news.ycombinator.com",
+ },
+ waitForCompletion: true,
+});
+console.log(result.output);
+```
+</CodeGroup>
### Constructor parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
-| `api_key` | `str` | — | **Required.** Your Skyvern API key. Get one at [app.skyvern.com/settings](https://app.skyvern.com/settings/). |
-| `environment` | `SkyvernEnvironment` | `CLOUD` | Target environment. Options: `CLOUD`, `STAGING`, `LOCAL`. |
-| `base_url` | `str \| None` | `None` | Override the API base URL. Use this for self-hosted deployments. |
-| `timeout` | `float \| None` | `None` | HTTP request timeout in seconds. |
+| `api_key` / `apiKey` | `str` / `string` | - | **Required.** Your Skyvern API key. Get one at [app.skyvern.com/settings](https://app.skyvern.com/settings/). |
+| `environment` | `SkyvernEnvironment` | `CLOUD` / `Cloud` | Target environment. See [Environments](#environments). |
+| `base_url` / `baseUrl` | `str` / `string` | `None` | Override the API base URL for self-hosted deployments. |
+| `timeout` / `timeoutInSeconds` | `float` / `number` | `None` / `60` | HTTP request timeout in seconds. |
+| `max_retries` / `maxRetries` | `int` / `number` | `None` / `2` | Number of times to retry failed requests. |
+| `headers` | `dict` / `Record<string, string>` | `None` | Additional headers included with every request. |
+
+<Accordion title="Python-only constructor options">
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
| `follow_redirects` | `bool` | `True` | Whether to follow HTTP redirects. |
-| `httpx_client` | `AsyncClient \| None` | `None` | Provide your own httpx client for custom TLS, proxying, or connection pooling. |
+| `httpx_client` | `httpx.AsyncClient` | `None` | Provide your own httpx client for custom TLS, proxying, or connection pooling. |
+
+</Accordion>
---
## Environments
-The SDK ships with three built-in environment URLs:
+Three built-in environment URLs:
-```python
+<CodeGroup>
+```python Python
from skyvern.client import SkyvernEnvironment
```
+```typescript TypeScript
+import { SkyvernEnvironment } from "@skyvern/client";
+```
+</CodeGroup>
+
| Environment | URL | When to use |
|-------------|-----|-------------|
-| `SkyvernEnvironment.CLOUD` | `https://api.skyvern.com` | Skyvern Cloud (default) |
-| `SkyvernEnvironment.STAGING` | `https://api.staging.skyvern.com` | Staging environment for testing |
-| `SkyvernEnvironment.LOCAL` | `http://localhost:8000` | Local server started with `skyvern run server` |
+| `CLOUD` / `Cloud` | `https://api.skyvern.com` | Skyvern Cloud (default) |
+| `STAGING` / `Staging` | `https://api-staging.skyvern.com` | Staging environment |
+| `LOCAL` / `Local` | `http://localhost:8000` | Local server started with `skyvern run server` |
-For a self-hosted instance at a custom URL, pass `base_url` instead:
+For a self-hosted instance at a custom URL:
-```python
+<CodeGroup>
+```python Python
client = Skyvern(
api_key="YOUR_API_KEY",
base_url="https://skyvern.your-company.com",
)
```
+```typescript TypeScript
+const skyvern = new Skyvern({
+ apiKey: "YOUR_API_KEY",
+ baseUrl: "https://skyvern.your-company.com",
+});
+```
+</CodeGroup>
+
---
## Local mode
-Run Skyvern entirely on your machine — no cloud, no network calls. `Skyvern.local()` reads your `.env` file, boots the engine in-process, and connects the client to it.
+Run Skyvern entirely on your machine - no cloud, no network calls. `Skyvern.local()` reads your `.env` file, boots the engine in-process, and connects the client to it.
**Prerequisite:** Run `skyvern quickstart` once to create the `.env` file with your database connection and LLM API keys.
```python
from skyvern import Skyvern
+# Python only. TypeScript requires a running Skyvern server
client = Skyvern.local()
result = await client.run_task(
@@ -107,7 +159,7 @@ result = await client.run_task(
)
```
-If you configured headful mode during `skyvern quickstart`, a Chromium window opens on your machine so you can watch the AI work.
+If you configured headful mode during `skyvern quickstart`, a Chromium window opens so you can watch the AI work.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
@@ -116,11 +168,12 @@ If you configured headful mode during `skyvern quickstart`, a Chromium window op
---
-## `wait_for_completion`
+## Waiting for completion
-By default, `run_task` and `run_workflow` return immediately after the run is queued — you get a `run_id` and need to poll `get_run()` yourself. Pass `wait_for_completion=True` to have the SDK poll automatically until the run reaches a terminal state (`completed`, `failed`, `terminated`, `timed_out`, or `canceled`):
+By default, task and workflow runs return immediately after queuing. You get a run ID and need to poll for results yourself. Pass `wait_for_completion` to have the SDK poll automatically until the run reaches a terminal state (`completed`, `failed`, `terminated`, `timed_out`, or `canceled`):
-```python
+<CodeGroup>
+```python Python
# Returns only after the task finishes (up to 30 min by default)
result = await client.run_task(
prompt="Fill out the contact form",
@@ -129,7 +182,7 @@ result = await client.run_task(
timeout=600, # give up after 10 minutes
)
-# Without wait_for_completion — returns immediately
+# Without wait_for_completion -- returns immediately
task = await client.run_task(
prompt="Fill out the contact form",
url="https://example.com/contact",
@@ -137,20 +190,43 @@ task = await client.run_task(
print(task.run_id) # poll with client.get_run(task.run_id)
```
+```typescript TypeScript
+// Returns only after the task finishes (up to 30 min by default)
+const result = await skyvern.runTask({
+ body: {
+ prompt: "Fill out the contact form",
+ url: "https://example.com/contact",
+ },
+ waitForCompletion: true,
+ timeout: 600, // give up after 10 minutes
+});
+
+// Without waitForCompletion -- returns immediately
+const task = await skyvern.runTask({
+ body: {
+ prompt: "Fill out the contact form",
+ url: "https://example.com/contact",
+ },
+});
+console.log(task.run_id); // poll with skyvern.getRun(task.run_id)
+```
+</CodeGroup>
+
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
-| `wait_for_completion` | `bool` | `False` | Poll until the run finishes. |
-| `timeout` | `float` | `1800` | Maximum wait time in seconds. Raises Python's `TimeoutError` if exceeded. |
+| `wait_for_completion` / `waitForCompletion` | `bool` / `boolean` | `false` | Poll until the run finishes. |
+| `timeout` | `float` / `number` | `1800` | Maximum wait time in seconds. |
-Supported on `run_task`, `run_workflow`, and `login`.
+Supported on task runs, workflow runs, and login. In TypeScript, also supported on file downloads.
---
## Request options
-Every method accepts an optional `request_options` parameter for per-request overrides of timeout, retries, and headers:
+Every method accepts per-request overrides for timeout, retries, and headers:
-```python
+<CodeGroup>
+```python Python
from skyvern.client.core import RequestOptions
result = await client.run_task(
@@ -164,6 +240,34 @@ result = await client.run_task(
)
```
+```typescript TypeScript
+// Pass as second argument to any method
+const result = await skyvern.runTask(
+ {
+ body: {
+ prompt: "Extract data",
+ url: "https://example.com",
+ },
+ },
+ {
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+ },
+);
+```
+</CodeGroup>
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `timeout_in_seconds` / `timeoutInSeconds` | `int` / `number` | HTTP timeout for this request. |
+| `max_retries` / `maxRetries` | `int` / `number` | Retry count for this request. |
+| `additional_headers` / `headers` | `dict` / `Record<string, string>` | Extra headers for this request. |
+| `additional_query_parameters` | `dict` | Extra query parameters (Python only). |
+| `additional_body_parameters` | `dict` | Extra body parameters (Python only). |
+| `abortSignal` | `AbortSignal` | Signal to abort the request (TypeScript only). |
+| `apiKey` | `string` | Override the API key for this request (TypeScript only). |
+
These override the client-level defaults for that single call only.
---
@@ -171,27 +275,27 @@ These override the client-level defaults for that single call only.
## Next steps
<CardGroup cols={2}>
+ <Card
+ title="Browser Automation"
+ icon="robot"
+ href="/sdk-reference/browser-automation/launch-cloud-browser"
+ >
+ Control browsers with Playwright + AI
+ </Card>
<Card
title="Tasks"
icon="play"
- href="/sdk-reference/tasks"
+ href="/sdk-reference/tasks/run-task"
>
Run browser automations with `run_task`
</Card>
<Card
title="Workflows"
icon="diagram-project"
- href="/sdk-reference/workflows"
+ href="/sdk-reference/workflows/run-workflow"
>
Create and run multi-step automations
</Card>
- <Card
- title="Browser Sessions"
- icon="browser"
- href="/sdk-reference/browser-sessions"
- >
- Maintain live browser state between calls
- </Card>
<Card
title="Error Handling"
icon="triangle-exclamation"
diff --git a/docs/sdk-reference/tasks.mdx b/docs/sdk-reference/tasks.mdx
deleted file mode 100644
index 847327c85..000000000
--- a/docs/sdk-reference/tasks.mdx
+++ /dev/null
@@ -1,314 +0,0 @@
----
-title: Tasks
-subtitle: Run single browser automations with natural language
-description: Create, run, and monitor browser automation tasks using the Skyvern Python SDK. Covers run_task(), get_run(), cancel_run(), get_run_timeline(), get_run_artifacts(), and task configuration options.
-slug: sdk-reference/tasks
-keywords:
- - run_task
- - get_run
- - cancel_run
- - get_run_timeline
- - get_run_artifacts
- - retry_run_webhook
- - data extraction
- - polling
- - webhook
- - max_steps
- - engine
- - proxy
- - TOTP
- - 2FA
- - artifact
----
-
-A task is a single browser automation. You describe what you want in natural language — Skyvern opens a browser, navigates to the URL, and executes the instructions with AI.
-
-For when to use tasks vs workflows, see [Run a Task](/running-automations/run-a-task).
-
----
-
-## `run_task`
-
-Start a browser automation. Skyvern opens a cloud browser, navigates to the URL, and executes your prompt with AI.
-
-```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)
-```
-
-### Parameters
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `prompt` | `str` | Yes | — | Natural language instructions for what the AI should do. |
-| `url` | `str` | No | `None` | Starting page URL. If omitted, the AI navigates from a blank page. |
-| `engine` | `RunEngine` | No | `skyvern_v2` | AI engine. Options: `skyvern_v2`, `skyvern_v1`, `openai_cua`, `anthropic_cua`, `ui_tars`. |
-| `wait_for_completion` | `bool` | No | `False` | Block until the run finishes. |
-| `timeout` | `float` | No | `1800` | Max wait time in seconds when `wait_for_completion=True`. |
-| `max_steps` | `int` | No | `None` | Cap the number of AI steps to limit cost. Run terminates with `timed_out` if hit. |
-| `data_extraction_schema` | `dict \| str` | No | `None` | JSON schema or Pydantic model name constraining the output shape. |
-| `proxy_location` | `ProxyLocation` | No | `None` | Route the browser through a geographic proxy. |
-| `browser_session_id` | `str` | No | `None` | Run inside an existing [browser session](/optimization/browser-sessions). |
-| `publish_workflow` | `bool` | No | `False` | Save the generated code as a reusable workflow. Only works with `skyvern_v2`. |
-| `webhook_url` | `str` | No | `None` | URL to receive a POST when the run finishes. |
-| `error_code_mapping` | `dict[str, str]` | No | `None` | Map custom error codes to failure reasons. |
-| `totp_identifier` | `str` | No | `None` | Identifier for TOTP verification. |
-| `totp_url` | `str` | No | `None` | URL to receive TOTP codes. |
-| `title` | `str` | No | `None` | Display name for this run in the dashboard. |
-| `model` | `dict` | No | `None` | Override the output model definition. |
-| `user_agent` | `str` | No | `None` | Custom User-Agent header for the browser. |
-| `extra_http_headers` | `dict[str, str]` | No | `None` | Additional HTTP headers injected into every browser request. |
-| `include_action_history_in_verification` | `bool` | No | `None` | Include action history when verifying task completion. |
-| `max_screenshot_scrolls` | `int` | No | `None` | Number of scrolls for post-action screenshots. Useful for lazy-loaded content. |
-| `browser_address` | `str` | No | `None` | Connect to a browser at this CDP address instead of spinning up a new one. |
-
-### Returns `TaskRunResponse`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `run_id` | `str` | Unique identifier. Starts with `tsk_` for task runs. |
-| `status` | `str` | `created`, `queued`, `running`, `completed`, `failed`, `terminated`, `timed_out`, or `canceled`. |
-| `output` | `dict \| None` | Extracted data from the run. Shape depends on your prompt or `data_extraction_schema`. |
-| `downloaded_files` | `list[FileInfo] \| None` | Files downloaded during the run. |
-| `recording_url` | `str \| None` | URL to the session recording video. |
-| `screenshot_urls` | `list[str] \| None` | Final screenshots (most recent first). |
-| `failure_reason` | `str \| None` | Error description if the run failed. |
-| `app_url` | `str \| None` | Link to view this run in the Cloud UI. |
-| `step_count` | `int \| None` | Number of AI steps taken. |
-| `script_run` | `ScriptRunResponse \| None` | Code execution result if the run used generated code. |
-| `created_at` | `datetime` | When the run was created. |
-| `finished_at` | `datetime \| None` | When the run finished. |
-
-### Examples
-
-**Extract structured data:**
-
-```python
-result = await client.run_task(
- prompt="Extract the name, price, and rating of the top 3 products",
- url="https://example.com/products",
- data_extraction_schema={
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "name": {"type": "string"},
- "price": {"type": "string"},
- "rating": {"type": "number"},
- },
- },
- },
- wait_for_completion=True,
-)
-print(result.output)
-# [{"name": "Widget A", "price": "$29.99", "rating": 4.5}, ...]
-```
-
-**Run inside an existing browser session:**
-
-```python
-session = await client.create_browser_session()
-
-result = await client.run_task(
- prompt="Log in and download the latest invoice",
- url="https://app.example.com/login",
- browser_session_id=session.browser_session_id,
- wait_for_completion=True,
-)
-```
-
-**Limit cost with max_steps:**
-
-```python
-result = await client.run_task(
- prompt="Fill out the contact form",
- url="https://example.com/contact",
- max_steps=10,
- wait_for_completion=True,
-)
-```
-
-**Use a lighter engine:**
-
-```python
-from skyvern.schemas.runs import RunEngine
-
-result = await client.run_task(
- prompt="Get the page title",
- url="https://example.com",
- engine=RunEngine.skyvern_v1,
- wait_for_completion=True,
-)
-```
-
-**Publish as a reusable workflow:**
-
-```python
-result = await client.run_task(
- prompt="Fill out the contact form with the provided data",
- url="https://example.com/contact",
- publish_workflow=True,
- wait_for_completion=True,
-)
-# The generated workflow is saved and can be re-triggered via run_workflow
-```
-
----
-
-## `get_run`
-
-Get the current status and results of any run (task or workflow).
-
-```python
-run = await client.get_run("tsk_v2_486305187432193504")
-print(run.status, run.output)
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `run_id` | `str` | Yes | The run ID returned by `run_task` or `run_workflow`. |
-
-### Returns `GetRunResponse`
-
-A discriminated union based on `run_type`. All variants share the same core fields as `TaskRunResponse` above, plus a `run_type` field (`task_v1`, `task_v2`, `openai_cua`, `anthropic_cua`, `ui_tars`, `workflow_run`).
-
-Workflow run responses additionally include `run_with` and `ai_fallback` fields.
-
----
-
-## `cancel_run`
-
-Cancel a running or queued run.
-
-```python
-await client.cancel_run("tsk_v2_486305187432193504")
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `run_id` | `str` | Yes | The run ID to cancel. |
-
-The run transitions to `canceled` status. If the run has already finished, this is a no-op.
-
----
-
-## `get_run_timeline`
-
-Get the step-by-step timeline of a run. Each entry represents one AI action with screenshots and reasoning.
-
-```python
-timeline = await client.get_run_timeline("tsk_v2_486305187432193504")
-for step in timeline:
- print(f"Step {step.order}: {step.type} — {step.status}")
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `run_id` | `str` | Yes | The run ID. |
-
-### Returns `list[WorkflowRunTimeline]`
-
-Each timeline entry contains step details including type, status, order, and associated artifacts.
-
----
-
-## `get_run_artifacts`
-
-Get all artifacts (screenshots, recordings, generated code, etc.) for a run.
-
-```python
-artifacts = await client.get_run_artifacts("tsk_v2_486305187432193504")
-for artifact in artifacts:
- print(f"{artifact.artifact_type}: {artifact.uri}")
-```
-
-Filter by type to get specific artifacts:
-
-```python
-# Get only the generated Playwright scripts
-scripts = await client.get_run_artifacts(
- "tsk_v2_486305187432193504",
- artifact_type=["script_file"],
-)
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `run_id` | `str` | Yes | The run ID. |
-| `artifact_type` | `ArtifactType \| list[ArtifactType]` | No | Filter by artifact type. |
-
-### Returns `list[Artifact]`
-
----
-
-## `get_artifact`
-
-Get a single artifact by ID.
-
-```python
-artifact = await client.get_artifact("art_486305187432193504")
-print(artifact.uri)
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `artifact_id` | `str` | Yes | The artifact ID. |
-
-### Returns `Artifact`
-
----
-
-## `retry_run_webhook`
-
-Re-send the webhook notification for a completed run. Useful if your webhook endpoint was down when the run finished.
-
-```python
-await client.retry_run_webhook("tsk_v2_486305187432193504")
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `run_id` | `str` | Yes | The run ID. |
-
----
-
-## Polling pattern
-
-If you don't use `wait_for_completion`, poll `get_run` manually:
-
-```python
-import asyncio
-
-task = await client.run_task(
- prompt="Extract product data",
- url="https://example.com/products",
-)
-
-while True:
- run = await client.get_run(task.run_id)
- if run.status in ("completed", "failed", "terminated", "timed_out", "canceled"):
- break
- await asyncio.sleep(5)
-
-print(run.output)
-```
-
-<Tip>
-For production, prefer `wait_for_completion=True` or [webhooks](/going-to-production/webhooks) over manual polling.
-</Tip>
diff --git a/docs/sdk-reference/tasks/cancel-run.mdx b/docs/sdk-reference/tasks/cancel-run.mdx
new file mode 100644
index 000000000..0e562f25d
--- /dev/null
+++ b/docs/sdk-reference/tasks/cancel-run.mdx
@@ -0,0 +1,66 @@
+---
+title: "cancel_run"
+slug: sdk-reference/tasks/cancel-run
+---
+
+Cancel a running or queued run.
+
+<CodeGroup>
+```python Python
+await client.cancel_run("tsk_v2_486305187432193504")
+```
+
+```typescript TypeScript
+await skyvern.cancelRun("tsk_v2_486305187432193504");
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `run_id` | `str` | Yes | The run ID to cancel. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+The run transitions to `canceled` status. If the run has already finished, this is a no-op.
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/tasks/get-artifact.mdx b/docs/sdk-reference/tasks/get-artifact.mdx
new file mode 100644
index 000000000..43decb7c1
--- /dev/null
+++ b/docs/sdk-reference/tasks/get-artifact.mdx
@@ -0,0 +1,68 @@
+---
+title: "get_artifact"
+slug: sdk-reference/tasks/get-artifact
+---
+
+Get a single artifact by ID.
+
+<CodeGroup>
+```python Python
+artifact = await client.get_artifact("art_abc123")
+print(artifact.uri)
+```
+
+```typescript TypeScript
+const artifact = await skyvern.getArtifact("art_abc123");
+console.log(artifact.uri);
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `artifact_id` | `str` | Yes | The artifact ID. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+### Returns `Artifact`
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/tasks/get-run-artifacts.mdx b/docs/sdk-reference/tasks/get-run-artifacts.mdx
new file mode 100644
index 000000000..186ec848b
--- /dev/null
+++ b/docs/sdk-reference/tasks/get-run-artifacts.mdx
@@ -0,0 +1,91 @@
+---
+title: "get_run_artifacts"
+slug: sdk-reference/tasks/get-run-artifacts
+---
+
+Get all artifacts (screenshots, recordings, generated code, etc.) for a run.
+
+<CodeGroup>
+```python Python
+artifacts = await client.get_run_artifacts("tsk_v2_486305187432193504")
+for artifact in artifacts:
+ print(f"{artifact.artifact_type}: {artifact.uri}")
+```
+
+```typescript TypeScript
+const artifacts = await skyvern.getRunArtifacts("tsk_v2_486305187432193504");
+for (const artifact of artifacts) {
+ console.log(`${artifact.artifact_type}: ${artifact.uri}`);
+}
+```
+</CodeGroup>
+
+Filter by type to get specific artifacts:
+
+<CodeGroup>
+```python Python
+# Get only the generated Playwright scripts
+scripts = await client.get_run_artifacts(
+ "tsk_v2_486305187432193504",
+ artifact_type=["script_file"],
+)
+```
+
+```typescript TypeScript
+const scripts = await skyvern.getRunArtifacts(
+ "tsk_v2_486305187432193504",
+ { artifact_type: ["script_file"] },
+);
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `run_id` | `str` | Yes | The run ID. |
+| `artifact_type` | `ArtifactType \| list[ArtifactType]` | No | Filter by artifact type. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+### Returns `list[Artifact]`
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/tasks/get-run-timeline.mdx b/docs/sdk-reference/tasks/get-run-timeline.mdx
new file mode 100644
index 000000000..7c9ac6f49
--- /dev/null
+++ b/docs/sdk-reference/tasks/get-run-timeline.mdx
@@ -0,0 +1,73 @@
+---
+title: "get_run_timeline"
+slug: sdk-reference/tasks/get-run-timeline
+---
+
+Get the step-by-step timeline of a run. Each entry represents one AI action with screenshots and reasoning.
+
+<CodeGroup>
+```python Python
+timeline = await client.get_run_timeline("tsk_v2_486305187432193504")
+for step in timeline:
+ print(f"Step {step.order}: {step.type} - {step.status}")
+```
+
+```typescript TypeScript
+const timeline = await skyvern.getRunTimeline("tsk_v2_486305187432193504");
+for (const step of timeline) {
+ console.log(`Step ${step.order}: ${step.type} - ${step.status}`);
+}
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `run_id` | `str` | Yes | The run ID. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+### Returns `list[WorkflowRunTimeline]`
+
+Each timeline entry contains step details including type, status, order, and associated artifacts.
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/tasks/get-run.mdx b/docs/sdk-reference/tasks/get-run.mdx
new file mode 100644
index 000000000..61c50850c
--- /dev/null
+++ b/docs/sdk-reference/tasks/get-run.mdx
@@ -0,0 +1,72 @@
+---
+title: "get_run"
+slug: sdk-reference/tasks/get-run
+---
+
+Get the current status and results of any run (task or workflow).
+
+<CodeGroup>
+```python Python
+run = await client.get_run("tsk_v2_486305187432193504")
+print(run.status, run.output)
+```
+
+```typescript TypeScript
+const run = await skyvern.getRun("tsk_v2_486305187432193504");
+console.log(run.status, run.output);
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `run_id` | `str` | Yes | The run ID returned by `run_task` or `run_workflow`. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+### Returns `GetRunResponse`
+
+A discriminated union based on `run_type`. All variants share the same core fields as `TaskRunResponse` above, plus a `run_type` field (`task_v1`, `task_v2`, `openai_cua`, `anthropic_cua`, `ui_tars`, `workflow_run`).
+
+Workflow run responses additionally include `run_with` and `ai_fallback` fields.
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/tasks/get-runs-v2.mdx b/docs/sdk-reference/tasks/get-runs-v2.mdx
new file mode 100644
index 000000000..ffc4f4490
--- /dev/null
+++ b/docs/sdk-reference/tasks/get-runs-v2.mdx
@@ -0,0 +1,74 @@
+---
+title: "get_runs_v2"
+slug: sdk-reference/tasks/get-runs-v2
+---
+
+List all runs across tasks and workflows for the current organization, with filtering and pagination.
+
+<CodeGroup>
+```python Python
+runs = await client.get_runs_v2(page=1, page_size=20, status="completed")
+for run in runs:
+ print(run.run_id, run.status)
+```
+
+```typescript TypeScript
+const runs = await skyvern.getRunsV2({ page: 1, page_size: 20, status: "completed" });
+for (const run of runs) {
+ console.log(run.run_id, run.status);
+}
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `page` | `int` | No | Page number (1-indexed). |
+| `page_size` | `int` | No | Results per page. |
+| `status` | `RunStatus \| list[RunStatus]` | No | Filter by run status. |
+| `search_key` | `str` | No | Case-insensitive substring search (min 3 chars). |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+### Returns `list[TaskRunListItem]`
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/tasks/retry-run-webhook.mdx b/docs/sdk-reference/tasks/retry-run-webhook.mdx
new file mode 100644
index 000000000..44303899d
--- /dev/null
+++ b/docs/sdk-reference/tasks/retry-run-webhook.mdx
@@ -0,0 +1,65 @@
+---
+title: "retry_run_webhook"
+slug: sdk-reference/tasks/retry-run-webhook
+---
+
+Re-send the webhook notification for a completed run. Useful if your webhook endpoint was down when the run finished.
+
+<CodeGroup>
+```python Python
+await client.retry_run_webhook("tsk_v2_486305187432193504")
+```
+
+```typescript TypeScript
+await skyvern.retryRunWebhook("tsk_v2_486305187432193504");
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `run_id` | `str` | Yes | The run ID. |
+| `webhook_url` | `str` | No | Override the stored webhook URL for this retry. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/tasks/run-task.mdx b/docs/sdk-reference/tasks/run-task.mdx
new file mode 100644
index 000000000..b8a5dd156
--- /dev/null
+++ b/docs/sdk-reference/tasks/run-task.mdx
@@ -0,0 +1,379 @@
+---
+title: "run_task"
+slug: sdk-reference/tasks/run-task
+---
+
+A task is a single browser automation. You describe what you want in natural language. Skyvern opens a browser, navigates to the URL, and executes the instructions with AI.
+
+For when to use tasks vs workflows, see [Run a Task](/running-automations/run-a-task).
+
+<Note>
+Python uses `snake_case` (e.g., `run_task`, `wait_for_completion`); TypeScript uses `camelCase` (e.g., `runTask`, `waitForCompletion`) and wraps request params in a `body` object. Parameter tables show Python names. TypeScript names are the camelCase equivalents.
+</Note>
+
+---
+
+Start a browser automation. Skyvern opens a cloud browser, navigates to the URL, and executes your prompt with AI.
+
+<CodeGroup>
+```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)
+```
+
+```typescript TypeScript
+const result = await skyvern.runTask({
+ body: {
+ prompt: "Get the title of the top post",
+ url: "https://news.ycombinator.com",
+ },
+ waitForCompletion: true,
+});
+console.log(result.output);
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `prompt` | `str` | Yes | - | Natural language instructions for what the AI should do. |
+| `url` | `str` | No | `None` | Starting page URL. If omitted, the AI navigates from a blank page. |
+| `engine` | `RunEngine` | No | `skyvern_v2` | AI engine. Options: `skyvern_v2`, `skyvern_v1`, `openai_cua`, `anthropic_cua`, `ui_tars`. |
+| `wait_for_completion` | `bool` | No | `False` | Block until the run finishes. |
+| `timeout` | `float` | No | `1800` | Max wait time in seconds when `wait_for_completion=True`. |
+| `max_steps` | `int` | No | `None` | Cap the number of AI steps to limit cost. Run terminates with `timed_out` if hit. |
+| `data_extraction_schema` | `dict \| str` | No | `None` | JSON schema or Pydantic model name constraining the output shape. |
+| `proxy_location` | `ProxyLocation` | No | `None` | Route the browser through a geographic proxy. |
+| `browser_session_id` | `str` | No | `None` | Run inside an existing [browser session](/optimization/browser-sessions). |
+| `publish_workflow` | `bool` | No | `False` | Save the generated code as a reusable workflow. Only works with `skyvern_v2`. |
+| `webhook_url` | `str` | No | `None` | URL to receive a POST when the run finishes. |
+| `error_code_mapping` | `dict[str, str]` | No | `None` | Map custom error codes to failure reasons. |
+| `totp_identifier` | `str` | No | `None` | Identifier for TOTP verification. |
+| `totp_url` | `str` | No | `None` | URL to receive TOTP codes. |
+| `title` | `str` | No | `None` | Display name for this run in the dashboard. |
+| `model` | `dict` | No | `None` | Override the output model definition. |
+| `user_agent` | `str` | No | `None` | Custom User-Agent header for the browser. |
+| `extra_http_headers` | `dict[str, str]` | No | `None` | Additional HTTP headers injected into every browser request. |
+| `include_action_history_in_verification` | `bool` | No | `None` | Include action history when verifying task completion. |
+| `max_screenshot_scrolls` | `int` | No | `None` | Number of scrolls for post-action screenshots. Useful for lazy-loaded content. |
+| `browser_address` | `str` | No | `None` | Connect to a browser at this CDP address instead of spinning up a new one. |
+| `run_with` | `str` | No | `None` | Force execution mode: `"code"` (use cached Playwright code) or `"agent"` (use AI). |
+| `request_options` | `RequestOptions` | No | - | Per-request configuration (see below). |
+
+### Returns `TaskRunResponse`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `run_id` | `str` | Unique identifier. Starts with `tsk_` for task runs. |
+| `status` | `str` | `created`, `queued`, `running`, `completed`, `failed`, `terminated`, `timed_out`, or `canceled`. |
+| `output` | `dict \| None` | Extracted data from the run. Shape depends on your prompt or `data_extraction_schema`. |
+| `downloaded_files` | `list[FileInfo] \| None` | Files downloaded during the run. |
+| `recording_url` | `str \| None` | URL to the session recording video. |
+| `screenshot_urls` | `list[str] \| None` | Final screenshots (most recent first). |
+| `failure_reason` | `str \| None` | Error description if the run failed. |
+| `app_url` | `str \| None` | Link to view this run in the Cloud UI. |
+| `step_count` | `int \| None` | Number of AI steps taken. |
+| `script_run` | `ScriptRunResponse \| None` | Code execution result if the run used generated code. |
+| `created_at` | `datetime` | When the run was created. |
+| `finished_at` | `datetime \| None` | When the run finished. |
+
+### Examples
+
+**Extract structured data:**
+
+<CodeGroup>
+```python Python
+result = await client.run_task(
+ prompt="Extract the name, price, and rating of the top 3 products",
+ url="https://example.com/products",
+ data_extraction_schema={
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "name": {"type": "string"},
+ "price": {"type": "string"},
+ "rating": {"type": "number"},
+ },
+ },
+ },
+ wait_for_completion=True,
+)
+print(result.output)
+# [{"name": "Widget A", "price": "$29.99", "rating": 4.5}, ...]
+```
+
+```typescript TypeScript
+const result = await skyvern.runTask({
+ body: {
+ prompt: "Extract the name, price, and rating of the top 3 products",
+ url: "https://example.com/products",
+ data_extraction_schema: {
+ type: "array",
+ items: {
+ type: "object",
+ properties: {
+ name: { type: "string" },
+ price: { type: "string" },
+ rating: { type: "number" },
+ },
+ },
+ },
+ },
+ waitForCompletion: true,
+});
+console.log(result.output);
+// [{ name: "Widget A", price: "$29.99", rating: 4.5 }, ...]
+```
+</CodeGroup>
+
+**Run inside an existing browser session:**
+
+<CodeGroup>
+```python Python
+session = await client.create_browser_session()
+
+result = await client.run_task(
+ prompt="Log in and download the latest invoice",
+ url="https://app.example.com/login",
+ browser_session_id=session.browser_session_id,
+ wait_for_completion=True,
+)
+```
+
+```typescript TypeScript
+const session = await skyvern.createBrowserSession({});
+
+const result = await skyvern.runTask({
+ body: {
+ prompt: "Log in and download the latest invoice",
+ url: "https://app.example.com/login",
+ browser_session_id: session.browser_session_id,
+ },
+ waitForCompletion: true,
+});
+```
+</CodeGroup>
+
+**Limit cost with max_steps:**
+
+<CodeGroup>
+```python Python
+result = await client.run_task(
+ prompt="Fill out the contact form",
+ url="https://example.com/contact",
+ max_steps=10,
+ wait_for_completion=True,
+)
+```
+
+```typescript TypeScript
+const result = await skyvern.runTask({
+ body: {
+ prompt: "Fill out the contact form",
+ url: "https://example.com/contact",
+ max_steps: 10,
+ },
+ waitForCompletion: true,
+});
+```
+</CodeGroup>
+
+**Use a lighter engine:**
+
+<CodeGroup>
+```python Python
+from skyvern.schemas.runs import RunEngine
+
+result = await client.run_task(
+ prompt="Get the page title",
+ url="https://example.com",
+ engine=RunEngine.skyvern_v1,
+ wait_for_completion=True,
+)
+```
+
+```typescript TypeScript
+const result = await skyvern.runTask({
+ body: {
+ prompt: "Get the page title",
+ url: "https://example.com",
+ engine: "skyvern_v1",
+ },
+ waitForCompletion: true,
+});
+```
+</CodeGroup>
+
+**Publish as a reusable workflow:**
+
+<CodeGroup>
+```python Python
+result = await client.run_task(
+ prompt="Fill out the contact form with the provided data",
+ url="https://example.com/contact",
+ publish_workflow=True,
+ wait_for_completion=True,
+)
+# The generated workflow is saved and can be re-triggered via run_workflow
+```
+
+```typescript TypeScript
+const result = await skyvern.runTask({
+ body: {
+ prompt: "Fill out the contact form with the provided data",
+ url: "https://example.com/contact",
+ publish_workflow: true,
+ },
+ waitForCompletion: true,
+});
+// The generated workflow is saved and can be re-triggered via runWorkflow
+```
+</CodeGroup>
+
+---
+
+## Polling pattern
+
+If you don't use `wait_for_completion` / `waitForCompletion`, poll `get_run` / `getRun` manually:
+
+<CodeGroup>
+```python Python
+import asyncio
+
+task = await client.run_task(
+ prompt="Extract product data",
+ url="https://example.com/products",
+)
+
+while True:
+ run = await client.get_run(task.run_id)
+ if run.status in ("completed", "failed", "terminated", "timed_out", "canceled"):
+ break
+ await asyncio.sleep(5)
+
+print(run.output)
+```
+
+```typescript TypeScript
+const task = await skyvern.runTask({
+ body: {
+ prompt: "Extract product data",
+ url: "https://example.com/products",
+ },
+});
+
+const terminalStatuses = ["completed", "failed", "terminated", "timed_out", "canceled"];
+let run;
+while (true) {
+ run = await skyvern.getRun(task.run_id);
+ if (terminalStatuses.includes(run.status)) break;
+ await new Promise((resolve) => setTimeout(resolve, 5000));
+}
+
+console.log(run.output);
+```
+</CodeGroup>
+
+<Tip>
+For production, prefer `wait_for_completion=True` / `waitForCompletion: true` or [webhooks](/going-to-production/webhooks) over manual polling.
+</Tip>
+
+---
+
+## `wait_for_completion` / `waitForCompletion`
+
+By default, `run_task` / `runTask` and `run_workflow` / `runWorkflow` return immediately after the run is queued. You get a `run_id` and need to poll `get_run` / `getRun` yourself. Pass `wait_for_completion=True` / `waitForCompletion: true` to have the SDK poll automatically until the run reaches a terminal state (`completed`, `failed`, `terminated`, `timed_out`, or `canceled`):
+
+<CodeGroup>
+```python Python
+# Returns only after the task finishes (up to 30 min by default)
+result = await client.run_task(
+ prompt="Fill out the contact form",
+ url="https://example.com/contact",
+ wait_for_completion=True,
+ timeout=600, # give up after 10 minutes
+)
+
+# Without wait_for_completion -- returns immediately
+task = await client.run_task(
+ prompt="Fill out the contact form",
+ url="https://example.com/contact",
+)
+print(task.run_id) # poll with client.get_run(task.run_id)
+```
+
+```typescript TypeScript
+// Returns only after the task finishes (up to 30 min by default)
+const result = await skyvern.runTask({
+ body: {
+ prompt: "Fill out the contact form",
+ url: "https://example.com/contact",
+ },
+ waitForCompletion: true,
+ timeout: 600, // give up after 10 minutes
+});
+
+// Without waitForCompletion -- returns immediately
+const task = await skyvern.runTask({
+ body: {
+ prompt: "Fill out the contact form",
+ url: "https://example.com/contact",
+ },
+});
+console.log(task.run_id); // poll with skyvern.getRun(task.run_id)
+```
+</CodeGroup>
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `wait_for_completion` / `waitForCompletion` | `bool` / `boolean` | `False` / `false` | Poll until the run finishes. |
+| `timeout` | `float` / `number` | `1800` | Maximum wait time in seconds. Raises `TimeoutError` (Python) or `Error` (TS) if exceeded. |
+
+Supported on `run_task`/`runTask`, `run_workflow`/`runWorkflow`, and `login`. In TypeScript, also supported on `downloadFiles`.
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/workflows.mdx b/docs/sdk-reference/workflows.mdx
deleted file mode 100644
index a3a826641..000000000
--- a/docs/sdk-reference/workflows.mdx
+++ /dev/null
@@ -1,302 +0,0 @@
----
-title: Workflows
-subtitle: Create and run multi-step browser automations
-description: Create, run, update, and manage multi-step workflow automations using the Skyvern Python SDK. Covers run_workflow(), create_workflow(), get_workflows(), update_workflow(), delete_workflow(), and workflow configuration options.
-slug: sdk-reference/workflows
-keywords:
- - run_workflow
- - create_workflow
- - get_workflow
- - update_workflow
- - delete_workflow
- - get_workflow_versions
- - parameter
- - block
- - YAML
- - JSON
- - template
- - version
- - Playwright
----
-
-A workflow chains multiple steps (blocks) into a single automation. Workflows support loops, conditionals, data passing between steps, and code-based re-execution.
-
-For conceptual background, see [Build a Workflow](/multi-step-automations/build-a-workflow).
-
----
-
-## `run_workflow`
-
-Execute a workflow by its permanent ID. Skyvern opens a cloud browser and runs each block in sequence.
-
-```python
-result = await client.run_workflow(
- workflow_id="wpid_abc123",
- wait_for_completion=True,
-)
-print(result.output)
-```
-
-### Parameters
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `workflow_id` | `str` | Yes | — | The workflow's permanent ID (`wpid_...`). |
-| `parameters` | `dict` | No | `None` | Input parameters defined in the workflow. Keys must match parameter names. |
-| `wait_for_completion` | `bool` | No | `False` | Block until the workflow finishes. |
-| `timeout` | `float` | No | `1800` | Max wait time in seconds when `wait_for_completion=True`. |
-| `run_with` | `str` | No | `None` | Force execution mode: `"code"` (use cached Playwright code) or `"agent"` (use AI). |
-| `ai_fallback` | `bool` | No | `None` | Fall back to AI if the cached code fails. |
-| `browser_session_id` | `str` | No | `None` | Run inside an existing [browser session](/optimization/browser-sessions). |
-| `browser_profile_id` | `str` | No | `None` | Load a [browser profile](/optimization/browser-profiles) (cookies, storage) into the session. |
-| `proxy_location` | `ProxyLocation` | No | `None` | Route the browser through a geographic proxy. |
-| `max_steps_override` | `int` | No | `None` | Cap total AI steps across all blocks. |
-| `webhook_url` | `str` | No | `None` | URL to receive a POST when the run finishes. |
-| `title` | `str` | No | `None` | Display name for this run in the dashboard. |
-| `totp_identifier` | `str` | No | `None` | Identifier for TOTP verification. |
-| `totp_url` | `str` | No | `None` | URL to receive TOTP codes. |
-| `template` | `bool` | No | `None` | Run a template workflow. |
-| `user_agent` | `str` | No | `None` | Custom User-Agent header for the browser. |
-| `extra_http_headers` | `dict[str, str]` | No | `None` | Additional HTTP headers injected into every browser request. |
-| `max_screenshot_scrolls` | `int` | No | `None` | Number of scrolls for post-action screenshots. |
-| `browser_address` | `str` | No | `None` | Connect to a browser at this CDP address. |
-
-### Returns `WorkflowRunResponse`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `run_id` | `str` | Unique identifier. Starts with `wr_` for workflow runs. |
-| `status` | `str` | `created`, `queued`, `running`, `completed`, `failed`, `terminated`, `timed_out`, or `canceled`. |
-| `output` | `dict \| None` | Extracted data from the workflow's output block. |
-| `downloaded_files` | `list[FileInfo] \| None` | Files downloaded during the run. |
-| `recording_url` | `str \| None` | URL to the session recording. |
-| `failure_reason` | `str \| None` | Error description if the run failed. |
-| `app_url` | `str \| None` | Link to view this run in the Cloud UI. |
-| `step_count` | `int \| None` | Total AI steps taken across all blocks. |
-| `run_with` | `str \| None` | Whether the run used `"code"` or `"agent"`. |
-| `ai_fallback` | `bool \| None` | Whether AI fallback was configured. |
-| `script_run` | `ScriptRunResponse \| None` | Code execution result. Contains `ai_fallback_triggered` if code was used. |
-
-### Examples
-
-**Pass parameters to a workflow:**
-
-```python
-result = await client.run_workflow(
- workflow_id="wpid_invoice_extraction",
- parameters={
- "company_name": "Acme Corp",
- "date_range": "2025-01-01 to 2025-12-31",
- },
- wait_for_completion=True,
-)
-```
-
-**Run with cached code (skip AI, use generated Playwright scripts):**
-
-```python
-result = await client.run_workflow(
- workflow_id="wpid_daily_report",
- run_with="code",
- ai_fallback=True, # Fall back to AI if code fails
- wait_for_completion=True,
-)
-```
-
-**Run with a browser profile (skip login):**
-
-```python
-result = await client.run_workflow(
- workflow_id="wpid_daily_report",
- browser_profile_id="bpf_abc123",
- wait_for_completion=True,
-)
-```
-
----
-
-## `create_workflow`
-
-Create a new workflow from a JSON or YAML definition.
-
-```python
-workflow = await client.create_workflow(
- json_definition={
- "title": "Extract Products",
- "workflow_definition": {
- "parameters": [
- {
- "key": "target_url",
- "parameter_type": "workflow",
- "workflow_parameter_type": "string",
- "description": "URL to scrape",
- }
- ],
- "blocks": [
- {
- "block_type": "task",
- "label": "extract_data",
- "prompt": "Extract the top 3 products",
- "url": "{{ target_url }}",
- }
- ],
- },
- },
-)
-print(workflow.workflow_permanent_id)
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `json_definition` | `WorkflowCreateYamlRequest` | No | Workflow definition as a JSON object. |
-| `yaml_definition` | `str` | No | Workflow definition as a YAML string. |
-| `folder_id` | `str` | No | Folder to organize the workflow in. |
-
-You must provide either `json_definition` or `yaml_definition`.
-
-### Returns `Workflow`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `workflow_id` | `str` | Unique ID for this version. |
-| `workflow_permanent_id` | `str` | Stable ID across all versions. Use this to run workflows. |
-| `version` | `int` | Version number. |
-| `title` | `str` | Workflow title. |
-| `workflow_definition` | `WorkflowDefinition` | The full definition including blocks and parameters. |
-| `status` | `str \| None` | Workflow status. |
-| `created_at` | `datetime` | When the workflow was created. |
-
----
-
-## `get_workflows`
-
-List all workflows. Supports filtering and pagination.
-
-```python
-workflows = await client.get_workflows()
-for wf in workflows:
- print(f"{wf.title} ({wf.workflow_permanent_id})")
-```
-
-### Parameters
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `page` | `int` | No | `None` | Page number for pagination. |
-| `page_size` | `int` | No | `None` | Number of results per page. |
-| `only_saved_tasks` | `bool` | No | `None` | Only return saved tasks. |
-| `only_workflows` | `bool` | No | `None` | Only return workflows (not saved tasks). |
-| `only_templates` | `bool` | No | `None` | Only return templates. |
-| `title` | `str` | No | `None` | Filter by exact title. |
-| `search_key` | `str` | No | `None` | Search by title. |
-| `folder_id` | `str` | No | `None` | Filter by folder. |
-| `status` | `WorkflowStatus \| list[WorkflowStatus]` | No | `None` | Filter by status. |
-
-### Returns `list[Workflow]`
-
----
-
-## `get_workflow`
-
-<Info>
-Requires `skyvern` version 1.1.0 or later. Run `pip install --upgrade skyvern` to update.
-</Info>
-
-Get a specific workflow by its permanent ID.
-
-```python
-workflow = await client.get_workflow("wpid_abc123")
-print(workflow.title, f"v{workflow.version}")
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `workflow_permanent_id` | `str` | Yes | The workflow's permanent ID. |
-| `version` | `int` | No | Specific version to retrieve. Defaults to latest. |
-| `template` | `bool` | No | Whether to fetch a template workflow. |
-
-### Returns `Workflow`
-
----
-
-## `get_workflow_versions`
-
-<Info>
-Requires `skyvern` version 1.1.0 or later. Run `pip install --upgrade skyvern` to update.
-</Info>
-
-List all versions of a workflow.
-
-```python
-versions = await client.get_workflow_versions("wpid_abc123")
-for v in versions:
- print(f"v{v.version} — {v.modified_at}")
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `workflow_permanent_id` | `str` | Yes | The workflow's permanent ID. |
-| `template` | `bool` | No | Whether to fetch template versions. |
-
-### Returns `list[Workflow]`
-
----
-
-## `update_workflow`
-
-Update an existing workflow's definition.
-
-```python
-updated = await client.update_workflow(
- "wpid_abc123",
- json_definition={
- "title": "Extract Products",
- "workflow_definition": {
- "blocks": [
- {
- "block_type": "task",
- "label": "extract_data",
- "prompt": "Extract the top 5 products",
- "url": "https://example.com/products",
- }
- ],
- "parameters": [],
- },
- },
-)
-print(f"Updated to v{updated.version}")
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `workflow_id` | `str` | Yes | The workflow's permanent ID (`wpid_...`). |
-| `json_definition` | `WorkflowCreateYamlRequest` | No | Updated workflow definition as JSON. |
-| `yaml_definition` | `str` | No | Updated workflow definition as YAML. |
-
-### Returns `Workflow`
-
-Creates a new version of the workflow.
-
----
-
-## `delete_workflow`
-
-Delete a workflow.
-
-```python
-await client.delete_workflow("wf_abc123")
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `workflow_id` | `str` | Yes | The workflow version ID to delete. |
diff --git a/docs/sdk-reference/workflows/create-workflow.mdx b/docs/sdk-reference/workflows/create-workflow.mdx
new file mode 100644
index 000000000..d09f14cf2
--- /dev/null
+++ b/docs/sdk-reference/workflows/create-workflow.mdx
@@ -0,0 +1,128 @@
+---
+title: create_workflow
+slug: sdk-reference/workflows/create-workflow
+---
+
+Create a new workflow from a JSON or YAML definition.
+
+<CodeGroup>
+```python Python
+workflow = await client.create_workflow(
+ json_definition={
+ "title": "Extract Products",
+ "workflow_definition": {
+ "parameters": [
+ {
+ "key": "target_url",
+ "parameter_type": "workflow",
+ "workflow_parameter_type": "string",
+ "description": "URL to scrape",
+ }
+ ],
+ "blocks": [
+ {
+ "block_type": "task",
+ "label": "extract_data",
+ "prompt": "Extract the top 3 products",
+ "url": "{{ target_url }}",
+ }
+ ],
+ },
+ },
+)
+print(workflow.workflow_permanent_id)
+```
+
+```typescript TypeScript
+const workflow = await skyvern.createWorkflow({
+ body: {
+ json_definition: {
+ title: "Extract Products",
+ workflow_definition: {
+ parameters: [
+ {
+ key: "target_url",
+ parameter_type: "workflow",
+ workflow_parameter_type: "string",
+ description: "URL to scrape",
+ },
+ ],
+ blocks: [
+ {
+ block_type: "task",
+ label: "extract",
+ prompt: "Extract the top 3 products with name and price",
+ url: "{{ target_url }}",
+ },
+ ],
+ },
+ },
+ },
+});
+console.log(workflow.workflow_permanent_id);
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `json_definition` | `WorkflowCreateYamlRequest` | No | Workflow definition as a JSON object. |
+| `yaml_definition` | `str` | No | Workflow definition as a YAML string. |
+| `folder_id` | `str` | No | Folder to organize the workflow in. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+You must provide either `json_definition` or `yaml_definition`.
+
+### Returns `Workflow`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `workflow_id` | `str` | Unique ID for this version. |
+| `workflow_permanent_id` | `str` | Stable ID across all versions. Use this to run workflows. |
+| `version` | `int` | Version number. |
+| `title` | `str` | Workflow title. |
+| `workflow_definition` | `WorkflowDefinition` | The full definition including blocks and parameters. |
+| `status` | `str \| None` | Workflow status. |
+| `created_at` | `datetime` | When the workflow was created. |
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/workflows/delete-workflow.mdx b/docs/sdk-reference/workflows/delete-workflow.mdx
new file mode 100644
index 000000000..c04e8d56f
--- /dev/null
+++ b/docs/sdk-reference/workflows/delete-workflow.mdx
@@ -0,0 +1,64 @@
+---
+title: delete_workflow
+slug: sdk-reference/workflows/delete-workflow
+---
+
+Delete a workflow.
+
+<CodeGroup>
+```python Python
+await client.delete_workflow("wf_abc123")
+```
+
+```typescript TypeScript
+await skyvern.deleteWorkflow("wf_abc123");
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `workflow_id` | `str` | Yes | The workflow version ID to delete. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/workflows/get-workflow-runs.mdx b/docs/sdk-reference/workflows/get-workflow-runs.mdx
new file mode 100644
index 000000000..049a268a0
--- /dev/null
+++ b/docs/sdk-reference/workflows/get-workflow-runs.mdx
@@ -0,0 +1,75 @@
+---
+title: get_workflow_runs
+slug: sdk-reference/workflows/get-workflow-runs
+---
+
+List workflow runs across all workflows for the current organization. Results are paginated and can be filtered by status, search key, and error code.
+
+<CodeGroup>
+```python Python
+runs = await client.get_workflow_runs(page=1, page_size=10)
+for run in runs:
+ print(run.workflow_run_id, run.status)
+```
+
+```typescript TypeScript
+const runs = await skyvern.getWorkflowRuns({ page: 1, page_size: 10 });
+for (const run of runs) {
+ console.log(run.workflow_run_id, run.status);
+}
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `page` | `int` | No | Page number (1-indexed). |
+| `page_size` | `int` | No | Results per page. |
+| `status` | `WorkflowRunStatus \| list[WorkflowRunStatus]` | No | Filter by run status. |
+| `search_key` | `str` | No | Case-insensitive substring search (min 3 chars). Matches against run ID, parameter keys, parameter values, and descriptions. |
+| `error_code` | `str` | No | Filter by error code. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+### Returns `list[WorkflowRun]`
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/workflows/get-workflow-versions.mdx b/docs/sdk-reference/workflows/get-workflow-versions.mdx
new file mode 100644
index 000000000..2d67099f9
--- /dev/null
+++ b/docs/sdk-reference/workflows/get-workflow-versions.mdx
@@ -0,0 +1,76 @@
+---
+title: get_workflow_versions
+slug: sdk-reference/workflows/get-workflow-versions
+---
+
+<Info>
+Python: requires `skyvern` version 1.1.0 or later. Run `pip install --upgrade skyvern` to update.
+</Info>
+
+List all versions of a workflow.
+
+<CodeGroup>
+```python Python
+versions = await client.get_workflow_versions("wpid_abc123")
+for v in versions:
+ print(f"v{v.version} - {v.modified_at}")
+```
+
+```typescript TypeScript
+const versions = await skyvern.getWorkflowVersions("wpid_abc123");
+for (const v of versions) {
+ console.log(`v${v.version} - ${v.modified_at}`);
+}
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `workflow_permanent_id` | `str` | Yes | The workflow's permanent ID. |
+| `template` | `bool` | No | Whether to fetch template versions. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+### Returns `list[Workflow]`
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/workflows/get-workflow.mdx b/docs/sdk-reference/workflows/get-workflow.mdx
new file mode 100644
index 000000000..8536d8de5
--- /dev/null
+++ b/docs/sdk-reference/workflows/get-workflow.mdx
@@ -0,0 +1,74 @@
+---
+title: get_workflow
+slug: sdk-reference/workflows/get-workflow
+---
+
+<Info>
+Python: requires `skyvern` version 1.1.0 or later. Run `pip install --upgrade skyvern` to update.
+</Info>
+
+Get a specific workflow by its permanent ID.
+
+<CodeGroup>
+```python Python
+workflow = await client.get_workflow("wpid_abc123")
+print(workflow.title, f"v{workflow.version}")
+```
+
+```typescript TypeScript
+const workflow = await skyvern.getWorkflow("wpid_abc123");
+console.log(workflow.title, `v${workflow.version}`);
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `workflow_permanent_id` | `str` | Yes | The workflow's permanent ID. |
+| `version` | `int` | No | Specific version to retrieve. Defaults to latest. |
+| `template` | `bool` | No | Whether to fetch a template workflow. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+### Returns `Workflow`
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/workflows/get-workflows.mdx b/docs/sdk-reference/workflows/get-workflows.mdx
new file mode 100644
index 000000000..23905da11
--- /dev/null
+++ b/docs/sdk-reference/workflows/get-workflows.mdx
@@ -0,0 +1,80 @@
+---
+title: get_workflows
+slug: sdk-reference/workflows/get-workflows
+---
+
+List all workflows. Supports filtering and pagination.
+
+<CodeGroup>
+```python Python
+workflows = await client.get_workflows()
+for wf in workflows:
+ print(f"{wf.title} ({wf.workflow_permanent_id})")
+```
+
+```typescript TypeScript
+const workflows = await skyvern.getWorkflows({});
+for (const wf of workflows) {
+ console.log(`${wf.title} (${wf.workflow_permanent_id})`);
+}
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `page` | `int` | No | `None` | Page number for pagination. |
+| `page_size` | `int` | No | `None` | Number of results per page. |
+| `only_saved_tasks` | `bool` | No | `None` | Only return saved tasks. |
+| `only_workflows` | `bool` | No | `None` | Only return workflows (not saved tasks). |
+| `only_templates` | `bool` | No | `None` | Only return templates. |
+| `template` | `bool` | No | `None` | Only return template workflows. |
+| `title` | `str` | No | `None` | Filter by title. Deprecated - use `search_key` instead. |
+| `search_key` | `str` | No | `None` | Case-insensitive substring search across workflow title, folder name, and parameter metadata. |
+| `folder_id` | `str` | No | `None` | Filter by folder. |
+| `status` | `WorkflowStatus \| list[WorkflowStatus]` | No | `None` | Filter by status. |
+| `request_options` | `RequestOptions` | No | - | Per-request configuration (see below). |
+
+### Returns `list[Workflow]`
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/workflows/run-workflow.mdx b/docs/sdk-reference/workflows/run-workflow.mdx
new file mode 100644
index 000000000..85ad326ab
--- /dev/null
+++ b/docs/sdk-reference/workflows/run-workflow.mdx
@@ -0,0 +1,179 @@
+---
+title: run_workflow
+slug: sdk-reference/workflows/run-workflow
+---
+
+A workflow chains multiple steps (blocks) into a single automation. Workflows support loops, conditionals, data passing between steps, and code-based re-execution.
+
+For conceptual background, see [Build a Workflow](/cloud/building-workflows/build-a-workflow).
+
+<Note>
+Python uses `snake_case` (e.g., `run_workflow`); TypeScript uses `camelCase` (e.g., `runWorkflow`) and wraps request params in a `body` object. Parameter tables show Python names. TypeScript names are the camelCase equivalents.
+</Note>
+
+Execute a workflow by its permanent ID. Skyvern opens a cloud browser and runs each block in sequence.
+
+<CodeGroup>
+```python Python
+result = await client.run_workflow(
+ workflow_id="wpid_abc123",
+ wait_for_completion=True,
+)
+print(result.output)
+```
+
+```typescript TypeScript
+const result = await skyvern.runWorkflow({
+ body: {
+ workflow_id: "wpid_abc123",
+ },
+ waitForCompletion: true,
+});
+console.log(result.output);
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `workflow_id` | `str` | Yes | - | The workflow's permanent ID (`wpid_...`). |
+| `parameters` | `dict` | No | `None` | Input parameters defined in the workflow. Keys must match parameter names. |
+| `wait_for_completion` | `bool` | No | `False` | Block until the workflow finishes. |
+| `timeout` | `float` | No | `1800` | Max wait time in seconds when `wait_for_completion=True`. |
+| `run_with` | `str` | No | `None` | Force execution mode: `"code"` (use cached Playwright code) or `"agent"` (use AI). |
+| `ai_fallback` | `bool` | No | `None` | Fall back to AI if the cached code fails. |
+| `browser_session_id` | `str` | No | `None` | Run inside an existing [browser session](/optimization/browser-sessions). |
+| `browser_profile_id` | `str` | No | `None` | Load a [browser profile](/optimization/browser-profiles) (cookies, storage) into the session. |
+| `proxy_location` | `ProxyLocation` | No | `None` | Route the browser through a geographic proxy. |
+| `max_steps_override` | `int` | No | `None` | Cap total AI steps across all blocks. |
+| `webhook_url` | `str` | No | `None` | URL to receive a POST when the run finishes. |
+| `title` | `str` | No | `None` | Display name for this run in the dashboard. |
+| `totp_identifier` | `str` | No | `None` | Identifier for TOTP verification. |
+| `totp_url` | `str` | No | `None` | URL to receive TOTP codes. |
+| `template` | `bool` | No | `None` | Run a template workflow. |
+| `user_agent` | `str` | No | `None` | Custom User-Agent header for the browser. |
+| `extra_http_headers` | `dict[str, str]` | No | `None` | Additional HTTP headers injected into every browser request. |
+| `max_screenshot_scrolls` | `int` | No | `None` | Number of scrolls for post-action screenshots. |
+| `browser_address` | `str` | No | `None` | Connect to a browser at this CDP address. |
+| `request_options` | `RequestOptions` | No | - | Per-request configuration (see below). |
+
+### Returns `WorkflowRunResponse`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `run_id` | `str` | Unique identifier. Starts with `wr_` for workflow runs. |
+| `status` | `str` | `created`, `queued`, `running`, `completed`, `failed`, `terminated`, `timed_out`, or `canceled`. |
+| `output` | `dict \| None` | Extracted data from the workflow's output block. |
+| `downloaded_files` | `list[FileInfo] \| None` | Files downloaded during the run. |
+| `recording_url` | `str \| None` | URL to the session recording. |
+| `failure_reason` | `str \| None` | Error description if the run failed. |
+| `app_url` | `str \| None` | Link to view this run in the Cloud UI. |
+| `step_count` | `int \| None` | Total AI steps taken across all blocks. |
+| `run_with` | `str \| None` | Whether the run used `"code"` or `"agent"`. |
+| `ai_fallback` | `bool \| None` | Whether AI fallback was configured. |
+| `script_run` | `ScriptRunResponse \| None` | Code execution result. Contains `ai_fallback_triggered` if code was used. |
+
+### Examples
+
+**Pass parameters to a workflow:**
+
+<CodeGroup>
+```python Python
+result = await client.run_workflow(
+ workflow_id="wpid_invoice_extraction",
+ parameters={
+ "company_name": "Acme Corp",
+ "date_range": "2025-01-01 to 2025-12-31",
+ },
+ wait_for_completion=True,
+)
+```
+
+```typescript TypeScript
+const result = await skyvern.runWorkflow({
+ body: {
+ workflow_id: "wpid_invoice_extraction",
+ parameters: {
+ company_name: "Acme Corp",
+ date_range: "2025-01-01 to 2025-12-31",
+ },
+ },
+ waitForCompletion: true,
+});
+```
+</CodeGroup>
+
+**Run with cached code (skip AI, use generated Playwright scripts):**
+
+```python
+result = await client.run_workflow(
+ workflow_id="wpid_daily_report",
+ run_with="code",
+ ai_fallback=True, # Fall back to AI if code fails
+ wait_for_completion=True,
+)
+```
+
+**Run with a browser profile (skip login):**
+
+<CodeGroup>
+```python Python
+result = await client.run_workflow(
+ workflow_id="wpid_daily_report",
+ browser_profile_id="bpf_abc123",
+ wait_for_completion=True,
+)
+```
+
+```typescript TypeScript
+const result = await skyvern.runWorkflow({
+ body: {
+ workflow_id: "wpid_daily_report",
+ browser_profile_id: "bpf_abc123",
+ },
+ waitForCompletion: true,
+});
+```
+</CodeGroup>
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/workflows/update-workflow-folder.mdx b/docs/sdk-reference/workflows/update-workflow-folder.mdx
new file mode 100644
index 000000000..182a6f092
--- /dev/null
+++ b/docs/sdk-reference/workflows/update-workflow-folder.mdx
@@ -0,0 +1,72 @@
+---
+title: update_workflow_folder
+slug: sdk-reference/workflows/update-workflow-folder
+---
+
+Move a workflow to a different folder, or remove it from its current folder.
+
+<CodeGroup>
+```python Python
+workflow = await client.update_workflow_folder(
+ "wpid_abc123",
+ folder_id="folder_456",
+)
+```
+
+```typescript TypeScript
+const workflow = await skyvern.updateWorkflowFolder("wpid_abc123", {
+ folder_id: "folder_456",
+});
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `workflow_permanent_id` | `str` | Yes | The workflow permanent ID. |
+| `folder_id` | `str` | No | Folder ID to assign. Set to `None` / `null` to remove from folder. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+### Returns `Workflow`
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/sdk-reference/workflows/update-workflow.mdx b/docs/sdk-reference/workflows/update-workflow.mdx
new file mode 100644
index 000000000..7b3a09160
--- /dev/null
+++ b/docs/sdk-reference/workflows/update-workflow.mdx
@@ -0,0 +1,103 @@
+---
+title: update_workflow
+slug: sdk-reference/workflows/update-workflow
+---
+
+Update an existing workflow's definition.
+
+<CodeGroup>
+```python Python
+updated = await client.update_workflow(
+ "wpid_abc123",
+ json_definition={
+ "title": "Extract Products",
+ "workflow_definition": {
+ "blocks": [
+ {
+ "block_type": "task",
+ "label": "extract_data",
+ "prompt": "Extract the top 5 products",
+ "url": "https://example.com/products",
+ }
+ ],
+ "parameters": [],
+ },
+ },
+)
+print(f"Updated to v{updated.version}")
+```
+
+```typescript TypeScript
+const updated = await skyvern.updateWorkflow("wpid_abc123", {
+ json_definition: {
+ title: "Extract Products Updated",
+ workflow_definition: {
+ blocks: [
+ {
+ block_type: "task",
+ label: "extract_data",
+ prompt: "Extract the top 5 products",
+ url: "https://example.com/products",
+ },
+ ],
+ parameters: [],
+ },
+ },
+});
+console.log(`Updated to v${updated.version}`);
+```
+</CodeGroup>
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `workflow_id` | `str` | Yes | The workflow's permanent ID (`wpid_...`). |
+| `json_definition` | `WorkflowCreateYamlRequest` | No | Updated definition as a JSON object. |
+| `yaml_definition` | `str` | No | Updated definition as a YAML string. |
+| `request_options` | `RequestOptions` | No | Per-request configuration (see below). |
+
+### Returns `Workflow`
+
+Creates a new version of the workflow.
+
+---
+
+### Request options
+
+
+Override timeout, retries, or headers for this call by passing `request_options` (Python) or a second options argument (TypeScript).
+
+<CodeGroup>
+```python Python
+from skyvern.client.core import RequestOptions
+
+request_options=RequestOptions(
+ timeout_in_seconds=120,
+ max_retries=3,
+ additional_headers={"x-custom-header": "value"},
+)
+```
+
+```typescript TypeScript
+// Pass as second argument to any method
+{
+ timeoutInSeconds: 120,
+ maxRetries: 3,
+ headers: { "x-custom-header": "value" },
+}
+```
+</CodeGroup>
+
+| Option (Python) | Option (TypeScript) | Type | Description |
+|-----------------|---------------------|------|-------------|
+| `timeout_in_seconds` | `timeoutInSeconds` | `int` / `number` | HTTP timeout in seconds. |
+| `max_retries` | `maxRetries` | `int` / `number` | Retry count. |
+| `additional_headers` | `headers` | `dict` / `Record<string, string>` | Extra headers. |
+| `additional_query_parameters` | - | `dict` | Extra query parameters. |
+| `additional_body_parameters` | - | `dict` | Extra body parameters. |
+| - | `abortSignal` | `AbortSignal` | Signal to cancel the request. |
+| - | `apiKey` | `string` | Override API key. |
+
+
+---
diff --git a/docs/self-hosted/browser.mdx b/docs/self-hosted/browser.mdx
index 5d65fe2dd..7ea5677bb 100644
--- a/docs/self-hosted/browser.mdx
+++ b/docs/self-hosted/browser.mdx
@@ -20,10 +20,10 @@ Skyvern uses Playwright with Chromium to execute browser automations.
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](#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)
@@ -75,7 +75,7 @@ Connect to an existing Chrome instance running with remote debugging enabled. Us
## 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.
+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
diff --git a/docs/skill.md b/docs/skill.md
index 6ae1b0d12..a68698e3d 100644
--- a/docs/skill.md
+++ b/docs/skill.md
@@ -1,6 +1,6 @@
---
name: skyvern
-description: Automate any website with AI-powered browser automation. Use when the user needs to interact with a website — filling forms, extracting data, downloading files, logging in, or running multi-step workflows. Skyvern navigates sites it has never seen before using LLMs and computer vision. Integrates via Python SDK, TypeScript SDK, REST API, MCP server, or CLI.
+description: Automate any website with AI-powered browser automation. Use when the user needs to interact with a website like filling forms, extracting data, downloading files, logging in, or running multi-step workflows. Skyvern navigates sites it has never seen before using LLMs and computer vision. Integrates via Python SDK, TypeScript SDK, REST API, MCP server, or CLI.
license: AGPL-3.0
compatibility: Requires a Skyvern Cloud API key (https://app.skyvern.com) or a self-hosted Skyvern instance. Python SDK requires Python 3.11+. TypeScript SDK requires Node.js 18+. MCP server works with Claude Code, Claude Desktop, Cursor, Windsurf, and VS Code.
metadata:
@@ -10,9 +10,11 @@ metadata:
github: https://github.com/Skyvern-AI/skyvern
---
-# Skyvern — AI Browser Automation
+# Skyvern: AI Browser Automation
-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.
+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.
+
+**SDK reference (all methods, parameters, types in one page):** https://skyvern.com/docs/sdk-reference/complete-reference
## When to use Skyvern
@@ -108,7 +110,7 @@ run = await client.run_workflow(workflow_id=workflow.workflow_id)
### Manage browser sessions
-Persist a live browser across multiple tasks — maintain login state, cookies, and page context.
+Persist a live browser across multiple tasks to maintain login state, cookies, and page context.
```python
session = await client.create_session()
@@ -170,10 +172,9 @@ skyvern workflow run --id wf_xxx # Run a workflow
## Key references
-- [API Quickstart](https://skyvern.com/docs/getting-started/quickstart.md): First task in 5 minutes
-- [Python SDK Reference](https://skyvern.com/docs/sdk-reference/complete-reference.md): All methods and types
-- [TypeScript SDK Reference](https://skyvern.com/docs/ts-sdk-reference/complete-reference.md): All methods and types
+- [Quickstart](https://skyvern.com/docs/getting-started/quickstart.md): First task in 5 minutes
+- [SDK Reference](https://skyvern.com/docs/sdk-reference/complete-reference.md): All methods and types (Python + TypeScript)
- [MCP Server Setup](https://skyvern.com/docs/going-to-production/mcp.md): Connect AI assistants
-- [Workflow Blocks Reference](https://skyvern.com/docs/multi-step-automations/workflow-blocks-reference.md): All block types
+- [Workflow Blocks Reference](https://skyvern.com/docs/cloud/building-workflows/configure-blocks.md): All block types
- [Task Parameters](https://skyvern.com/docs/running-automations/task-parameters.md): All task options
- [Full documentation index](https://skyvern.com/docs/llms.txt): Complete page directory
diff --git a/docs/snippets/ai-agents-quickstart-content.mdx b/docs/snippets/ai-agents-quickstart-content.mdx
new file mode 100644
index 000000000..fd54ab734
--- /dev/null
+++ b/docs/snippets/ai-agents-quickstart-content.mdx
@@ -0,0 +1,342 @@
+export const ApiKeyPrompt = ({ children }) => {
+ const [apiKey, setApiKey] = useState("");
+ const [copied, setCopied] = useState(false);
+ const text = typeof children === "string" ? children : String(children);
+ const lines = text.split("\n");
+ const indents = lines.slice(1).filter(l => l.trim()).map(l => l.match(/^(\s*)/)[1].length);
+ const min = indents.length ? Math.min(...indents) : 0;
+ const raw = min > 0 ? lines.map((l, i) => i === 0 ? l : l.slice(min)).join("\n") : text;
+ const content = apiKey ? raw.replace(/PASTE_YOUR_API_KEY_HERE/g, apiKey) : raw;
+ return (
+ <div>
+ <input
+ type="text"
+ placeholder="Paste your Skyvern API key"
+ value={apiKey}
+ onChange={(e) => setApiKey(e.target.value)}
+ spellCheck={false}
+ autoComplete="off"
+ style={{
+ width: "100%",
+ padding: "10px 14px",
+ marginBottom: "12px",
+ borderRadius: "8px",
+ border: "1px solid var(--border, #d1d5db)",
+ fontSize: "14px",
+ fontFamily: "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace",
+ backgroundColor: "var(--background, transparent)",
+ color: "inherit",
+ outline: "none",
+ boxSizing: "border-box",
+ }}
+ />
+ <div style={{ position: "relative", borderRadius: "8px", overflow: "hidden" }}>
+ <button
+ onClick={async () => {
+ await navigator.clipboard.writeText(content);
+ setCopied(true);
+ setTimeout(() => setCopied(false), 2000);
+ }}
+ style={{
+ position: "absolute",
+ top: "10px",
+ right: "10px",
+ padding: "4px 12px",
+ fontSize: "12px",
+ borderRadius: "6px",
+ border: "none",
+ backgroundColor: "rgba(255, 255, 255, 0.1)",
+ color: "#a1a1aa",
+ cursor: "pointer",
+ zIndex: 1,
+ }}
+ >
+ {copied ? "Copied!" : "Copy"}
+ </button>
+ <pre style={{
+ margin: 0,
+ padding: "16px",
+ overflowX: "auto",
+ fontSize: "13px",
+ lineHeight: "1.7",
+ backgroundColor: "#0d1117",
+ color: "#e6edf3",
+ }}>
+ <code>{content}</code>
+ </pre>
+ </div>
+ </div>
+ );
+};
+
+Skyvern lets AI coding assistants (Claude Code, Cursor, Windsurf, Codex) control browsers, extract data, and run workflows.
+
+**Copy the prompt below** into your AI coding agent and you'll have a running automation in minutes.
+
+<Note>
+Looking to self-host instead? See the [local installation guide](/getting-started/quickstart) for full setup instructions.
+</Note>
+
+## 1. Get your API key
+
+Go to [app.skyvern.com/settings](https://app.skyvern.com/settings) and get your API key.
+
+<Frame>
+ <img src="/images/get-api-key.png" alt="Skyvern Settings page showing the API Keys section with a masked key and reveal/copy buttons" width="500" />
+</Frame>
+
+## 2. Give this prompt to your AI coding agent
+
+Paste your API key below, then copy the prompt into your AI coding assistant.
+
+It will:
+1. Install the Skyvern Python/TypeScript SDK
+2. Ask what you want to automate (say "Go to Hacker News and get the top comment of the #1 post" for example)
+3. Write a browser automation that launches a cloud browser, runs AI actions on pages, and prints the result
+
+<Tabs>
+<Tab title="Python">
+
+<ApiKeyPrompt>{`Set up Skyvern for browser automation:
+
+1. Install the Skyvern Python SDK (requires Python 3.11, 3.12, or 3.13).
+ If you hit version errors, use pipx to install in an isolated environment:
+ pip install skyvern
+ # or: pipx install skyvern
+
+2. Install all Skyvern skills into this project:
+ skyvern skill copy --output .claude/skills/
+
+3. Set my API key:
+ export SKYVERN_API_KEY="PASTE_YOUR_API_KEY_HERE"
+
+Now ask me what I want to automate in the browser. Suggest this as a default:
+"Go to Hacker News and get the top comment of the #1 post"
+
+After I respond, create a skyvern-tasks/ folder and save a Python file there
+using this template, replacing <URL>, <TASK>, and the schema fields with what
+I asked for. Use the Page/Agent/Browser pattern: launch a cloud browser, get a
+page, then run AI actions on it.
+
+ 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()
+
+ try:
+ await page.goto("<URL>")
+
+ # 2. For a multi-step goal (navigate + extract), use the agent
+ result = await page.agent.run_task(
+ "<TASK>",
+ data_extraction_schema={
+ "type": "object",
+ "properties": {
+ "answer": {"type": "string"},
+ },
+ },
+ )
+
+ print(f"Status: {result.status}")
+ print(f"View run: {result.app_url}")
+ print(f"Steps used: {result.step_count}")
+ if result.output is not None:
+ print(f"Output: {result.output}")
+ elif result.failure_reason:
+ print(f"Failed: {result.failure_reason}")
+ finally:
+ # 3. Always close the browser to release cloud resources
+ await browser.close()
+
+ asyncio.run(main())
+
+Run the file and show me the output.
+
+Notes:
+- For one-shot extraction on a single page, use page.extract() directly instead of agent.run_task().
+- For anything requiring login, use page.agent.login() before the task.
+- Always wrap browser usage in try/finally with browser.close().
+
+Reference docs you can fetch as needed:
+- https://skyvern.com/docs/llms.txt (full page index, LLM-friendly)
+- https://skyvern.com/docs/sdk-reference/complete-reference.md (every SDK method, parameter, and type; unified Python + TypeScript)
+- https://skyvern.com/docs/api-reference/openapi.json (OpenAPI spec for the REST API)`}</ApiKeyPrompt>
+
+</Tab>
+<Tab title="TypeScript">
+
+<ApiKeyPrompt>{`Set up Skyvern for browser automation:
+
+1. Initialize a Node.js project (if needed) and install the Skyvern TypeScript SDK:
+ npm init -y
+ npm install @skyvern/client
+
+2. Set my API key:
+ export SKYVERN_API_KEY="PASTE_YOUR_API_KEY_HERE"
+
+Now ask me what I want to automate in the browser. Suggest this as a default:
+"Go to Hacker News and get the top comment of the #1 post"
+
+After I respond, create a skyvern-tasks/ folder and save a TypeScript file there
+using this template, replacing <URL>, <TASK>, and the schema fields with what
+I asked for. Use the Page/Agent/Browser pattern: launch a cloud browser, get a
+page, then run AI actions on it.
+
+ 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();
+
+ try {
+ await page.goto("<URL>");
+
+ // 2. For a multi-step goal (navigate + extract), use the agent
+ const result = await page.agent.runTask("<TASK>", {
+ dataExtractionSchema: {
+ type: "object",
+ properties: {
+ answer: { type: "string" },
+ },
+ },
+ });
+
+ console.log(\`Status: \${result.status}\`);
+ console.log(\`View run: \${result.appUrl}\`);
+ console.log(\`Steps used: \${result.stepCount}\`);
+ if (result.output != null) {
+ console.log("Output:", result.output);
+ } else if (result.failureReason) {
+ console.log(\`Failed: \${result.failureReason}\`);
+ }
+ } finally {
+ // 3. Always close the browser to release cloud resources
+ await browser.close();
+ }
+ }
+
+ main();
+
+Run the file and show me the output.
+
+Notes:
+- For one-shot extraction on a single page, use page.extract() directly instead of agent.runTask().
+- For anything requiring login, use page.agent.login() before the task.
+- Always wrap browser usage in try/finally with browser.close().
+
+Reference docs you can fetch as needed:
+- https://skyvern.com/docs/llms.txt (full page index, LLM-friendly)
+- https://skyvern.com/docs/sdk-reference/complete-reference.md (every SDK method, parameter, and type; unified Python + TypeScript)
+- https://skyvern.com/docs/api-reference/openapi.json (OpenAPI spec for the REST API)`}</ApiKeyPrompt>
+
+</Tab>
+</Tabs>
+
+## 3. Next steps
+
+### Connect the MCP server
+
+Give your AI coding assistant direct browser control through natural language. No SDK code needed.
+
+<Tabs>
+<Tab title="Claude Code">
+
+```bash
+claude mcp add-json skyvern '{"type":"http","url":"https://api.skyvern.com/mcp/","headers":{"x-api-key":"YOUR_SKYVERN_API_KEY"}}' --scope user
+```
+
+</Tab>
+<Tab title="Cursor">
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+ "mcpServers": {
+ "Skyvern": {
+ "type": "streamable-http",
+ "url": "https://api.skyvern.com/mcp/",
+ "headers": {
+ "x-api-key": "YOUR_SKYVERN_API_KEY"
+ }
+ }
+ }
+}
+```
+
+</Tab>
+<Tab title="Windsurf">
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+ "mcpServers": {
+ "Skyvern": {
+ "type": "streamable-http",
+ "url": "https://api.skyvern.com/mcp/",
+ "headers": {
+ "x-api-key": "YOUR_SKYVERN_API_KEY"
+ }
+ }
+ }
+}
+```
+
+</Tab>
+<Tab title="Codex">
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.skyvern]
+url = "https://api.skyvern.com/mcp/"
+
+[mcp_servers.skyvern.http_headers]
+x-api-key = "YOUR_SKYVERN_API_KEY"
+```
+
+</Tab>
+</Tabs>
+
+### Keep building
+
+<CardGroup cols={2}>
+ <Card
+ title="Build a Browser Automation"
+ icon="browser"
+ href="/browser-automations/overview"
+ >
+ The full Page/Agent/Browser walkthrough
+ </Card>
+ <Card
+ title="SDK Reference"
+ icon="code"
+ href="/sdk-reference/complete-reference"
+ >
+ Every SDK method, parameter, and type (Python + TypeScript)
+ </Card>
+ <Card
+ title="Full MCP Reference"
+ icon="server"
+ href="/integrations/mcp"
+ >
+ All tools, config options, local mode, and troubleshooting
+ </Card>
+ <Card
+ title="llms.txt"
+ icon="file-lines"
+ href="https://skyvern.com/docs/llms.txt"
+ >
+ Machine-readable doc index for AI coding agents
+ </Card>
+</CardGroup>
diff --git a/docs/snippets/core-concepts-content.mdx b/docs/snippets/core-concepts-content.mdx
index 1847e792c..04c242dbe 100644
--- a/docs/snippets/core-concepts-content.mdx
+++ b/docs/snippets/core-concepts-content.mdx
@@ -1,10 +1,8 @@
-Skyvern has nine core concepts. Master these and you can build any browser automation.
-
----
+Skyvern has a handful of core concepts. Once you understand how they fit together, you can build any browser automation.
## Tasks
-A **Task** is a single automation job—think of it as asking Skyvern to do one thing. You provide a prompt describing the goal, and Skyvern navigates the browser to complete it.
+A Task is a single automation job. You provide a natural-language prompt describing the goal, a starting URL, and optionally a JSON schema for structured output. Skyvern navigates the browser and returns the result.
```python
from skyvern import Skyvern
@@ -28,27 +26,93 @@ result = await skyvern.run_task(
print(result.output) # {"posts": ["Post 1", "Post 2", "Post 3"]}
```
-**Key properties:**
+The two most important parameters are `prompt` (what to do) and `url` (where to start). Beyond those, `data_extraction_schema` defines the shape of structured output, `max_steps` caps the number of AI decision cycles (which controls cost), and `webhook_url` lets you receive async notifications when the task completes. See [Task Parameters](/running-automations/task-parameters) for the full list.
+
+Tasks are best for one-off automations, quick data extraction, and prototyping. When a single task isn't enough, you have two options for multi-step work:
-| Property | Description |
-|----------|-------------|
-| `prompt` | Natural language description of the goal (required) |
-| `url` | Starting URL for the task |
-| `data_extraction_schema` | JSON Schema defining expected output structure |
-| `max_steps` | Maximum steps allowed (controls cost) |
-| `engine` | AI model to use (see [Engines](#engines) below) |
-| `browser_session_id` | Run in an existing browser session |
-| `webhook_url` | Callback URL for async completion |
+<CardGroup cols={2}>
+ <Card
+ title="Browser Automation (Code)"
+ href="#browser-automation"
+ >
+ Write multi-step automations in Python or TypeScript with full Playwright control. Version, test, and deploy automation code like any other software.
+ </Card>
+ <Card
+ title="Workflows (Visual)"
+ href="#workflows"
+ >
+ Build multi-step automations visually in the Cloud UI with drag-and-drop blocks. No code required. Share templates across your team.
+ </Card>
+</CardGroup>
+
+## Browser Automation
+
+Browser Automation is the code-first way to build multi-step automations. The Skyvern SDK connects to a cloud Chromium instance over CDP, layers Playwright on top, and injects AI into every page interaction. There are three layers that nest inside each other: Browser, Page, and Agent.
+
+### Browser
+
+Every code-based automation starts by launching a browser. A Browser is a cloud Chromium instance with a Playwright context. Cookies, storage, and auth state persist across every page you open inside it.
+
+```python
+browser = await skyvern.launch_cloud_browser()
+page = await browser.get_working_page()
+
+await page.goto("https://example.com")
+# ... work across multiple pages ...
+
+await browser.close()
+```
-**Use Tasks for:** one-off automations, quick data extraction, prototyping before building a workflow.
+One browser per run. All pages share the same session state.
-When you need reusable, multi-step automations, use **Workflows** instead.
+### Page
----
+A Page wraps a Playwright page with AI. Standard Playwright calls like `goto`, `click("#id")`, and `fill` work as-is. AI actions work without selectors: Skyvern screenshots the page and decides what to interact with from your prompt.
+
+```python
+# AI actions: no selectors needed
+await page.act("Click the login button")
+data = await page.extract("Extract all product names and prices")
+is_ok = await page.validate("The cart has 3 items")
+
+# AI-enhanced Playwright: try the selector first, fall back to AI if it fails
+await page.click("#checkout", prompt="Click the checkout button")
+await page.fill("#email", value="[email protected]", prompt="Fill the email field")
+```
+
+Selectors are fast and deterministic. AI prompts survive layout changes. You can combine both in the same automation, using selectors for stable elements and AI for things that move around.
+
+### Agent
+
+An Agent runs complete multi-step AI tasks inside a page you already have open. It reuses the current page with its cookies, login state, and navigation history. You control when to hand off to the agent and when to take back control.
+
+```python
+browser = await skyvern.launch_cloud_browser()
+page = await browser.get_working_page()
+
+await page.goto("https://app.example.com")
+await page.agent.login(credential_type="skyvern", credential_id="cred_123")
+
+# The page is now logged in. Hand off a complex goal to the agent.
+result = await page.agent.run_task(
+ "Go to billing, download the latest invoice"
+)
+
+# Or trigger a workflow you built in the Cloud UI
+await page.agent.run_workflow("wpid_monthly_report")
+
+await browser.close()
+```
+
+Agents are useful when you want to mix precise Playwright control with open-ended AI goals. Log in with a direct call, then hand off "find and download the invoice" to the agent, then take back control to process the file.
+
+<Note>
+Full method reference: [Page](/sdk-reference/browser-automation/act), [Agent](/sdk-reference/browser-automation/agent-run-task), [Browser](/sdk-reference/browser-automation/launch-cloud-browser). Developer guide: [Multi-Step Automations](/browser-automations/overview).
+</Note>
## Workflows
-A **Workflow** is a reusable template composed of blocks. Unlike tasks, workflows can be versioned, shared across your team, and executed repeatedly with different parameters.
+A Workflow is a reusable automation template built in the [Cloud UI workflow editor](/cloud/building-workflows/build-a-workflow). You drag and drop blocks onto a canvas, wire them together, and save. Workflows can be versioned, shared across your team, scheduled on a cron, and run repeatedly with different parameters.
```mermaid
flowchart LR
@@ -65,80 +129,31 @@ flowchart LR
end
```
-> **Parameters:** `{{search_query}}`, `{{max_price}}`
-> Each block can reference outputs from previous blocks.
+Each block can reference outputs from previous blocks using Jinja templating: `{{search_query}}` for parameters, `{{extract_block.product_name}}` for upstream block outputs.
-```python
-result = await skyvern.run_workflow(
- workflow_id="wpid_abc123",
- parameters={
- "search_query": "wireless headphones",
- "max_price": 100
- }
-)
-
-print(result.output)
-```
-
-Workflows support Jinja templating:
-- Reference parameters: `{{search_query}}`
-- Reference previous block outputs: `{{extract_block.product_name}}`
-
-**Use Workflows for:** repeatable automations, multi-step processes, team-shared templates, complex logic with loops or conditionals.
-
-See [Workflow Blocks](/multi-step-automations/workflow-blocks-reference) for the full block reference.
-
----
-
-## Blocks
+Workflows are the right choice when you want no-code automation, team-shared templates, scheduled recurring jobs, or visual drag-and-drop logic.
-Blocks are the building units of workflows. Each block performs one specific task, and blocks execute sequentially—each can reference outputs from previous blocks.
+<Tip>
+**Building workflows?** See the [Workflow Editor guide](/cloud/building-workflows/build-a-workflow). **Need to trigger a workflow from code?** See [Run from Code](/cloud/building-workflows/run-from-code) in the Cloud UI docs.
+</Tip>
-### Navigation & Interaction
+### Blocks
-| Block | Purpose |
-|-------|---------|
-| **Navigation** | AI-guided navigation toward a goal—Skyvern figures out the clicks and inputs |
-| **Action** | Perform a single specific action (click, type, select, upload) |
-| **Go to URL** | Navigate directly to a specific URL |
-| **Login** | Authenticate using stored credentials |
-| **Wait** | Pause execution for a specified duration |
-| **Human Interaction** | Pause for manual intervention (CAPTCHA, approval, etc.) |
+Blocks are the building units of workflows. Each block performs one operation.
-### Data & Files
+**Navigation and interaction:** Navigate (AI-guided navigation toward a goal), Action (click, type, select, upload), Go to URL (direct navigation), Login (authenticate with stored credentials), Wait (pause for a duration), and Human Interaction (pause for manual intervention).
-| Block | Purpose |
-|-------|---------|
-| **Extract** | Pull structured data from a page into JSON |
-| **File Download** | Download files from websites |
-| **File Upload** | Upload files to form fields |
-| **File Parser** | Process PDFs, CSVs, and Excel files |
-| **PDF Parser** | Specialized PDF text extraction |
+**Data and files:** Extract (pull structured data into JSON), File Download, File Upload, File Parser (PDFs, CSVs, Excel), and PDF Parser (specialized text extraction).
-### Logic & Control Flow
+**Logic and control flow:** Conditional (if/else branching), For Loop (repeat over a list), Validation (assert conditions, halt on failure), and Code (custom Python/Playwright scripts).
-| Block | Purpose |
-|-------|---------|
-| **Conditional** | Branch workflow based on conditions (if/else) |
-| **For Loop** | Repeat a sequence of blocks over a list |
-| **Validation** | Assert conditions; halt workflow on failure |
-| **Code** | Execute custom Python/Playwright scripts |
+**Communication:** HTTP Request (external API calls), Text Prompt (text-only LLM prompt, no browser), and Send Email.
-### Communication & Integration
-
-| Block | Purpose |
-|-------|---------|
-| **HTTP Request** | Make API calls to external services |
-| **Text Prompt** | Text-only LLM prompt (no browser interaction) |
-| **Send Email** | Send email messages |
-
-For detailed block configuration, see [Workflow Blocks](/workflows/workflow-blocks-details).
-
----
+For detailed block configuration, see [Block Types and Configuration](/cloud/building-workflows/configure-blocks).
## Runs
-Every time you execute a task or workflow, Skyvern creates a **Run** to track progress and store outputs.
+Every time you execute a task or kick off a workflow, Skyvern creates a Run to track progress and store outputs. A run moves through a lifecycle:
```mermaid
flowchart LR
@@ -161,32 +176,15 @@ print(result.status) # "completed"
print(result.output) # {"heading": "Welcome"}
```
-**Run identifiers:**
-- Task runs: `tsk_*` prefix
-- Workflow runs: `wr_*` prefix
-
-**Run response fields:**
-
-| Field | Description |
-|-------|-------------|
-| `run_id` | Unique identifier |
-| `status` | Current lifecycle state |
-| `output` | Extracted data (matches your schema) |
-| `recording_url` | Video of the execution |
-| `screenshot_urls` | Screenshots captured during execution |
-| `downloaded_files` | Files retrieved (with URLs and checksums) |
-| `failure_reason` | Error details if failed |
-| `step_count` | Number of steps taken |
+Task runs get a `tsk_` prefix, workflow runs get `wr_`. The response includes the `run_id`, `status`, `output` (matching your extraction schema), `recording_url`, `screenshot_urls`, `downloaded_files`, `failure_reason` (if something went wrong), and `step_count`.
<Warning>
-**Billing:** You're billed per step. A step is one AI decision + action cycle. Use `max_steps` to cap costs during development.
+You're billed per step. A step is one AI decision + action cycle. Use `max_steps` to cap costs during development.
</Warning>
----
-
## Schedules
-A **Schedule** runs a workflow automatically on a recurring basis. You define a cron expression and timezone, and Skyvern triggers the workflow at each interval.
+A Schedule runs a workflow automatically on a recurring basis. You define a cron expression and timezone, and Skyvern triggers the workflow at each interval.
<CodeGroup>
```python Python
@@ -211,22 +209,11 @@ const result = await skyvern.agent.createWorkflowSchedule("wpid_abc123", {
```
</CodeGroup>
-**Key properties:**
-
-| Property | Description |
-|----------|-------------|
-| `cron_expression` | 5-field cron expression defining the recurrence (minimum 5-minute interval) |
-| `timezone` | IANA timezone identifier (e.g., `America/New_York`) |
-| `parameters` | Workflow parameters passed to each scheduled run |
-| `enabled` | `true` (active) or `false` (paused) |
-
-**Use Schedules for:** recurring data extraction, periodic report generation, daily monitoring tasks, any workflow you want to run without manual intervention.
-
----
+The `cron_expression` is a standard 5-field cron (minimum 5-minute interval), `timezone` is an IANA identifier like `America/New_York`, and `parameters` are passed to each scheduled run. You can pause a schedule by setting `enabled` to `false`.
## Credentials
-Credentials provide secure storage for authentication data. Skyvern encrypts credentials at rest and in transit, and injects them directly into the browser—**credentials are never sent to or seen by the LLM**.
+Credentials provide secure storage for authentication data. Skyvern encrypts credentials at rest and in transit, injects them directly into the browser, and never sends them to the LLM.
```mermaid
flowchart TD
@@ -236,24 +223,13 @@ flowchart TD
D --> E["LLM sees: 'login happened'<br/>LLM never sees: actual credentials"]
```
-**Supported credential types:**
-- Usernames and passwords
-- TOTP codes (authenticator apps)
-- Credit cards
+Supported credential types are usernames and passwords, TOTP codes (authenticator apps), and credit cards. You can store them in Skyvern's native encrypted storage, or sync from Bitwarden, 1Password, Azure Key Vault, or a custom HTTP vault.
-**Credential sources:**
-- **Skyvern** — Native encrypted storage
-- **Bitwarden** — Sync from your Bitwarden vault
-- **1Password** — Sync from your 1Password vault
-- **Azure Key Vault** — Enterprise secret management
+See [Credentials](/sdk-reference/credentials/create-credential) for setup instructions.
-See [Credentials](/sdk-reference/credentials) for setup instructions.
+## Browser Sessions and Profiles
----
-
-## Browser Sessions & Profiles
-
-Skyvern offers two ways to manage browser state across runs:
+Skyvern offers two ways to manage browser state across runs.
```mermaid
flowchart LR
@@ -267,69 +243,45 @@ flowchart LR
B -- "restore" --> A
```
-| | Browser Session | Browser Profile |
-|---|---|---|
-| **Lifetime** | Expires after timeout (max 24h) | Persists indefinitely |
-| **Use case** | Real-time task chaining | Skip login on repeated runs |
-| **Sharing** | Single use | Shared across team |
-
-### Browser Sessions
-
-A live browser instance that maintains state across multiple tasks. Use sessions when you need to chain tasks in real-time or allow human intervention.
+**Browser Sessions** are live browser instances that maintain state across multiple operations. Cookies, storage, and page context persist for the duration of the session (up to 24 hours). They're useful for chaining operations in real-time or allowing human intervention between steps.
```python
-# Create a session (default: 60 minutes, max: 24 hours)
-session = await skyvern.create_browser_session(timeout=120)
-
-# Run tasks in the same session
-await skyvern.run_task(
- prompt="Log in with the test account",
- url="https://example.com/login",
- browser_session_id=session.browser_session_id
-)
+browser = await skyvern.launch_cloud_browser()
+page = await browser.get_working_page()
-# Second task reuses the authenticated state
-await skyvern.run_task(
- prompt="Extract the account balance",
- url="https://example.com/dashboard",
- browser_session_id=session.browser_session_id
-)
-
-# Clean up
-await skyvern.close_browser_session(
- browser_session_id=session.browser_session_id
-)
-```
+await page.goto("https://example.com/login")
+await page.agent.login(credential_type="skyvern", credential_id="cred_123")
-**Session limits:** 5 to 1,440 minutes (24 hours max). Default: 60 minutes.
+# Authenticated state persists. Extract data from another page.
+await page.goto("https://example.com/dashboard")
+balance = await page.extract("Extract the account balance")
-### Browser Profiles
+await browser.close()
+```
-A saved snapshot of browser state. Unlike sessions, profiles persist indefinitely and can be reused across days or weeks—perfect for skipping login on repeated runs.
+**Browser Profiles** are saved snapshots of browser state (cookies, auth tokens, local storage, session storage). Unlike sessions, profiles persist indefinitely and can be reused across days or weeks, which makes them ideal for skipping login on repeated runs.
```python
-# Create a profile from a completed run
profile = await skyvern.create_browser_profile(
name="my-authenticated-profile",
workflow_run_id=run.run_id
)
-# Future runs restore the authenticated state
-await skyvern.run_workflow(
- workflow_id="wpid_extract_data",
+# Future runs restore the authenticated state without logging in again.
+browser = await skyvern.launch_cloud_browser(
browser_profile_id=profile.browser_profile_id
)
+page = await browser.get_working_page()
+await page.goto("https://example.com/dashboard")
+data = await page.extract("Extract the monthly report data")
+await browser.close()
```
-**What's saved:** Cookies, authentication tokens, local storage, session storage.
-
See [Browser Sessions](/optimization/browser-sessions) for details.
----
-
## Artifacts
-Every run generates artifacts for observability, debugging, and audit trails.
+Every run generates artifacts for observability, debugging, and audit trails: end-to-end video recordings, screenshots captured after each action, downloaded files, JSON-structured logs at step/task/workflow levels, and HAR files for network debugging.
```python
result = await skyvern.run_task(
@@ -342,31 +294,11 @@ print(result.screenshot_urls) # List of screenshot URLs
print(result.downloaded_files) # [{"url": "...", "checksum": "..."}]
```
-| Artifact | Description |
-|----------|-------------|
-| **Recordings** | End-to-end video of the entire run |
-| **Screenshots** | Captured after each action |
-| **Downloaded files** | Files retrieved during execution |
-| **Logs** | JSON-structured logs at step, task, and workflow levels |
-| **HAR files** | HTTP Archive data for network debugging |
-
-In the Skyvern UI, go to **Runs** → click a run → view the **Actions** and **Recording** tabs.
-
----
+In the Skyvern UI, go to **Runs**, click a run, and view the **Actions** and **Recording** tabs.
## Engines
-Skyvern supports multiple AI engines for task execution:
-
-| Engine | Description |
-|--------|-------------|
-| `skyvern-1.0` | Default Skyvern model — fast, precise, ideal for simple tasks |
-| `skyvern-2.0` | Latest Skyvern model — flexible, handles complex multi-step tasks |
-| `openai-cua` | OpenAI Computer Use Agent |
-| `anthropic-cua` | Anthropic Computer Use Agent |
-| `ui-tars` | UI-TARS model |
-
-Specify the engine when running a task:
+Skyvern supports multiple AI engines. `skyvern-2.0` is the latest and default for the Cloud UI (the SDK defaults to `skyvern-1.0`). Other options include `openai-cua` (OpenAI Computer Use Agent), `anthropic-cua` (Anthropic Computer Use Agent), and `ui-tars`.
```python
from skyvern.schemas.runs import RunEngine
@@ -378,34 +310,30 @@ result = await skyvern.run_task(
)
```
----
-
## Quick Reference
| I want to... | Use |
|--------------|-----|
| Run a one-off automation | [Task](#tasks) |
-| Build a reusable multi-step process | [Workflow](#workflows) |
-| Keep a browser open between tasks | [Browser Session](#browser-sessions) |
-| Skip login on repeated runs | [Browser Profile](#browser-profiles) |
+| Build multi-step automation in code | [Browser Automation](#browser-automation) |
+| Build multi-step automation visually | [Workflow](#workflows) |
+| Trigger a UI-built workflow from code | [Run from Code](/cloud/building-workflows/run-from-code) |
+| Keep a browser open between operations | [Browser Session](#browser-sessions-and-profiles) |
+| Skip login on repeated runs | [Browser Profile](#browser-sessions-and-profiles) |
| Store secrets securely | [Credentials](#credentials) |
| Debug a failed run | [Artifacts](#artifacts) |
----
-
## Choose your path
<CardGroup cols={2}>
<Card
title="Use the dashboard"
- icon="window-maximize"
href="/cloud/getting-started/overview"
>
- Run tasks, build workflows visually, and monitor runs — no code required.
+ Run tasks, build workflows visually, and monitor runs. No code required.
</Card>
<Card
title="Build with the API"
- icon="code"
href="/getting-started/quickstart"
>
Integrate Skyvern into your product with Python, TypeScript, or REST.
@@ -415,14 +343,12 @@ result = await skyvern.run_task(
<CardGroup cols={2}>
<Card
title="AI Agents Quickstart"
- icon="robot"
href="/getting-started/ai-agents-quickstart"
>
- Give Claude Code, Cursor, or Windsurf full browser automation via MCP.
+ Give Claude Code, Cursor, or Windsurf browser automation via MCP.
</Card>
<Card
title="Self-host Skyvern"
- icon="server"
href="/self-hosted/overview"
>
Deploy on your own infrastructure with your own LLM keys.
diff --git a/docs/snippets/introduction-content.mdx b/docs/snippets/introduction-content.mdx
index 1c1c30e7e..7511b3f46 100644
--- a/docs/snippets/introduction-content.mdx
+++ b/docs/snippets/introduction-content.mdx
@@ -59,5 +59,5 @@ Most browser automation breaks down at authentication, CAPTCHAs, or dynamic cont
Now that you understand how Skyvern works under the hood, learn the eight building blocks you'll use to create any automation.
<Card title="Core Concepts →" icon="book-open" href="/getting-started/core-concepts">
- Tasks, workflows, blocks, runs, credentials, browser sessions, engines — everything you need to know before you start building.
+ Tasks, workflows, blocks, runs, credentials, browser sessions, engines: everything you need to know before you start building.
</Card>
diff --git a/docs/snippets/schema-builder.mdx b/docs/snippets/schema-builder.mdx
new file mode 100644
index 000000000..66d27ab03
--- /dev/null
+++ b/docs/snippets/schema-builder.mdx
@@ -0,0 +1,192 @@
+export const FIELD_TYPES = [
+ { value: "string", label: "String" },
+ { value: "number", label: "Number" },
+ { value: "integer", label: "Integer" },
+ { value: "boolean", label: "Boolean" },
+]
+
+export const SchemaBuilder = () => {
+ const [schemaType, setSchemaType] = useState("single")
+ const [arrayName, setArrayName] = useState("items")
+ const [fields, setFields] = useState([
+ { id: "1", name: "title", type: "string", description: "The title" },
+ ])
+ const [outputFormat, setOutputFormat] = useState("python")
+ const [copied, setCopied] = useState(false)
+
+ const addField = () => {
+ setFields([...fields, { id: String(Date.now()), name: "", type: "string", description: "" }])
+ }
+
+ const removeField = (id) => {
+ if (fields.length > 1) setFields(fields.filter((f) => f.id !== id))
+ }
+
+ const updateField = (id, key, value) => {
+ setFields(fields.map((f) => (f.id === id ? { ...f, [key]: value } : f)))
+ }
+
+ const duplicateNames = useMemo(() => {
+ const names = fields.map((f) => f.name).filter((n) => n.trim() !== "")
+ const counts = {}
+ for (const n of names) {
+ counts[n] = (counts[n] || 0) + 1
+ }
+ return new Set(Object.keys(counts).filter((n) => counts[n] > 1))
+ }, [fields])
+
+ const schema = useMemo(() => {
+ const properties = {}
+ fields.forEach((field) => {
+ if (field.name) {
+ properties[field.name] = {
+ type: field.type,
+ description: field.description || `The ${field.name}`,
+ }
+ }
+ })
+ if (schemaType === "array") {
+ return {
+ type: "object",
+ properties: {
+ [arrayName]: {
+ type: "array",
+ description: "List of extracted items",
+ items: { type: "object", properties },
+ },
+ },
+ }
+ }
+ return { type: "object", properties }
+ }, [fields, schemaType, arrayName])
+
+ const formattedOutput = useMemo(() => {
+ const jsonStr = JSON.stringify(schema, null, 2)
+ if (outputFormat === "python") {
+ return `data_extraction_schema=${jsonStr.replace(/: null/g, ": None").replace(/: true/g, ": True").replace(/: false/g, ": False")}`
+ }
+ if (outputFormat === "typescript") {
+ return `data_extraction_schema: ${jsonStr}`
+ }
+ return `"data_extraction_schema": ${jsonStr}`
+ }, [schema, outputFormat])
+
+ const copyToClipboard = async () => {
+ await navigator.clipboard.writeText(formattedOutput)
+ setCopied(true)
+ setTimeout(() => setCopied(false), 2000)
+ }
+
+ return (
+ <div className="p-5 border rounded-lg mt-4 mb-4 not-prose" style={{ backgroundColor: "#f8fafc" }}>
+ <div className="mb-5">
+ <label className="block font-semibold mb-2 text-sm">What are you extracting?</label>
+ <div className="flex gap-3">
+ {[
+ { value: "single", label: "Single object", desc: "Extract one item with multiple fields" },
+ { value: "array", label: "List of items", desc: "Extract multiple items with the same structure" },
+ ].map((type) => (
+ <button
+ key={type.value}
+ onClick={() => setSchemaType(type.value)}
+ className={`flex-1 p-3 rounded-md text-left border-2 ${schemaType === type.value ? "border-indigo-500 bg-indigo-50" : "border-gray-200 bg-white"}`}
+ >
+ <div className="font-medium text-sm">{type.label}</div>
+ <div className="text-xs text-gray-500 mt-1">{type.desc}</div>
+ </button>
+ ))}
+ </div>
+ </div>
+
+ {schemaType === "array" && (
+ <div className="mb-5">
+ <label className="block text-xs font-medium mb-1 text-gray-700">Array field name</label>
+ <input
+ type="text"
+ value={arrayName}
+ onChange={(e) => setArrayName(e.target.value)}
+ className="w-full p-2 border rounded-md text-sm"
+ placeholder="items"
+ />
+ </div>
+ )}
+
+ <div className="mb-4">
+ <label className="block font-semibold mb-2 text-sm">Fields to extract</label>
+ <div className="flex flex-col gap-2">
+ {fields.map((field) => (
+ <div key={field.id} className="flex gap-2 items-center p-3 bg-white rounded-md border">
+ <input
+ type="text"
+ value={field.name}
+ onChange={(e) => updateField(field.id, "name", e.target.value)}
+ placeholder="Field name"
+ className={`w-32 p-2 border rounded-md text-sm ${duplicateNames.has(field.name) ? "border-red-500 bg-red-50" : ""}`}
+ title={duplicateNames.has(field.name) ? "Duplicate field name - will be overwritten in schema" : ""}
+ />
+ <select
+ value={field.type}
+ onChange={(e) => updateField(field.id, "type", e.target.value)}
+ className="w-24 p-2 border rounded-md text-sm bg-white"
+ >
+ {FIELD_TYPES.map((t) => (
+ <option key={t.value} value={t.value}>{t.label}</option>
+ ))}
+ </select>
+ <input
+ type="text"
+ value={field.description}
+ onChange={(e) => updateField(field.id, "description", e.target.value)}
+ placeholder="Description (helps AI understand what to extract)"
+ className="flex-1 p-2 border rounded-md text-sm"
+ />
+ <button
+ onClick={() => removeField(field.id)}
+ disabled={fields.length === 1}
+ className={`px-2 py-1 rounded text-lg ${fields.length === 1 ? "text-gray-300 cursor-not-allowed" : "text-red-500 hover:bg-red-50"}`}
+ >
+ ×
+ </button>
+ </div>
+ ))}
+ </div>
+ <button onClick={addField} className="w-full mt-2 p-2 border border-dashed rounded-md text-gray-500 text-sm hover:bg-gray-50">
+ + Add field
+ </button>
+ {duplicateNames.size > 0 && (
+ <div className="mt-2 p-2 bg-red-50 border border-red-200 rounded-md text-red-700 text-xs">
+ Duplicate field names detected. Only the last field with each name will appear in the schema.
+ </div>
+ )}
+ </div>
+
+ <div>
+ <div className="flex justify-between items-center mb-2">
+ <label className="font-semibold text-sm">Generated schema</label>
+ <div className="flex gap-1">
+ {["python", "typescript", "curl"].map((format) => (
+ <button
+ key={format}
+ onClick={() => setOutputFormat(format)}
+ className={`px-3 py-1 rounded text-xs ${outputFormat === format ? "bg-indigo-100 border-indigo-500 border font-medium" : "bg-white border border-gray-200"}`}
+ >
+ {format === "curl" ? "cURL" : format.charAt(0).toUpperCase() + format.slice(1)}
+ </button>
+ ))}
+ </div>
+ </div>
+ <div className="relative">
+ <pre className="bg-slate-800 text-slate-200 p-4 rounded-md overflow-auto text-xs leading-relaxed">
+ <code>{formattedOutput}</code>
+ </pre>
+ <button
+ onClick={copyToClipboard}
+ className={`absolute top-2 right-2 px-3 py-1 rounded text-xs text-white ${copied ? "bg-green-500" : "bg-slate-600 hover:bg-slate-500"}`}
+ >
+ {copied ? "Copied!" : "Copy"}
+ </button>
+ </div>
+ </div>
+ </div>
+ )
+}
diff --git a/docs/ts-sdk-reference/browser-automation.mdx b/docs/ts-sdk-reference/browser-automation.mdx
deleted file mode 100644
index a995e9a01..000000000
--- a/docs/ts-sdk-reference/browser-automation.mdx
+++ /dev/null
@@ -1,419 +0,0 @@
----
-title: Browser Automation
-subtitle: Control cloud browsers with Playwright + AI
-description: Use the Skyvern TypeScript SDK to launch cloud browsers with Playwright integration, run AI-powered tasks, and use enhanced click, fill, and selectOption methods that fall back to natural language selectors.
-slug: ts-sdk-reference/browser-automation
-keywords:
- - Playwright
- - launchCloudBrowser
- - useCloudBrowser
- - connectToBrowserOverCdp
- - act
- - extract
- - validate
- - prompt
- - click
- - fill
- - selectOption
- - AI fallback
- - cloud browser
- - agent
----
-
-The TypeScript SDK extends Playwright with AI-powered browser automation. Launch a cloud browser, get a page that works like a normal Playwright `Page`, then use `.agent` for full-task AI execution or AI-enhanced versions of `click`, `fill`, and `selectOption` that fall back to natural language when selectors fail.
-
----
-
-## Launch a cloud browser
-
-### `launchCloudBrowser`
-
-Create a new cloud-hosted browser session and connect to it.
-
-```typescript
-const browser = await skyvern.launchCloudBrowser();
-const page = await browser.getWorkingPage();
-
-// Use Playwright methods
-await page.goto("https://example.com");
-
-// Or use AI
-await page.agent.runTask("Fill out the contact form and submit it");
-
-await browser.close();
-```
-
-#### Parameters
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `timeout` | `number` | No | `60` | Session timeout in minutes (5–1440). |
-| `proxyLocation` | `ProxyLocation` | No | `undefined` | Geographic proxy location for browser traffic. |
-
-#### Returns `SkyvernBrowser`
-
-<Note>
-Cloud browser sessions are only available with `SkyvernEnvironment.Cloud` or `SkyvernEnvironment.Staging`.
-</Note>
-
----
-
-### `useCloudBrowser`
-
-Get or create a cloud browser session. Reuses the most recent available session if one exists, otherwise creates a new one.
-
-```typescript
-const browser = await skyvern.useCloudBrowser();
-const page = await browser.getWorkingPage();
-```
-
-#### Parameters
-
-Same as `launchCloudBrowser`. Options are only used when creating a new session.
-
-#### Returns `SkyvernBrowser`
-
----
-
-### `connectToCloudBrowserSession`
-
-Connect to an existing cloud browser session by ID.
-
-```typescript
-const browser = await skyvern.connectToCloudBrowserSession("pbs_abc123");
-const page = await browser.getWorkingPage();
-```
-
-#### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `browserSessionId` | `string` | Yes | The ID of the cloud browser session. |
-
-#### Returns `SkyvernBrowser`
-
----
-
-### `connectToBrowserOverCdp`
-
-Connect to any browser running with Chrome DevTools Protocol (CDP) enabled, whether local or remote.
-
-```typescript
-const browser = await skyvern.connectToBrowserOverCdp("http://localhost:9222");
-const page = await browser.getWorkingPage();
-```
-
-#### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `cdpUrl` | `string` | Yes | The CDP WebSocket URL (e.g., `"http://localhost:9222"`). |
-
-#### Returns `SkyvernBrowser`
-
----
-
-## SkyvernBrowser
-
-A browser context wrapper that provides Skyvern-enabled pages.
-
-### `getWorkingPage()`
-
-Get the most recent page or create a new one if none exists.
-
-```typescript
-const page = await browser.getWorkingPage();
-```
-
-### `newPage()`
-
-Create a new page (tab) in the browser context.
-
-```typescript
-const page = await browser.newPage();
-```
-
-### `close()`
-
-Close the browser and release resources. If connected to a cloud session, also closes the session.
-
-```typescript
-await browser.close();
-```
-
----
-
-## SkyvernBrowserPage
-
-A `SkyvernBrowserPage` extends Playwright's `Page` with AI capabilities. Every standard Playwright method (`goto`, `click`, `fill`, `waitForSelector`, etc.) works as-is. Additionally, it provides:
-
-- **`page.agent`** — AI-powered task execution (full automations)
-- **AI-enhanced `click`, `fill`, `selectOption`** — try selectors first, fall back to AI
-- **`page.act`, `page.extract`, `page.validate`, `page.prompt`** — single AI actions
-
----
-
-### AI-enhanced Playwright methods
-
-These methods extend the standard Playwright API with AI fallback. Pass a CSS selector and it works like normal Playwright. Add a `prompt` option and if the selector fails, AI takes over.
-
-#### `click`
-
-```typescript
-// Standard Playwright click
-await page.click("#submit-button");
-
-// AI-powered click (no selector needed)
-await page.click({ prompt: "Click the 'Submit' button" });
-
-// Selector with AI fallback
-await page.click("#submit-button", { prompt: "Click the 'Submit' button" });
-```
-
-#### `fill`
-
-```typescript
-// Standard Playwright fill
-await page.fill("#email", "[email protected]");
-
-// AI-powered fill
-await page.fill({ prompt: "Fill '[email protected]' in the email field" });
-
-// Selector with AI fallback
-await page.fill("#email", "[email protected]", {
- prompt: "Fill the email address field",
-});
-```
-
-#### `selectOption`
-
-```typescript
-// Standard Playwright select
-await page.selectOption("#country", "us");
-
-// AI-powered select
-await page.selectOption({ prompt: "Select 'United States' from the country dropdown" });
-
-// Selector with AI fallback
-await page.selectOption("#country", "us", {
- prompt: "Select United States from country",
-});
-```
-
----
-
-### `page.agent` — Full task execution
-
-The `agent` property provides methods for running complete AI-powered automations within the browser page context. These always wait for completion.
-
-#### `agent.runTask`
-
-Run a complete AI task in the context of the current page.
-
-```typescript
-const result = await page.agent.runTask("Fill out the contact form and submit it", {
- dataExtractionSchema: {
- type: "object",
- properties: {
- confirmation_number: { type: "string" },
- },
- },
-});
-console.log(result.output);
-```
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `prompt` | `string` | Yes | Natural language task description. |
-| `options.engine` | `RunEngine` | No | AI engine to use. |
-| `options.url` | `string` | No | URL to navigate to. Defaults to current page URL. |
-| `options.dataExtractionSchema` | `Record<string, unknown> \| string` | No | JSON schema for output. |
-| `options.maxSteps` | `number` | No | Maximum AI steps. |
-| `options.timeout` | `number` | No | Max wait time in seconds. Default: `1800`. |
-| `options.webhookUrl` | `string` | No | Webhook URL for notifications. |
-| `options.totpIdentifier` | `string` | No | TOTP identifier. |
-| `options.totpUrl` | `string` | No | TOTP URL. |
-| `options.title` | `string` | No | Run display name. |
-| `options.errorCodeMapping` | `Record<string, string>` | No | Custom error code mapping. |
-| `options.model` | `Record<string, unknown>` | No | LLM model configuration. |
-
-Returns `TaskRunResponse`.
-
-#### `agent.login`
-
-Run a login workflow in the context of the current page. Supports multiple credential providers via overloaded signatures.
-
-```typescript
-// Skyvern credentials
-await page.agent.login("skyvern", {
- credentialId: "cred_123",
-});
-
-// Bitwarden
-await page.agent.login("bitwarden", {
- bitwardenItemId: "item_id",
- bitwardenCollectionId: "collection_id",
-});
-
-// 1Password
-await page.agent.login("1password", {
- onepasswordVaultId: "vault_id",
- onepasswordItemId: "item_id",
-});
-
-// Azure Vault
-await page.agent.login("azure_vault", {
- azureVaultName: "vault_name",
- azureVaultUsernameKey: "username_key",
- azureVaultPasswordKey: "password_key",
-});
-```
-
-Returns `WorkflowRunResponse`.
-
-#### `agent.downloadFiles`
-
-Download files in the context of the current page.
-
-```typescript
-const result = await page.agent.downloadFiles("Download the latest invoice PDF", {
- downloadSuffix: ".pdf",
- downloadTimeout: 30,
-});
-```
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `prompt` | `string` | Yes | What to download. |
-| `options.url` | `string` | No | URL to navigate to. Defaults to current page URL. |
-| `options.downloadSuffix` | `string` | No | Expected file extension. |
-| `options.downloadTimeout` | `number` | No | Download timeout in seconds. |
-| `options.maxStepsPerRun` | `number` | No | Max AI steps. |
-| `options.timeout` | `number` | No | Max wait time in seconds. Default: `1800`. |
-
-Returns `WorkflowRunResponse`.
-
-#### `agent.runWorkflow`
-
-Run a pre-defined workflow in the context of the current page.
-
-```typescript
-const result = await page.agent.runWorkflow("wpid_abc123", {
- parameters: { company_name: "Acme Corp" },
-});
-console.log(result.output);
-```
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `workflowId` | `string` | Yes | The workflow permanent ID. |
-| `options.parameters` | `Record<string, unknown>` | No | Workflow input parameters. |
-| `options.template` | `boolean` | No | Whether it's a template. |
-| `options.title` | `string` | No | Run display name. |
-| `options.timeout` | `number` | No | Max wait time in seconds. Default: `1800`. |
-
-Returns `WorkflowRunResponse`.
-
----
-
-### Single AI actions
-
-#### `act`
-
-Perform a single AI action on the page.
-
-```typescript
-await page.act("Scroll down and click the 'Load More' button");
-```
-
-#### `extract`
-
-Extract structured data from the current page.
-
-```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: "string" },
- },
- },
- },
-});
-console.log(data);
-```
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `prompt` | `string` | Yes | What to extract. |
-| `schema` | `Record<string, unknown> \| unknown[] \| string` | No | JSON schema for output. |
-| `errorCodeMapping` | `Record<string, string>` | No | Custom error codes. |
-
-Returns `Record<string, unknown> | unknown[] | string | null`.
-
-#### `validate`
-
-Validate the current page state with AI.
-
-```typescript
-const isLoggedIn = await page.validate("Check if the user is logged in");
-console.log(isLoggedIn); // true or false
-```
-
-Returns `boolean`.
-
-#### `prompt`
-
-Send a prompt to the LLM and get a structured response.
-
-```typescript
-const result = await page.prompt(
- "What is the main heading on this page?",
- { heading: { type: "string" } },
-);
-console.log(result);
-```
-
-Returns `Record<string, unknown> | unknown[] | string | null`.
-
----
-
-## Complete example
-
-```typescript
-import { Skyvern } from "@skyvern/client";
-
-const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
-const browser = await skyvern.launchCloudBrowser();
-const page = await browser.getWorkingPage();
-
-// Navigate with Playwright
-await page.goto("https://app.example.com");
-
-// Login with AI
-await page.agent.login("skyvern", { credentialId: "cred_abc123" });
-
-// Extract data with AI
-const data = await page.extract({
- prompt: "Extract all invoice numbers and amounts from the billing page",
- schema: {
- type: "array",
- items: {
- type: "object",
- properties: {
- invoice_number: { type: "string" },
- amount: { type: "string" },
- },
- },
- },
-});
-console.log(data);
-
-// Clean up
-await browser.close();
-await skyvern.close();
-```
diff --git a/docs/ts-sdk-reference/browser-profiles.mdx b/docs/ts-sdk-reference/browser-profiles.mdx
deleted file mode 100644
index 222049241..000000000
--- a/docs/ts-sdk-reference/browser-profiles.mdx
+++ /dev/null
@@ -1,145 +0,0 @@
----
-title: Browser Profiles
-subtitle: Save and reuse browser state across runs
-description: Use the Skyvern TypeScript SDK to create, list, and delete browser profiles that snapshot cookies and session data for reuse across workflow runs.
-slug: ts-sdk-reference/browser-profiles
-keywords:
- - createBrowserProfile
- - listBrowserProfiles
- - getBrowserProfile
- - deleteBrowserProfile
- - cookies
- - session snapshot
- - persistent state
- - reuse
----
-
-A browser profile is a snapshot of browser state — cookies, local storage, session data. Create a profile from a completed run, then load it into future workflow runs to skip login and setup steps.
-
-For conceptual background, see [Browser Profiles](/optimization/browser-profiles).
-
----
-
-## `createBrowserProfile`
-
-Create a profile from a completed workflow run.
-
-```typescript
-const profile = await skyvern.createBrowserProfile({
- name: "production-login",
- workflow_run_id: "wr_abc123",
-});
-console.log(profile.browser_profile_id); // bpf_abc123
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `name` | `string` | Yes | Display name for the profile. |
-| `description` | `string` | No | Optional description. |
-| `workflow_run_id` | `string` | Conditional | The workflow run ID to snapshot. The run must have used `persist_browser_session: true`. Required if `browser_session_id` is not provided. |
-| `browser_session_id` | `string` | Conditional | The browser session ID to snapshot. Required if `workflow_run_id` is not provided. |
-
-You must provide either `workflow_run_id` or `browser_session_id`.
-
-### Returns `BrowserProfile`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `browser_profile_id` | `string` | Unique ID. Starts with `bpf_`. |
-| `name` | `string` | Profile name. |
-| `description` | `string \| undefined` | Profile description. |
-| `created_at` | `string` | When the profile was created. |
-
-### Example: Create a profile from a login workflow
-
-```typescript
-// Step 1: Run a workflow with persist_browser_session
-const run = await skyvern.runWorkflow({
- body: {
- workflow_id: "wpid_login_flow",
- parameters: { username: "[email protected]" },
- },
- waitForCompletion: true,
-});
-
-// Step 2: Create a profile from the run
-const profile = await skyvern.createBrowserProfile({
- name: "demo-account-login",
- workflow_run_id: run.run_id,
-});
-
-// Step 3: Use the profile in future runs (skip login)
-const result = await skyvern.runWorkflow({
- body: {
- workflow_id: "wpid_extract_invoices",
- browser_profile_id: profile.browser_profile_id,
- },
- waitForCompletion: true,
-});
-```
-
-<Info>
-Session archiving is asynchronous. If `createBrowserProfile` fails immediately after a workflow completes, wait a few seconds and retry.
-</Info>
-
----
-
-## `listBrowserProfiles`
-
-List all browser profiles.
-
-```typescript
-const profiles = await skyvern.listBrowserProfiles({});
-for (const p of profiles) {
- console.log(`${p.name} (${p.browser_profile_id})`);
-}
-```
-
-### Parameters
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `include_deleted` | `boolean` | No | `undefined` | Include soft-deleted profiles in the results. |
-
-### Returns `BrowserProfile[]`
-
----
-
-## `getBrowserProfile`
-
-Get a single profile by ID.
-
-```typescript
-const profile = await skyvern.getBrowserProfile("bpf_abc123");
-console.log(profile.name);
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `profileId` | `string` | Yes | The browser profile ID. |
-
-### Returns `BrowserProfile`
-
----
-
-## `deleteBrowserProfile`
-
-Delete a browser profile.
-
-```typescript
-await skyvern.deleteBrowserProfile("bpf_abc123");
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `profileId` | `string` | Yes | The browser profile ID to delete. |
-
-<Warning>
-`browser_profile_id` only works with `runWorkflow`, not `runTask`. If you pass it to `runTask`, it will be silently ignored.
-</Warning>
diff --git a/docs/ts-sdk-reference/browser-sessions.mdx b/docs/ts-sdk-reference/browser-sessions.mdx
deleted file mode 100644
index 5740d41fd..000000000
--- a/docs/ts-sdk-reference/browser-sessions.mdx
+++ /dev/null
@@ -1,134 +0,0 @@
----
-title: Browser Sessions
-subtitle: Maintain live browser state between API calls
-description: Use the Skyvern TypeScript SDK to create, retrieve, and close persistent browser sessions that preserve cookies and login state across multiple tasks.
-slug: ts-sdk-reference/browser-sessions
-keywords:
- - createBrowserSession
- - getBrowserSession
- - closeBrowserSession
- - persistent browser
- - session chaining
- - cookies
- - login state
- - proxy
----
-
-A browser session is a persistent browser instance that stays alive between API calls. Use sessions to chain multiple tasks in the same browser without losing cookies, local storage, or login state.
-
-For conceptual background, see [Browser Sessions](/optimization/browser-sessions).
-
----
-
-## `createBrowserSession`
-
-Spin up a new cloud browser session.
-
-```typescript
-const session = await skyvern.createBrowserSession({ timeout: 60 });
-console.log(session.browser_session_id); // pbs_abc123
-```
-
-### Parameters
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `timeout` | `number` | No | `60` | Session timeout in minutes (5–1440). Timer starts after the session is ready. |
-| `proxy_location` | `ProxyLocation` | No | `undefined` | Route browser traffic through a geographic proxy. |
-| `extensions` | `Extensions[]` | No | `undefined` | Browser extensions to install. Options: `"ad-blocker"`, `"captcha-solver"`. |
-| `browser_type` | `PersistentBrowserType` | No | `undefined` | Browser type. Options: `"chrome"`, `"msedge"`. |
-
-### Returns `BrowserSessionResponse`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `browser_session_id` | `string` | Unique ID. Starts with `pbs_`. |
-| `status` | `string \| undefined` | Current session status. |
-| `browser_address` | `string \| undefined` | CDP address for connecting to the browser. |
-| `app_url` | `string \| undefined` | Link to the live browser view in the Cloud UI. |
-| `timeout` | `number \| undefined` | Configured timeout in minutes. |
-| `started_at` | `string \| undefined` | When the session became ready. |
-| `created_at` | `string` | When the session was requested. |
-
-### Example: Chain multiple tasks in one session
-
-```typescript
-const session = await skyvern.createBrowserSession({});
-
-// Step 1: Log in
-await skyvern.runTask({
- body: {
- prompt: "Log in with username [email protected]",
- url: "https://app.example.com/login",
- browser_session_id: session.browser_session_id,
- },
- waitForCompletion: true,
-});
-
-// Step 2: Extract data (same browser, already logged in)
-const result = await skyvern.runTask({
- body: {
- prompt: "Go to the invoices page and extract all invoice numbers",
- browser_session_id: session.browser_session_id,
- },
- waitForCompletion: true,
-});
-console.log(result.output);
-
-// Clean up
-await skyvern.closeBrowserSession(session.browser_session_id);
-```
-
----
-
-## `getBrowserSession`
-
-Get the status and details of a session.
-
-```typescript
-const session = await skyvern.getBrowserSession("pbs_abc123");
-console.log(session.status, session.browser_address);
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `browserSessionId` | `string` | Yes | The session ID. |
-
-### Returns `BrowserSessionResponse`
-
----
-
-## `getBrowserSessions`
-
-List all active browser sessions.
-
-```typescript
-const sessions = await skyvern.getBrowserSessions();
-for (const s of sessions) {
- console.log(`${s.browser_session_id} — ${s.status}`);
-}
-```
-
-### Returns `BrowserSessionResponse[]`
-
----
-
-## `closeBrowserSession`
-
-Close a browser session and release its resources.
-
-```typescript
-await skyvern.closeBrowserSession("pbs_abc123");
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `browserSessionId` | `string` | Yes | The session ID to close. |
-
-<Warning>
-Closing a session is irreversible. Any unsaved state (cookies, local storage) is lost unless you created a [browser profile](/ts-sdk-reference/browser-profiles) from it.
-</Warning>
diff --git a/docs/ts-sdk-reference/complete-reference.mdx b/docs/ts-sdk-reference/complete-reference.mdx
deleted file mode 100644
index 9cc63312b..000000000
--- a/docs/ts-sdk-reference/complete-reference.mdx
+++ /dev/null
@@ -1,632 +0,0 @@
----
-title: Complete Reference (For LLMs)
-subtitle: Every method, parameter, and type in one page
-description: Complete TypeScript SDK reference covering every Skyvern client method, parameter, return type, and error class on a single page for quick lookup.
-slug: ts-sdk-reference/complete-reference
-keywords:
- - complete reference
- - all methods
- - runTask
- - runWorkflow
- - browser automation
- - Playwright
- - launchCloudBrowser
- - page.act
- - page.extract
- - page.agent
- - credential
- - error handling
----
-
-## Install and initialize
-
-```bash
-npm install @skyvern/client
-```
-
-```typescript
-import { Skyvern } from "@skyvern/client";
-
-const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
-
-const result = await skyvern.runTask({
- body: {
- prompt: "Get the title of the top post on Hacker News",
- url: "https://news.ycombinator.com",
- },
- waitForCompletion: true,
-});
-console.log(result.output);
-```
-
-**Constructor:**
-
-```typescript
-new Skyvern({
- apiKey: string, // Required
- baseUrl?: string, // Override for self-hosted deployments
- environment?: SkyvernEnvironment | string, // Cloud (default), Staging, or Local
- timeoutInSeconds?: number, // HTTP request timeout (default: 60)
- maxRetries?: number, // Retry count (default: 2)
- headers?: Record<string, string>, // Additional headers
-})
-```
-
-**Environments:**
-
-```typescript
-import { SkyvernEnvironment } from "@skyvern/client";
-// SkyvernEnvironment.Cloud → "https://api.skyvern.com"
-// SkyvernEnvironment.Staging → "https://api-staging.skyvern.com"
-// SkyvernEnvironment.Local → "http://localhost:8000"
-```
-
-All methods return promises. Requires Node.js 18+.
-
----
-
-## Imports
-
-```typescript
-import {
- Skyvern, // Main client class
- SkyvernEnvironment, // Cloud, Staging, Local
- SkyvernError, // Base error class
- SkyvernTimeoutError, // HTTP timeout error
- SkyvernApi, // Namespace for API types and error subclasses
-} from "@skyvern/client";
-
-// HTTP error subclasses via SkyvernApi namespace:
-// SkyvernApi.BadRequestError — 400
-// SkyvernApi.ForbiddenError — 403
-// SkyvernApi.NotFoundError — 404
-// SkyvernApi.ConflictError — 409
-// SkyvernApi.UnprocessableEntityError — 422
-```
-
-**Important:** `SkyvernError` and `SkyvernTimeoutError` are top-level exports. The HTTP-specific errors (`BadRequestError`, etc.) extend `SkyvernError` and are accessed via the `SkyvernApi` namespace.
-
----
-
-## Tasks
-
-### `runTask`
-
-```typescript
-const result = await skyvern.runTask({
- body: {
- prompt: string, // Required. Natural language instructions.
- url?: string, // Starting page URL.
- engine?: RunEngine, // "skyvern_v1" (default), "skyvern_v2", "openai_cua", "anthropic_cua", "ui_tars"
- max_steps?: number, // Cap AI steps to limit cost.
- data_extraction_schema?: Record<string, unknown> | string, // JSON Schema for output.
- browser_session_id?: string, // Run in existing session.
- publish_workflow?: boolean, // Save generated code as reusable workflow.
- proxy_location?: ProxyLocation,
- webhook_url?: string,
- error_code_mapping?: Record<string, string>,
- totp_identifier?: string,
- totp_url?: string,
- title?: string,
- model?: Record<string, unknown>,
- user_agent?: string,
- extra_http_headers?: Record<string, string>,
- browser_address?: string,
- },
- waitForCompletion?: boolean, // Poll until finished. Default: false.
- timeout?: number, // Max wait (seconds). Default: 1800.
-}): Promise<TaskRunResponse>
-```
-
-**`TaskRunResponse` fields:**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `run_id` | `string` | Unique ID (`tsk_...`). |
-| `status` | `string` | `created` \| `queued` \| `running` \| `completed` \| `failed` \| `terminated` \| `timed_out` \| `canceled` |
-| `output` | `Record<string, unknown> \| null` | Extracted data. `null` until completed. |
-| `failure_reason` | `string \| undefined` | Error description if failed. |
-| `downloaded_files` | `FileInfo[] \| undefined` | Files downloaded during the run. |
-| `recording_url` | `string \| undefined` | Session recording video URL. |
-| `screenshot_urls` | `string[] \| undefined` | Final screenshots. |
-| `app_url` | `string \| undefined` | Link to run in Skyvern UI. |
-| `step_count` | `number \| undefined` | Number of AI steps taken. |
-| `created_at` | `string` | When the run was created. |
-| `finished_at` | `string \| undefined` | When the run finished. |
-
-### `getRun`
-
-```typescript
-const run = await skyvern.getRun(runId: string): Promise<GetRunResponse>
-```
-
-Returns status and results for any run (task or workflow).
-
-### `cancelRun`
-
-```typescript
-await skyvern.cancelRun(runId: string): Promise<void>
-```
-
-### `getRunTimeline`
-
-```typescript
-const timeline = await skyvern.getRunTimeline(runId: string): Promise<WorkflowRunTimeline[]>
-```
-
-### `getRunArtifacts`
-
-```typescript
-const artifacts = await skyvern.getRunArtifacts(
- runId: string,
- request?: { artifact_type?: ArtifactType | ArtifactType[] },
-): Promise<Artifact[]>
-```
-
-### `getArtifact`
-
-```typescript
-const artifact = await skyvern.getArtifact(artifactId: string): Promise<Artifact>
-```
-
-### `retryRunWebhook`
-
-```typescript
-await skyvern.retryRunWebhook(runId: string): Promise<void>
-```
-
----
-
-## Workflows
-
-### `runWorkflow`
-
-```typescript
-const result = await skyvern.runWorkflow({
- body: {
- workflow_id: string, // Required. Permanent ID (wpid_...).
- parameters?: Record<string, unknown>, // Input params matching workflow definition.
- browser_session_id?: string,
- browser_profile_id?: string, // Load saved browser state.
- proxy_location?: ProxyLocation,
- webhook_url?: string,
- title?: string,
- totp_identifier?: string,
- totp_url?: string,
- user_agent?: string,
- extra_http_headers?: Record<string, string>,
- browser_address?: string,
- },
- template?: boolean,
- waitForCompletion?: boolean, // Default: false.
- timeout?: number, // Default: 1800.
-}): Promise<WorkflowRunResponse>
-```
-
-**`WorkflowRunResponse` fields:** Same as `TaskRunResponse` plus `run_with`, `ai_fallback`, `script_run`.
-
-### `createWorkflow`
-
-```typescript
-const workflow = await skyvern.createWorkflow({
- body: { json_definition?: object, yaml_definition?: string },
- folder_id?: string,
-}): Promise<Workflow>
-```
-
-**`Workflow` fields:** `workflow_id`, `workflow_permanent_id`, `version`, `title`, `workflow_definition`, `status`, `created_at`
-
-### `getWorkflows`
-
-```typescript
-const workflows = await skyvern.getWorkflows({
- page?: number,
- page_size?: number,
- only_saved_tasks?: boolean,
- only_workflows?: boolean,
- title?: string,
- search_key?: string,
- folder_id?: string,
- status?: WorkflowStatus | WorkflowStatus[],
-}): Promise<Workflow[]>
-```
-
-### `getWorkflow`
-
-```typescript
-const workflow = await skyvern.getWorkflow(
- workflowPermanentId: string,
- request?: { version?: number; template?: boolean },
-): Promise<Workflow>
-```
-
-### `getWorkflowVersions`
-
-```typescript
-const versions = await skyvern.getWorkflowVersions(
- workflowPermanentId: string,
- request?: { template?: boolean },
-): Promise<Workflow[]>
-```
-
-### `updateWorkflow`
-
-```typescript
-const updated = await skyvern.updateWorkflow(
- workflowId: string, // The permanent ID (wpid_...).
- request?: { json_definition?: object; yaml_definition?: string },
-): Promise<Workflow>
-```
-
-### `deleteWorkflow`
-
-```typescript
-await skyvern.deleteWorkflow(workflowId: string): Promise<void>
-```
-
----
-
-## Browser sessions
-
-A persistent browser instance that stays alive between API calls. Use to chain tasks without losing cookies or login state.
-
-### `createBrowserSession`
-
-```typescript
-const session = await skyvern.createBrowserSession({
- timeout?: number, // Minutes (5-1440). Default: 60.
- proxy_location?: ProxyLocation,
- extensions?: Extensions[], // "ad-blocker", "captcha-solver"
- browser_type?: PersistentBrowserType, // "chrome", "msedge"
-}): Promise<BrowserSessionResponse>
-```
-
-**`BrowserSessionResponse` fields:** `browser_session_id`, `status`, `browser_address`, `app_url`, `timeout`, `started_at`, `created_at`
-
-### `getBrowserSession`
-
-```typescript
-const session = await skyvern.getBrowserSession(browserSessionId: string): Promise<BrowserSessionResponse>
-```
-
-### `getBrowserSessions`
-
-```typescript
-const sessions = await skyvern.getBrowserSessions(): Promise<BrowserSessionResponse[]>
-```
-
-### `closeBrowserSession`
-
-```typescript
-await skyvern.closeBrowserSession(browserSessionId: string): Promise<void>
-```
-
-### Session chaining example
-
-```typescript
-const session = await skyvern.createBrowserSession({});
-
-// Step 1: Log in
-await skyvern.runTask({
- body: {
- prompt: "Log in with username [email protected]",
- url: "https://app.example.com/login",
- browser_session_id: session.browser_session_id,
- },
- waitForCompletion: true,
-});
-
-// Step 2: Extract data (same browser, already logged in)
-const result = await skyvern.runTask({
- body: {
- prompt: "Go to the invoices page and extract all invoice numbers",
- browser_session_id: session.browser_session_id,
- },
- waitForCompletion: true,
-});
-console.log(result.output);
-
-// Clean up
-await skyvern.closeBrowserSession(session.browser_session_id);
-```
-
----
-
-## Browser profiles
-
-A saved snapshot of browser state (cookies, local storage). Create from a completed workflow run, then reuse to skip login.
-
-### `createBrowserProfile`
-
-```typescript
-const profile = await skyvern.createBrowserProfile({
- name: string,
- description?: string,
- workflow_run_id?: string, // Run must have used persist_browser_session: true.
- browser_session_id?: string, // One of workflow_run_id or browser_session_id is required.
-}): Promise<BrowserProfile>
-```
-
-**`BrowserProfile` fields:** `browser_profile_id`, `name`, `description`, `created_at`
-
-### `listBrowserProfiles`
-
-```typescript
-const profiles = await skyvern.listBrowserProfiles({
- include_deleted?: boolean,
-}): Promise<BrowserProfile[]>
-```
-
-### `getBrowserProfile`
-
-```typescript
-const profile = await skyvern.getBrowserProfile(profileId: string): Promise<BrowserProfile>
-```
-
-### `deleteBrowserProfile`
-
-```typescript
-await skyvern.deleteBrowserProfile(profileId: string): Promise<void>
-```
-
----
-
-## Credentials
-
-Store login information securely. Reference by ID instead of passing secrets in code.
-
-### `createCredential`
-
-```typescript
-const credential = await skyvern.createCredential({
- name: string,
- credential_type: CredentialType, // e.g. "password"
- credential: object, // Password: { username: "...", password: "..." }
-}): Promise<CredentialResponse>
-```
-
-### `getCredentials`
-
-```typescript
-const creds = await skyvern.getCredentials({
- page?: number,
- page_size?: number,
-}): Promise<CredentialResponse[]>
-```
-
-### `getCredential`
-
-```typescript
-const cred = await skyvern.getCredential(credentialId: string): Promise<CredentialResponse>
-```
-
-### `deleteCredential`
-
-```typescript
-await skyvern.deleteCredential(credentialId: string): Promise<void>
-```
-
-### `sendTotpCode`
-
-Send a TOTP code to Skyvern during a run that requires 2FA.
-
-```typescript
-await skyvern.sendTotpCode({
- totp_identifier: string,
- content: string, // The TOTP code value.
- task_id?: string,
- workflow_id?: string,
- workflow_run_id?: string,
- source?: string,
- expired_at?: string,
-}): Promise<TotpCode>
-```
-
----
-
-## Helper methods
-
-### `login`
-
-Automate logging into a website using stored credentials.
-
-```typescript
-const result = await skyvern.login({
- credential_type: CredentialType, // Required. "skyvern", "bitwarden", "1password", "azure_vault".
- url?: string,
- credential_id?: string, // When using "skyvern" type.
- prompt?: string,
- browser_session_id?: string,
- browser_address?: string,
- proxy_location?: ProxyLocation,
- webhook_url?: string,
- totp_identifier?: string,
- totp_url?: string,
- extra_http_headers?: Record<string, string>,
- waitForCompletion?: boolean, // Default: false.
- timeout?: number, // Default: 1800.
- // Bitwarden: bitwarden_collection_id, bitwarden_item_id
- // 1Password: onepassword_vault_id, onepassword_item_id
- // Azure: azure_vault_name, azure_vault_username_key, azure_vault_password_key, azure_vault_totp_secret_key
-}): Promise<WorkflowRunResponse>
-```
-
-### `downloadFiles`
-
-```typescript
-const result = await skyvern.downloadFiles({
- navigation_goal: string, // Required. What to download.
- url?: string,
- browser_session_id?: string,
- browser_profile_id?: string,
- download_suffix?: string, // Expected extension, e.g. ".pdf"
- download_timeout?: number,
- max_steps_per_run?: number,
- extra_http_headers?: Record<string, string>,
- waitForCompletion?: boolean, // Default: false.
- timeout?: number, // Default: 1800.
-}): Promise<WorkflowRunResponse>
-```
-
-### `uploadFile`
-
-```typescript
-const upload = await skyvern.uploadFile({ file }): Promise<UploadFileResponse>
-// Returns: { s3_uri: string, presigned_url: string }
-```
-
----
-
-## Browser automation (Playwright + AI)
-
-The TypeScript SDK extends Playwright with AI capabilities via cloud browsers.
-
-### Launch browsers
-
-```typescript
-// Launch new cloud browser
-const browser = await skyvern.launchCloudBrowser({ timeout?: number, proxyLocation?: ProxyLocation });
-
-// Reuse existing or create new
-const browser = await skyvern.useCloudBrowser({ timeout?: number, proxyLocation?: ProxyLocation });
-
-// Connect to existing cloud session
-const browser = await skyvern.connectToCloudBrowserSession(browserSessionId: string);
-
-// Connect via CDP
-const browser = await skyvern.connectToBrowserOverCdp(cdpUrl: string);
-```
-
-### Get pages
-
-```typescript
-const page = await browser.getWorkingPage(); // Get or create page
-const page = await browser.newPage(); // Always create new page
-await browser.close(); // Close browser and session
-```
-
-### AI-enhanced page methods
-
-```typescript
-// Click with AI fallback
-await page.click("#selector"); // Standard Playwright
-await page.click({ prompt: "Click the submit button" }); // AI-powered
-await page.click("#selector", { prompt: "Click submit" }); // Selector + AI fallback
-
-// Fill with AI fallback
-await page.fill("#email", "[email protected]"); // Standard Playwright
-await page.fill({ prompt: "Fill email with [email protected]" }); // AI-powered
-await page.fill("#email", "[email protected]", { prompt: "..." }); // Selector + AI fallback
-
-// Select with AI fallback
-await page.selectOption("#country", "us"); // Standard Playwright
-await page.selectOption({ prompt: "Select United States from country" }); // AI-powered
-
-// Single AI actions
-await page.act("Click the login button"); // Perform an action
-const data = await page.extract({ prompt: "Extract products" }); // Extract data
-const ok = await page.validate("User is logged in"); // Validate state (boolean)
-const resp = await page.prompt("What is the heading?", schema); // LLM prompt
-```
-
-### Full task execution via `page.agent`
-
-```typescript
-await page.agent.runTask("Fill out the form", { timeout: 300 });
-await page.agent.login("skyvern", { credentialId: "cred_123" });
-await page.agent.downloadFiles("Download the PDF", { downloadSuffix: ".pdf" });
-await page.agent.runWorkflow("wpid_abc", { parameters: { key: "value" } });
-```
-
----
-
-## Error handling
-
-```typescript
-import { SkyvernError, SkyvernTimeoutError, SkyvernApi } from "@skyvern/client";
-
-try {
- const run = await skyvern.getRun("tsk_nonexistent");
-} catch (e) {
- if (e instanceof SkyvernApi.NotFoundError) {
- console.log(e.statusCode, e.body); // 404
- } else if (e instanceof SkyvernTimeoutError) {
- console.log("Request timed out");
- } else if (e instanceof SkyvernError) {
- console.log(e.statusCode, e.body); // Any other HTTP error
- }
-}
-```
-
-**Error types:** `SkyvernApi.BadRequestError` (400), `SkyvernApi.ForbiddenError` (403), `SkyvernApi.NotFoundError` (404), `SkyvernApi.ConflictError` (409), `SkyvernApi.UnprocessableEntityError` (422). All inherit from `SkyvernError`.
-
-**Completion timeout** throws a standard `Error`:
-
-```typescript
-try {
- const result = await skyvern.runTask({
- body: { prompt: "...", url: "..." },
- waitForCompletion: true,
- timeout: 300,
- });
-} catch (e) {
- if (e instanceof Error && e.message.includes("Timeout")) {
- console.log("Task didn't complete in time");
- }
-}
-```
-
-**Run failure** is not an exception — check `result.status`:
-
-```typescript
-if (result.status === "failed") console.log(result.failure_reason);
-if (result.status === "completed") console.log(result.output);
-```
-
----
-
-## Request options
-
-Override timeout, retries, or headers per-request (second parameter on all methods):
-
-```typescript
-const result = await skyvern.runTask(
- { body: { prompt: "...", url: "..." } },
- {
- timeoutInSeconds: 120,
- maxRetries: 3,
- headers: { "x-custom-header": "value" },
- abortSignal: controller.signal,
- },
-);
-```
-
----
-
-## Polling pattern
-
-When not using `waitForCompletion`:
-
-```typescript
-const task = await skyvern.runTask({ body: { prompt: "...", url: "..." } });
-
-const terminal = ["completed", "failed", "terminated", "timed_out", "canceled"];
-let run;
-while (true) {
- run = await skyvern.getRun(task.run_id);
- if (terminal.includes(run.status)) break;
- await new Promise((resolve) => setTimeout(resolve, 5000));
-}
-console.log(run.output);
-```
-
----
-
-## Key constraints
-
-- `browser_profile_id` works with `runWorkflow` only — silently ignored by `runTask`.
-- Only workflow runs with `persist_browser_session: true` produce archives for profile creation.
-- Session archiving is async — profile creation may need a short retry delay after a run completes.
-- `engine` accepts string values: `"skyvern_v1"`, `"skyvern_v2"`, `"openai_cua"`, `"anthropic_cua"`, `"ui_tars"`.
-- Cloud browser methods (`launchCloudBrowser`, `useCloudBrowser`, `connectToCloudBrowserSession`) only work with `Cloud` or `Staging` environments.
-- The SDK depends on `playwright` for browser automation features.
diff --git a/docs/ts-sdk-reference/credentials.mdx b/docs/ts-sdk-reference/credentials.mdx
deleted file mode 100644
index a215f2cad..000000000
--- a/docs/ts-sdk-reference/credentials.mdx
+++ /dev/null
@@ -1,132 +0,0 @@
----
-title: Credentials
-subtitle: Store and manage authentication credentials securely
-description: Use the Skyvern TypeScript SDK to create, list, retrieve, and delete credentials, and send TOTP codes for two-factor authentication during automated runs.
-slug: ts-sdk-reference/credentials
-keywords:
- - credential
- - password
- - TOTP
- - 2FA
- - authentication
- - createCredential
- - getCredentials
- - deleteCredential
- - sendTotpCode
- - secret
----
-
-Credentials let you store login information (username/password, TOTP secrets) securely in Skyvern's vault. Reference them by ID in tasks and workflows instead of passing secrets in your code.
-
----
-
-## `createCredential`
-
-Store a new credential.
-
-```typescript
-const credential = await skyvern.createCredential({
- name: "my-app-login",
- credential_type: "password",
- credential: {
- username: "[email protected]",
- password: "s3cur3-p4ss",
- },
-});
-console.log(credential.credential_id);
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `name` | `string` | Yes | Display name for the credential. |
-| `credential_type` | `CredentialType` | Yes | Type of credential. |
-| `credential` | `object` | Yes | The credential data. Shape depends on `credential_type`. |
-
-### Returns `CredentialResponse`
-
----
-
-## `getCredentials`
-
-List all credentials. Credential values are never returned — only metadata.
-
-```typescript
-const creds = await skyvern.getCredentials({});
-for (const c of creds) {
- console.log(`${c.name} (${c.credential_id})`);
-}
-```
-
-### Parameters
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `page` | `number` | No | `undefined` | Page number. |
-| `page_size` | `number` | No | `undefined` | Results per page. |
-
-### Returns `CredentialResponse[]`
-
----
-
-## `getCredential`
-
-Get a single credential's metadata by ID.
-
-```typescript
-const cred = await skyvern.getCredential("cred_abc123");
-console.log(cred.name, cred.credential_type);
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `credentialId` | `string` | Yes | The credential ID. |
-
-### Returns `CredentialResponse`
-
----
-
-## `deleteCredential`
-
-Delete a credential.
-
-```typescript
-await skyvern.deleteCredential("cred_abc123");
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `credentialId` | `string` | Yes | The credential ID to delete. |
-
----
-
-## `sendTotpCode`
-
-Send a TOTP (time-based one-time password) code to Skyvern during a run that requires 2FA. Call this when your webhook or polling detects that Skyvern is waiting for a TOTP code.
-
-```typescript
-await skyvern.sendTotpCode({
- totp_identifier: "[email protected]",
- content: "123456",
-});
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `totp_identifier` | `string` | Yes | The identifier matching the `totp_identifier` used in the task/workflow. |
-| `content` | `string` | Yes | The TOTP code value. |
-| `task_id` | `string` | No | Associate with a specific task run. |
-| `workflow_id` | `string` | No | Associate with a specific workflow. |
-| `workflow_run_id` | `string` | No | Associate with a specific workflow run. |
-| `source` | `string` | No | Source of the TOTP code. |
-| `expired_at` | `string` | No | When this code expires (ISO 8601 format). |
-| `type` | `OtpType` | No | OTP type. |
-
-### Returns `TotpCode`
diff --git a/docs/ts-sdk-reference/error-handling.mdx b/docs/ts-sdk-reference/error-handling.mdx
deleted file mode 100644
index 1f520a13c..000000000
--- a/docs/ts-sdk-reference/error-handling.mdx
+++ /dev/null
@@ -1,240 +0,0 @@
----
-title: Error Handling
-subtitle: Handle API errors, timeouts, and configure retries
-description: Handle typed API errors, timeouts, and configure automatic retries in the Skyvern TypeScript SDK using SkyvernError, status-specific exceptions, and the built-in retry mechanism.
-slug: ts-sdk-reference/error-handling
-keywords:
- - BadRequestError
- - ForbiddenError
- - NotFoundError
- - SkyvernTimeoutError
- - timeout
- - retry
- - AbortSignal
- - polling
- - run status
- - failure
----
-
-The SDK raises typed exceptions for API errors. All errors extend `SkyvernError` and include the HTTP status code, response body, and raw response.
-
----
-
-## Error types
-
-| Exception | Status Code | When it's raised |
-|-----------|-------------|------------------|
-| `BadRequestError` | 400 | Invalid request parameters. |
-| `ForbiddenError` | 403 | Invalid or missing API key. |
-| `NotFoundError` | 404 | Resource (run, workflow, session) not found. |
-| `ConflictError` | 409 | Resource conflict (e.g., duplicate creation). |
-| `UnprocessableEntityError` | 422 | Request validation failed. |
-| `SkyvernError` | Any | Base class for all API errors. Catch this as a fallback. |
-| `SkyvernTimeoutError` | — | HTTP request timed out. |
-
-Import errors from the package:
-
-```typescript
-import { SkyvernError, SkyvernTimeoutError, SkyvernApi } from "@skyvern/client";
-
-// Base errors are top-level exports:
-// SkyvernError — base class for all API errors
-// SkyvernTimeoutError — HTTP request timed out
-
-// HTTP status error subclasses are accessed via the SkyvernApi namespace:
-// SkyvernApi.BadRequestError — 400
-// SkyvernApi.ForbiddenError — 403
-// SkyvernApi.NotFoundError — 404
-// SkyvernApi.ConflictError — 409
-// SkyvernApi.UnprocessableEntityError — 422
-```
-
----
-
-## Catching errors
-
-```typescript
-import { Skyvern, SkyvernError, SkyvernApi } from "@skyvern/client";
-
-const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
-
-try {
- const run = await skyvern.getRun("tsk_nonexistent");
-} catch (e) {
- if (e instanceof SkyvernApi.NotFoundError) {
- console.log(`Run not found: ${e.body}`);
- } else if (e instanceof SkyvernError) {
- console.log(`API error ${e.statusCode}: ${e.body}`);
- }
-}
-```
-
-### Error properties
-
-Every error has these attributes:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `statusCode` | `number \| undefined` | HTTP status code. |
-| `body` | `unknown` | Response body (usually an object with error details). |
-| `rawResponse` | `RawResponse \| undefined` | The raw HTTP response. |
-| `message` | `string` | Human-readable error message. |
-
----
-
-## Timeouts
-
-Two different timeouts apply:
-
-### HTTP request timeout
-
-Controls how long the SDK waits for the HTTP response from the Skyvern API. Set it in the constructor or per-request:
-
-```typescript
-// Global timeout (applies to all requests)
-const skyvern = new Skyvern({
- apiKey: "YOUR_API_KEY",
- timeoutInSeconds: 30,
-});
-
-// Per-request timeout
-const result = await skyvern.getRun("tsk_abc123", {
- timeoutInSeconds: 10,
-});
-```
-
-When an HTTP request times out, a `SkyvernTimeoutError` is thrown.
-
-### Completion timeout
-
-Controls how long `waitForCompletion` polls before giving up. This is separate from the HTTP timeout:
-
-```typescript
-try {
- const result = await skyvern.runTask({
- body: {
- prompt: "Extract data",
- url: "https://example.com",
- },
- waitForCompletion: true,
- timeout: 300, // Give up after 5 minutes
- });
-} catch (e) {
- if (e instanceof Error && e.message.includes("Timeout")) {
- console.log("Task didn't complete in time");
- }
-}
-```
-
-The completion timeout throws a standard JavaScript `Error` with a timeout message.
-
----
-
-## Retries
-
-Configure automatic retries for transient failures. Set it in the constructor or per-request:
-
-```typescript
-// Global retries (default: 2)
-const skyvern = new Skyvern({
- apiKey: "YOUR_API_KEY",
- maxRetries: 3,
-});
-
-// Per-request retries
-const result = await skyvern.runTask(
- {
- body: {
- prompt: "Extract product data",
- url: "https://example.com/products",
- },
- },
- { maxRetries: 5 },
-);
-```
-
-Retries apply to the HTTP request level (network errors, 5xx responses). They do not retry the entire task if it fails at the AI level — use `getRun` to check the status and re-run if needed.
-
----
-
-## Abort requests
-
-Cancel in-flight requests using `AbortSignal`:
-
-```typescript
-const controller = new AbortController();
-
-// Cancel after 10 seconds
-setTimeout(() => controller.abort(), 10000);
-
-try {
- const result = await skyvern.runTask(
- {
- body: {
- prompt: "Extract data",
- url: "https://example.com",
- },
- },
- { abortSignal: controller.signal },
- );
-} catch (e) {
- if (e instanceof Error && e.name === "AbortError") {
- console.log("Request was aborted");
- }
-}
-```
-
----
-
-## Run failure vs API errors
-
-There are two distinct failure modes:
-
-**API error** — The HTTP request itself failed. The SDK throws an exception.
-
-```typescript
-import { SkyvernError } from "@skyvern/client";
-
-try {
- const result = await skyvern.runTask({
- body: { prompt: "..." },
- });
-} catch (e) {
- if (e instanceof SkyvernError) {
- console.log(`API call failed: ${e.statusCode}`);
- }
-}
-```
-
-**Run failure** — The API call succeeded, but the task/workflow failed during execution. No exception is thrown. Check the `status` field:
-
-```typescript
-const result = await skyvern.runTask({
- body: {
- prompt: "Fill out the form",
- url: "https://example.com",
- },
- waitForCompletion: true,
-});
-
-if (result.status === "failed") {
- console.log(`Task failed: ${result.failure_reason}`);
-} else if (result.status === "timed_out") {
- console.log(`Task exceeded step limit after ${result.step_count} steps`);
-} else if (result.status === "completed") {
- console.log(`Success: ${JSON.stringify(result.output)}`);
-}
-```
-
-### Run statuses
-
-| Status | Description |
-|--------|-------------|
-| `created` | Run initialized, not yet queued. |
-| `queued` | Waiting for an available browser. |
-| `running` | AI is executing. |
-| `completed` | Finished successfully. |
-| `failed` | Encountered an error during execution. |
-| `terminated` | Manually stopped. |
-| `timed_out` | Exceeded step limit (`max_steps`). |
-| `canceled` | Canceled before starting. |
diff --git a/docs/ts-sdk-reference/helpers.mdx b/docs/ts-sdk-reference/helpers.mdx
deleted file mode 100644
index a88042f11..000000000
--- a/docs/ts-sdk-reference/helpers.mdx
+++ /dev/null
@@ -1,176 +0,0 @@
----
-title: Helper Methods
-subtitle: High-level methods for common automation patterns
-description: Use the Skyvern TypeScript SDK helper methods for common patterns like automated login with stored credentials, file downloads, and multi-provider authentication via Bitwarden, 1Password, and Azure Key Vault.
-slug: ts-sdk-reference/helpers
-keywords:
- - login
- - downloadFiles
- - uploadFile
- - Bitwarden
- - 1Password
- - Azure Key Vault
- - credential
- - authentication
- - file download
- - file upload
----
-
-These methods wrap common multi-step patterns into single API calls. Under the hood, they create and run specialized workflows.
-
----
-
-## `login`
-
-Automate logging into a website using stored credentials. This creates a login workflow, executes it, and optionally waits for completion.
-
-```typescript
-const result = await skyvern.login({
- credential_type: "skyvern",
- credential_id: "cred_abc123",
- url: "https://app.example.com/login",
- waitForCompletion: true,
-});
-console.log(result.status);
-```
-
-### Parameters
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `credential_type` | `CredentialType` | Yes | — | How credentials are stored. Options: `"skyvern"`, `"bitwarden"`, `"1password"`, `"azure_vault"`. |
-| `url` | `string` | No | `undefined` | The login page URL. |
-| `credential_id` | `string` | No | `undefined` | The Skyvern credential ID (when using `"skyvern"` type). |
-| `prompt` | `string` | No | `undefined` | Additional instructions for the AI during login. |
-| `browser_session_id` | `string` | No | `undefined` | Run login inside an existing browser session. |
-| `browser_address` | `string` | No | `undefined` | Connect to a browser at this CDP address. |
-| `proxy_location` | `ProxyLocation` | No | `undefined` | Route browser traffic through a geographic proxy. |
-| `webhook_url` | `string` | No | `undefined` | URL to receive a POST when the login finishes. |
-| `totp_identifier` | `string` | No | `undefined` | Identifier for TOTP verification. |
-| `totp_url` | `string` | No | `undefined` | URL to receive TOTP codes. |
-| `extra_http_headers` | `Record<string, string>` | No | `undefined` | Additional HTTP headers. |
-| `max_screenshot_scrolling_times` | `number` | No | `undefined` | Number of screenshot scrolls. |
-| `waitForCompletion` | `boolean` | No | `false` | Block until the login finishes. |
-| `timeout` | `number` | No | `1800` | Max wait time in seconds. |
-
-**Bitwarden-specific parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `bitwarden_collection_id` | `string` | Bitwarden collection ID. |
-| `bitwarden_item_id` | `string` | Bitwarden item ID. |
-
-**1Password-specific parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `onepassword_vault_id` | `string` | 1Password vault ID. |
-| `onepassword_item_id` | `string` | 1Password item ID. |
-
-**Azure Key Vault-specific parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `azure_vault_name` | `string` | Azure Key Vault name. |
-| `azure_vault_username_key` | `string` | Secret name for the username. |
-| `azure_vault_password_key` | `string` | Secret name for the password. |
-| `azure_vault_totp_secret_key` | `string` | Secret name for the TOTP secret. |
-
-### Returns `WorkflowRunResponse`
-
-### Example: Login then extract data
-
-```typescript
-const session = await skyvern.createBrowserSession({});
-
-// Login
-await skyvern.login({
- credential_type: "skyvern",
- credential_id: "cred_abc123",
- url: "https://app.example.com/login",
- browser_session_id: session.browser_session_id,
- waitForCompletion: true,
-});
-
-// Now extract data from the authenticated session
-const result = await skyvern.runTask({
- body: {
- prompt: "Go to the billing page and extract all invoices",
- browser_session_id: session.browser_session_id,
- },
- waitForCompletion: true,
-});
-console.log(result.output);
-```
-
----
-
-## `downloadFiles`
-
-Navigate to a page and download files.
-
-```typescript
-const result = await skyvern.downloadFiles({
- navigation_goal: "Download the latest monthly report PDF",
- url: "https://app.example.com/reports",
- waitForCompletion: true,
-});
-
-for (const f of result.downloaded_files ?? []) {
- console.log(f.name);
-}
-```
-
-### Parameters
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `navigation_goal` | `string` | Yes | — | Natural language description of what to download. |
-| `url` | `string` | No | `undefined` | Starting page URL. |
-| `browser_session_id` | `string` | No | `undefined` | Run inside an existing browser session. |
-| `browser_profile_id` | `string` | No | `undefined` | Load a browser profile. |
-| `proxy_location` | `ProxyLocation` | No | `undefined` | Route through a geographic proxy. |
-| `webhook_url` | `string` | No | `undefined` | URL to receive a POST when the download finishes. |
-| `download_suffix` | `string` | No | `undefined` | Expected file extension to wait for (e.g., `".pdf"`). |
-| `download_timeout` | `number` | No | `undefined` | Max time to wait for the download in seconds. |
-| `max_steps_per_run` | `number` | No | `undefined` | Cap AI steps. |
-| `extra_http_headers` | `Record<string, string>` | No | `undefined` | Additional HTTP headers. |
-| `waitForCompletion` | `boolean` | No | `false` | Block until the download finishes. |
-| `timeout` | `number` | No | `1800` | Max wait time in seconds. |
-
-### Returns `WorkflowRunResponse`
-
-The `downloaded_files` field contains the list of files that were downloaded.
-
-<Note>
-Unlike the Python SDK where `download_files` does not support `wait_for_completion`, the TypeScript SDK supports `waitForCompletion` on all methods including `downloadFiles`.
-</Note>
-
----
-
-## `uploadFile`
-
-Upload a file to Skyvern's storage. Returns a presigned URL and S3 URI you can reference in tasks and workflows.
-
-```typescript
-import fs from "fs";
-
-const upload = await skyvern.uploadFile({
- file: fs.createReadStream("data.csv"),
-});
-console.log(upload.s3_uri); // s3://skyvern-uploads/...
-console.log(upload.presigned_url); // https://...signed download URL
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `file` | `File \| ReadStream \| Blob` | Yes | The file to upload. |
-
-### Returns `UploadFileResponse`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `s3_uri` | `string` | S3 URI for the uploaded file. |
-| `presigned_url` | `string` | Pre-signed download URL. |
diff --git a/docs/ts-sdk-reference/overview.mdx b/docs/ts-sdk-reference/overview.mdx
deleted file mode 100644
index 39c5721eb..000000000
--- a/docs/ts-sdk-reference/overview.mdx
+++ /dev/null
@@ -1,185 +0,0 @@
----
-title: TypeScript SDK
-subtitle: Install, authenticate, and configure the Skyvern TypeScript client
-description: Install the Skyvern TypeScript SDK, authenticate with your API key, and start running browser automation tasks and workflows programmatically.
-slug: ts-sdk-reference/overview
-keywords:
- - install
- - npm
- - api key
- - client
- - configuration
- - authentication
- - environment
- - timeout
- - maxRetries
- - abortSignal
----
-
-The `@skyvern/client` package wraps the Skyvern REST API in a typed TypeScript client with built-in browser automation via Playwright.
-
-```bash
-npm install @skyvern/client
-```
-
-<Note>
-Requires Node.js 18+. Also compatible with Bun, Deno, and Cloudflare Workers.
-</Note>
-
----
-
-## Initialize the client
-
-The `Skyvern` class provides both API methods and browser automation. All API methods return promises:
-
-```typescript
-import { Skyvern } from "@skyvern/client";
-
-const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
-
-const result = await skyvern.runTask({
- body: {
- prompt: "Get the title of the top post on Hacker News",
- url: "https://news.ycombinator.com",
- },
- waitForCompletion: true,
-});
-console.log(result.output);
-```
-
-### Constructor parameters
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `apiKey` | `string` | — | **Required.** Your Skyvern API key. Get one at [app.skyvern.com/settings](https://app.skyvern.com/settings/). |
-| `environment` | `SkyvernEnvironment \| string` | `Cloud` | Target environment. Options: `Cloud`, `Staging`, `Local`. |
-| `baseUrl` | `string` | `undefined` | Override the API base URL. Use this for self-hosted deployments. |
-| `timeoutInSeconds` | `number` | `60` | HTTP request timeout in seconds. |
-| `maxRetries` | `number` | `2` | Number of times to retry failed requests. |
-| `headers` | `Record<string, string>` | `undefined` | Additional headers included with every request. |
-
----
-
-## Environments
-
-The SDK ships with three built-in environment URLs:
-
-```typescript
-import { SkyvernEnvironment } from "@skyvern/client";
-```
-
-| Environment | URL | When to use |
-|-------------|-----|-------------|
-| `SkyvernEnvironment.Cloud` | `https://api.skyvern.com` | Skyvern Cloud (default) |
-| `SkyvernEnvironment.Staging` | `https://api-staging.skyvern.com` | Staging environment |
-| `SkyvernEnvironment.Local` | `http://localhost:8000` | Local server started with `skyvern run server` |
-
-For a self-hosted instance at a custom URL, pass `baseUrl` instead:
-
-```typescript
-const skyvern = new Skyvern({
- apiKey: "YOUR_API_KEY",
- baseUrl: "https://skyvern.your-company.com",
-});
-```
-
----
-
-## `waitForCompletion`
-
-By default, `runTask` and `runWorkflow` return immediately after the run is queued — you get a `run_id` and need to poll `getRun()` yourself. Pass `waitForCompletion: true` to have the SDK poll automatically until the run reaches a terminal state (`completed`, `failed`, `terminated`, `timed_out`, or `canceled`):
-
-```typescript
-// Returns only after the task finishes (up to 30 min by default)
-const result = await skyvern.runTask({
- body: {
- prompt: "Fill out the contact form",
- url: "https://example.com/contact",
- },
- waitForCompletion: true,
- timeout: 600, // give up after 10 minutes
-});
-
-// Without waitForCompletion — returns immediately
-const task = await skyvern.runTask({
- body: {
- prompt: "Fill out the contact form",
- url: "https://example.com/contact",
- },
-});
-console.log(task.run_id); // poll with skyvern.getRun(task.run_id)
-```
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `waitForCompletion` | `boolean` | `false` | Poll until the run finishes. |
-| `timeout` | `number` | `1800` | Maximum wait time in seconds. Throws `Error` if exceeded. |
-
-Supported on `runTask`, `runWorkflow`, `login`, and `downloadFiles`.
-
----
-
-## Request options
-
-Every method accepts an optional second parameter for per-request overrides of timeout, retries, headers, and abort signal:
-
-```typescript
-const result = await skyvern.runTask(
- {
- body: {
- prompt: "Extract data",
- url: "https://example.com",
- },
- },
- {
- timeoutInSeconds: 120,
- maxRetries: 3,
- headers: { "x-custom-header": "value" },
- },
-);
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `timeoutInSeconds` | `number` | HTTP timeout for this request. |
-| `maxRetries` | `number` | Retry count for this request. |
-| `abortSignal` | `AbortSignal` | Signal to abort the request. |
-| `apiKey` | `string` | Override the API key for this request. |
-| `headers` | `Record<string, string>` | Additional headers for this request. |
-
-These override the client-level defaults for that single call only.
-
----
-
-## Next steps
-
-<CardGroup cols={2}>
- <Card
- title="Tasks"
- icon="play"
- href="/ts-sdk-reference/tasks"
- >
- Run browser automations with `runTask`
- </Card>
- <Card
- title="Workflows"
- icon="diagram-project"
- href="/ts-sdk-reference/workflows"
- >
- Create and run multi-step automations
- </Card>
- <Card
- title="Browser Automation"
- icon="robot"
- href="/ts-sdk-reference/browser-automation"
- >
- Control cloud browsers with Playwright + AI
- </Card>
- <Card
- title="Error Handling"
- icon="triangle-exclamation"
- href="/ts-sdk-reference/error-handling"
- >
- Handle errors and configure retries
- </Card>
-</CardGroup>
diff --git a/docs/ts-sdk-reference/tasks.mdx b/docs/ts-sdk-reference/tasks.mdx
deleted file mode 100644
index 40030c5d5..000000000
--- a/docs/ts-sdk-reference/tasks.mdx
+++ /dev/null
@@ -1,305 +0,0 @@
----
-title: Tasks
-subtitle: Run single browser automations with natural language
-description: Use the Skyvern TypeScript SDK to run, monitor, cancel, and retrieve browser automation tasks with the runTask, getRun, and cancelRun methods.
-slug: ts-sdk-reference/tasks
-keywords:
- - runTask
- - getRun
- - cancelRun
- - getRunTimeline
- - getRunArtifacts
- - retryRunWebhook
- - data extraction
- - polling
- - webhook
- - maxSteps
- - engine
- - proxy
- - TOTP
- - 2FA
- - artifact
----
-
-A task is a single browser automation. You describe what you want in natural language — Skyvern opens a browser, navigates to the URL, and executes the instructions with AI.
-
-For when to use tasks vs workflows, see [Run a Task](/running-automations/run-a-task).
-
----
-
-## `runTask`
-
-Start a browser automation. Skyvern opens a cloud browser, navigates to the URL, and executes your prompt with AI.
-
-```typescript
-const result = await skyvern.runTask({
- body: {
- prompt: "Get the title of the top post",
- url: "https://news.ycombinator.com",
- },
- waitForCompletion: true,
-});
-console.log(result.output);
-```
-
-### Parameters
-
-The `runTask` method accepts a single request object with the following shape:
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `body.prompt` | `string` | Yes | — | Natural language instructions for what the AI should do. |
-| `body.url` | `string` | No | `undefined` | Starting page URL. If omitted, the AI navigates from a blank page. |
-| `body.engine` | `RunEngine` | No | `"skyvern_v2"` | AI engine. Options: `"skyvern_v2"`, `"skyvern_v1"`, `"openai_cua"`, `"anthropic_cua"`, `"ui_tars"`. |
-| `body.max_steps` | `number` | No | `undefined` | Cap the number of AI steps to limit cost. Run terminates with `timed_out` if hit. |
-| `body.data_extraction_schema` | `Record<string, unknown> \| string` | No | `undefined` | JSON schema constraining the output shape. |
-| `body.proxy_location` | `ProxyLocation` | No | `undefined` | Route the browser through a geographic proxy. |
-| `body.browser_session_id` | `string` | No | `undefined` | Run inside an existing [browser session](/optimization/browser-sessions). |
-| `body.publish_workflow` | `boolean` | No | `false` | Save the generated code as a reusable workflow. Only works with `skyvern_v2`. |
-| `body.webhook_url` | `string` | No | `undefined` | URL to receive a POST when the run finishes. |
-| `body.error_code_mapping` | `Record<string, string>` | No | `undefined` | Map custom error codes to failure reasons. |
-| `body.totp_identifier` | `string` | No | `undefined` | Identifier for TOTP verification. |
-| `body.totp_url` | `string` | No | `undefined` | URL to receive TOTP codes. |
-| `body.title` | `string` | No | `undefined` | Display name for this run in the dashboard. |
-| `body.model` | `Record<string, unknown>` | No | `undefined` | Override the output model definition. |
-| `body.user_agent` | `string` | No | `undefined` | Custom User-Agent header for the browser. |
-| `body.extra_http_headers` | `Record<string, string>` | No | `undefined` | Additional HTTP headers injected into every browser request. |
-| `body.browser_address` | `string` | No | `undefined` | Connect to a browser at this CDP address instead of spinning up a new one. |
-| `waitForCompletion` | `boolean` | No | `false` | Block until the run finishes. |
-| `timeout` | `number` | No | `1800` | Max wait time in seconds when `waitForCompletion` is `true`. |
-
-### Returns `TaskRunResponse`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `run_id` | `string` | Unique identifier. Starts with `tsk_` for task runs. |
-| `status` | `string` | `"created"`, `"queued"`, `"running"`, `"completed"`, `"failed"`, `"terminated"`, `"timed_out"`, or `"canceled"`. |
-| `output` | `Record<string, unknown> \| null` | Extracted data from the run. Shape depends on your prompt or `data_extraction_schema`. |
-| `downloaded_files` | `FileInfo[] \| undefined` | Files downloaded during the run. |
-| `recording_url` | `string \| undefined` | URL to the session recording video. |
-| `screenshot_urls` | `string[] \| undefined` | Final screenshots (most recent first). |
-| `failure_reason` | `string \| undefined` | Error description if the run failed. |
-| `app_url` | `string \| undefined` | Link to view this run in the Cloud UI. |
-| `step_count` | `number \| undefined` | Number of AI steps taken. |
-| `script_run` | `ScriptRunResponse \| undefined` | Code execution result if the run used generated code. |
-| `created_at` | `string` | When the run was created. |
-| `finished_at` | `string \| undefined` | When the run finished. |
-
-### Examples
-
-**Extract structured data:**
-
-```typescript
-const result = await skyvern.runTask({
- body: {
- prompt: "Extract the name, price, and rating of the top 3 products",
- url: "https://example.com/products",
- data_extraction_schema: {
- type: "array",
- items: {
- type: "object",
- properties: {
- name: { type: "string" },
- price: { type: "string" },
- rating: { type: "number" },
- },
- },
- },
- },
- waitForCompletion: true,
-});
-console.log(result.output);
-// [{ name: "Widget A", price: "$29.99", rating: 4.5 }, ...]
-```
-
-**Run inside an existing browser session:**
-
-```typescript
-const session = await skyvern.createBrowserSession({});
-
-const result = await skyvern.runTask({
- body: {
- prompt: "Log in and download the latest invoice",
- url: "https://app.example.com/login",
- browser_session_id: session.browser_session_id,
- },
- waitForCompletion: true,
-});
-```
-
-**Limit cost with max_steps:**
-
-```typescript
-const result = await skyvern.runTask({
- body: {
- prompt: "Fill out the contact form",
- url: "https://example.com/contact",
- max_steps: 10,
- },
- waitForCompletion: true,
-});
-```
-
-**Publish as a reusable workflow:**
-
-```typescript
-const result = await skyvern.runTask({
- body: {
- prompt: "Fill out the contact form with the provided data",
- url: "https://example.com/contact",
- publish_workflow: true,
- },
- waitForCompletion: true,
-});
-// The generated workflow is saved and can be re-triggered via runWorkflow
-```
-
----
-
-## `getRun`
-
-Get the current status and results of any run (task or workflow).
-
-```typescript
-const run = await skyvern.getRun("tsk_v2_486305187432193504");
-console.log(run.status, run.output);
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `runId` | `string` | Yes | The run ID returned by `runTask` or `runWorkflow`. |
-
-### Returns `GetRunResponse`
-
-A discriminated union based on `run_type`. All variants share the same core fields as `TaskRunResponse` above, plus a `run_type` field (`task_v1`, `task_v2`, `openai_cua`, `anthropic_cua`, `ui_tars`, `workflow_run`).
-
-Workflow run responses additionally include `run_with` and `ai_fallback` fields.
-
----
-
-## `cancelRun`
-
-Cancel a running or queued run.
-
-```typescript
-await skyvern.cancelRun("tsk_v2_486305187432193504");
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `runId` | `string` | Yes | The run ID to cancel. |
-
-The run transitions to `canceled` status. If the run has already finished, this is a no-op.
-
----
-
-## `getRunTimeline`
-
-Get the step-by-step timeline of a run. Each entry represents one AI action with screenshots and reasoning.
-
-```typescript
-const timeline = await skyvern.getRunTimeline("tsk_v2_486305187432193504");
-for (const step of timeline) {
- console.log(`Step ${step.order}: ${step.type} — ${step.status}`);
-}
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `runId` | `string` | Yes | The run ID. |
-
-### Returns `WorkflowRunTimeline[]`
-
-Each timeline entry contains step details including type, status, order, and associated artifacts.
-
----
-
-## `getRunArtifacts`
-
-Get all artifacts (screenshots, recordings, generated code, etc.) for a run.
-
-```typescript
-const artifacts = await skyvern.getRunArtifacts("tsk_v2_486305187432193504");
-for (const artifact of artifacts) {
- console.log(`${artifact.artifact_type}: ${artifact.uri}`);
-}
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `runId` | `string` | Yes | The run ID. |
-| `artifactType` | `ArtifactType \| ArtifactType[]` | No | Filter by artifact type. |
-
-### Returns `Artifact[]`
-
----
-
-## `getArtifact`
-
-Get a single artifact by ID.
-
-```typescript
-const artifact = await skyvern.getArtifact("art_486305187432193504");
-console.log(artifact.uri);
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `artifactId` | `string` | Yes | The artifact ID. |
-
-### Returns `Artifact`
-
----
-
-## `retryRunWebhook`
-
-Re-send the webhook notification for a completed run. Useful if your webhook endpoint was down when the run finished.
-
-```typescript
-await skyvern.retryRunWebhook("tsk_v2_486305187432193504");
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `runId` | `string` | Yes | The run ID. |
-
----
-
-## Polling pattern
-
-If you don't use `waitForCompletion`, poll `getRun` manually:
-
-```typescript
-const task = await skyvern.runTask({
- body: {
- prompt: "Extract product data",
- url: "https://example.com/products",
- },
-});
-
-const terminalStatuses = ["completed", "failed", "terminated", "timed_out", "canceled"];
-let run;
-while (true) {
- run = await skyvern.getRun(task.run_id);
- if (terminalStatuses.includes(run.status)) break;
- await new Promise((resolve) => setTimeout(resolve, 5000));
-}
-
-console.log(run.output);
-```
-
-<Tip>
-For production, prefer `waitForCompletion: true` or [webhooks](/going-to-production/webhooks) over manual polling.
-</Tip>
diff --git a/docs/ts-sdk-reference/workflows.mdx b/docs/ts-sdk-reference/workflows.mdx
deleted file mode 100644
index 992667205..000000000
--- a/docs/ts-sdk-reference/workflows.mdx
+++ /dev/null
@@ -1,287 +0,0 @@
----
-title: Workflows
-subtitle: Create and run multi-step browser automations
-description: Use the Skyvern TypeScript SDK to execute, monitor, and manage multi-step workflows with the runWorkflow method, including parameter passing and browser session reuse.
-slug: ts-sdk-reference/workflows
-keywords:
- - runWorkflow
- - createWorkflow
- - getWorkflow
- - updateWorkflow
- - deleteWorkflow
- - getWorkflowVersions
- - parameter
- - block
- - YAML
- - JSON
- - template
- - version
----
-
-A workflow chains multiple steps (blocks) into a single automation. Workflows support loops, conditionals, data passing between steps, and code-based re-execution.
-
-For conceptual background, see [Build a Workflow](/multi-step-automations/build-a-workflow).
-
----
-
-## `runWorkflow`
-
-Execute a workflow by its permanent ID. Skyvern opens a cloud browser and runs each block in sequence.
-
-```typescript
-const result = await skyvern.runWorkflow({
- body: {
- workflow_id: "wpid_abc123",
- },
- waitForCompletion: true,
-});
-console.log(result.output);
-```
-
-### Parameters
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `body.workflow_id` | `string` | Yes | — | The workflow's permanent ID (`wpid_...`). |
-| `body.parameters` | `Record<string, unknown>` | No | `undefined` | Input parameters defined in the workflow. Keys must match parameter names. |
-| `body.browser_session_id` | `string` | No | `undefined` | Run inside an existing [browser session](/optimization/browser-sessions). |
-| `body.browser_profile_id` | `string` | No | `undefined` | Load a [browser profile](/optimization/browser-profiles) (cookies, storage) into the session. |
-| `body.proxy_location` | `ProxyLocation` | No | `undefined` | Route the browser through a geographic proxy. |
-| `body.webhook_url` | `string` | No | `undefined` | URL to receive a POST when the run finishes. |
-| `body.title` | `string` | No | `undefined` | Display name for this run in the dashboard. |
-| `body.totp_identifier` | `string` | No | `undefined` | Identifier for TOTP verification. |
-| `body.totp_url` | `string` | No | `undefined` | URL to receive TOTP codes. |
-| `body.user_agent` | `string` | No | `undefined` | Custom User-Agent header for the browser. |
-| `body.extra_http_headers` | `Record<string, string>` | No | `undefined` | Additional HTTP headers injected into every browser request. |
-| `body.browser_address` | `string` | No | `undefined` | Connect to a browser at this CDP address. |
-| `template` | `boolean` | No | `undefined` | Run a template workflow. |
-| `waitForCompletion` | `boolean` | No | `false` | Block until the workflow finishes. |
-| `timeout` | `number` | No | `1800` | Max wait time in seconds when `waitForCompletion` is `true`. |
-
-### Returns `WorkflowRunResponse`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `run_id` | `string` | Unique identifier. Starts with `wr_` for workflow runs. |
-| `status` | `string` | `"created"`, `"queued"`, `"running"`, `"completed"`, `"failed"`, `"terminated"`, `"timed_out"`, or `"canceled"`. |
-| `output` | `Record<string, unknown> \| null` | Extracted data from the workflow's output block. |
-| `downloaded_files` | `FileInfo[] \| undefined` | Files downloaded during the run. |
-| `recording_url` | `string \| undefined` | URL to the session recording. |
-| `failure_reason` | `string \| undefined` | Error description if the run failed. |
-| `app_url` | `string \| undefined` | Link to view this run in the Cloud UI. |
-| `step_count` | `number \| undefined` | Total AI steps taken across all blocks. |
-| `run_with` | `string \| undefined` | Whether the run used `"code"` or `"agent"`. |
-| `ai_fallback` | `boolean \| undefined` | Whether AI fallback was configured. |
-| `script_run` | `ScriptRunResponse \| undefined` | Code execution result. Contains `ai_fallback_triggered` if code was used. |
-
-### Examples
-
-**Pass parameters to a workflow:**
-
-```typescript
-const result = await skyvern.runWorkflow({
- body: {
- workflow_id: "wpid_invoice_extraction",
- parameters: {
- company_name: "Acme Corp",
- date_range: "2025-01-01 to 2025-12-31",
- },
- },
- waitForCompletion: true,
-});
-```
-
-**Run with a browser profile (skip login):**
-
-```typescript
-const result = await skyvern.runWorkflow({
- body: {
- workflow_id: "wpid_daily_report",
- browser_profile_id: "bpf_abc123",
- },
- waitForCompletion: true,
-});
-```
-
----
-
-## `createWorkflow`
-
-Create a new workflow from a JSON or YAML definition.
-
-```typescript
-const workflow = await skyvern.createWorkflow({
- body: {
- json_definition: {
- title: "Extract Products",
- workflow_definition: {
- parameters: [
- {
- key: "target_url",
- parameter_type: "workflow",
- workflow_parameter_type: "string",
- description: "URL to scrape",
- },
- ],
- blocks: [
- {
- block_type: "task",
- label: "extract",
- prompt: "Extract the top 3 products with name and price",
- url: "{{ target_url }}",
- },
- ],
- },
- },
- },
-});
-console.log(workflow.workflow_permanent_id);
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `body.json_definition` | `object` | No | Workflow definition as a JSON object. |
-| `body.yaml_definition` | `string` | No | Workflow definition as a YAML string. |
-| `folder_id` | `string` | No | Folder to organize the workflow in. |
-
-You must provide either `body.json_definition` or `body.yaml_definition`.
-
-### Returns `Workflow`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `workflow_id` | `string` | Unique ID for this version. |
-| `workflow_permanent_id` | `string` | Stable ID across all versions. Use this to run workflows. |
-| `version` | `number` | Version number. |
-| `title` | `string` | Workflow title. |
-| `workflow_definition` | `WorkflowDefinition` | The full definition including blocks and parameters. |
-| `status` | `string \| undefined` | Workflow status. |
-| `created_at` | `string` | When the workflow was created. |
-
----
-
-## `getWorkflows`
-
-List all workflows. Supports filtering and pagination.
-
-```typescript
-const workflows = await skyvern.getWorkflows({});
-for (const wf of workflows) {
- console.log(`${wf.title} (${wf.workflow_permanent_id})`);
-}
-```
-
-### Parameters
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `page` | `number` | No | `undefined` | Page number for pagination. |
-| `page_size` | `number` | No | `undefined` | Number of results per page. |
-| `only_saved_tasks` | `boolean` | No | `undefined` | Only return saved tasks. |
-| `only_workflows` | `boolean` | No | `undefined` | Only return workflows (not saved tasks). |
-| `only_templates` | `boolean` | No | `undefined` | Only return templates. |
-| `title` | `string` | No | `undefined` | Filter by exact title. |
-| `search_key` | `string` | No | `undefined` | Search by title. |
-| `folder_id` | `string` | No | `undefined` | Filter by folder. |
-| `status` | `WorkflowStatus \| WorkflowStatus[]` | No | `undefined` | Filter by status. |
-
-### Returns `Workflow[]`
-
----
-
-## `getWorkflow`
-
-Get a specific workflow by its permanent ID.
-
-```typescript
-const workflow = await skyvern.getWorkflow("wpid_abc123");
-console.log(workflow.title, `v${workflow.version}`);
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `workflowPermanentId` | `string` | Yes | The workflow's permanent ID. |
-| `version` | `number` | No | Specific version to retrieve. Defaults to latest. |
-| `template` | `boolean` | No | Whether to fetch a template workflow. |
-
-### Returns `Workflow`
-
----
-
-## `getWorkflowVersions`
-
-List all versions of a workflow.
-
-```typescript
-const versions = await skyvern.getWorkflowVersions("wpid_abc123");
-for (const v of versions) {
- console.log(`v${v.version} — ${v.modified_at}`);
-}
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `workflowPermanentId` | `string` | Yes | The workflow's permanent ID. |
-| `template` | `boolean` | No | Whether to fetch template versions. |
-
-### Returns `Workflow[]`
-
----
-
-## `updateWorkflow`
-
-Update an existing workflow's definition.
-
-```typescript
-const updated = await skyvern.updateWorkflow("wpid_abc123", {
- json_definition: {
- title: "Extract Products Updated",
- workflow_definition: {
- blocks: [
- {
- block_type: "task",
- label: "extract_data",
- prompt: "Extract the top 5 products",
- url: "https://example.com/products",
- },
- ],
- parameters: [],
- },
- },
-});
-console.log(`Updated to v${updated.version}`);
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `workflowId` | `string` | Yes | The workflow's permanent ID (`wpid_...`). |
-| `json_definition` | `object` | No | Updated workflow definition as JSON. |
-| `yaml_definition` | `string` | No | Updated workflow definition as YAML. |
-
-### Returns `Workflow`
-
-Creates a new version of the workflow.
-
----
-
-## `deleteWorkflow`
-
-Delete a workflow.
-
-```typescript
-await skyvern.deleteWorkflow("wf_abc123");
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `workflowId` | `string` | Yes | The workflow version ID to delete. |