Skip to content

Automate browser based workflows with AI

Apply the merged-but-unapplied Datadog monitor definitions, and make route-5xx applyable (SKY-15449) (#8935)

Aaron Perez8604b8d4df96
diff --git a/docs/browsers.mdx b/docs/browsers.mdx
index 45a0b8b12..a4aadb176 100644
--- a/docs/browsers.mdx
+++ b/docs/browsers.mdx
@@ -142,6 +142,16 @@ Use a session when you need a browser right now. Use a profile when you want to
A session's `status` is `running` while it is usable, then `completed` (closed), `timeout` (ran out) or `failed`.
+ **A run sent to a session that has already ended** is refused before the run is created, so it is never billed and never appears in your run history. The response body carries a stable `error_code` to branch on, so a scheduled caller does not have to match on the message text:
+
+ | `error_code` | Status | What to do |
+ |---|---|---|
+ | `browser_session_expired` | `410` | The session ran out its lifetime. Re-sending the same id will always fail. Create a new session and pass the new id, or omit `browser_session_id` to start a fresh browser. |
+ | `browser_session_closed` | `410` | The session ended for another reason, such as being closed. Create a new session. |
+ | `browser_session_startup_timeout` | `504` | The session timed out before starting. Re-sending the same id will fail. Create a new session and pass its id, or omit `browser_session_id` to start a fresh browser. |
+
+ If you pin a session id in a recurring job, treat all three codes as terminal for that session id: create a new session or omit `browser_session_id`, rather than retrying the same id on the next tick.
+
**Extend a running session.** Each call adds minutes, up to 6 hours in total since the session started. Read the new `timeout` from the response; a retried call adds again. The call returns `409` if the session has ended, has under two minutes left, or is already at 6 hours. The TypeScript SDK has no `extendBrowserSession` method yet; call the REST endpoint.
<CodeGroup>
diff --git a/docs/sdk-reference/agents.mdx b/docs/sdk-reference/agents.mdx
index 7000d6c89..f1029b251 100644
--- a/docs/sdk-reference/agents.mdx
+++ b/docs/sdk-reference/agents.mdx
@@ -55,30 +55,135 @@ skyvern.runWorkflow(request: RunWorkflowOptions): Promise<WorkflowRunResponse>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `workflow_id` | `agent_id` | `str` | Yes | — | ID of the agent (`wpid_…`). |
-| `parameters` | `parameters` | `dict[str, Any] \| None` | No | `None` | Parameters to pass to the workflow |
-| `template` | `template` | `bool \| None` | No | `None` | |
-| `title` | `title` | `str \| None` | No | `None` | The title for this workflow run |
-| `proxy_location` | `proxy_location` | `ProxyLocationInput` | No | `None` | Geographic Proxy location to route the browser traffic through. This is only available in Skyvern Cloud. |
-| `webhook_url` | `webhook_url` | `str \| None` | No | `None` | URL to send workflow status updates to after a run is finished. Refer to https://www.skyvern.com/docs/running-tasks/webhooks-faq for webhook questions. |
-| `totp_url` | `totp_url` | `str \| None` | No | `None` | URL that serves TOTP/2FA/MFA codes for Skyvern to use during the workflow run. Refer to https://www.skyvern.com/docs/credentials/totp#option-2-get-code-from-your-endpoint for more details. |
-| `totp_identifier` | `totp_identifier` | `str \| None` | No | `None` | Identifier for the TOTP/2FA/MFA code when the code is pushed to Skyvern. Refer to https://www.skyvern.com/docs/credentials/totp#option-3-push-code-to-skyvern for more details. |
-| `browser_session_id` | `browser_session_id` | `str \| None` | No | `None` | ID of a Skyvern browser session to reuse, having it continue from the current screen state |
-| `max_steps_override` | `x-max-steps-override` | `int \| None` | No | `None` | Override the agent's maximum number of steps for this run. |
-| `user_agent` | `x-user-agent` | `str \| None` | No | `None` | User-Agent string the browser sends. |
-| `browser_profile_id` | `browser_profile_id` | `str \| None` | No | `None` | ID of a browser profile to reuse for this workflow run |
-| `max_screenshot_scrolls` | `max_screenshot_scrolls` | `int \| None` | No | `None` | The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot. |
-| `max_elapsed_time_minutes` | `max_elapsed_time_minutes` | `int \| None` | No | `None` | Timeout this workflow run after the configured elapsed runtime in minutes. When omitted, the platform default is 240 minutes. The maximum configurable value is 480 minutes. |
-| `extra_http_headers` | `extra_http_headers` | `dict[str, str] \| None` | No | `None` | The extra HTTP headers for the requests in browser. |
-| `browser_address` | `browser_address` | `str \| None` | No | `None` | The CDP address for the workflow run. |
-| `ai_fallback` | `ai_fallback` | `bool \| None` | No | `None` | Whether to fallback to AI if the workflow run fails. |
-| `run_with` | `run_with` | `str \| None` | No | `None` | Whether to run the workflow with agent or code. Null inherits from the workflow setting. |
-| `run_metadata` | `run_metadata` | `dict[str, str] \| None` | No | `None` | String key/value metadata to attach to this workflow run for analytics tag filtering. |
-| `wait_for_completion` | `waitForCompletion` | `bool` | No | `False` | Wait for the run to reach a final status before returning. |
-| `timeout` | `timeout` | `float` | No | `1800` | Maximum time to wait for completion, in seconds. |
-| — | `cdp_connect_headers` | `Record<string, string \| undefined>` | No | — | HTTP headers attached ONLY to the CDP WebSocket handshake when connecting to a remote browser via browser_address. Use this for browser-provider auth (e.g., x-api-key for Skyvern Cloud, Browserless, or similar). These headers are NEVER forwarded to target websites. |
+<ParamField path={"workflow_id"} type={"str"} required>
+ID of the agent (`wpid_…`).
+
+TypeScript: `agent_id`
+</ParamField>
+
+<ParamField path={"parameters"} type={"dict[str, Any] | None"}>
+Parameters to pass to the workflow
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"template"} type={"bool | None"}>
+Default: `None`
+</ParamField>
+
+<ParamField path={"title"} type={"str | None"}>
+The title for this workflow run
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"proxy_location"} type={"ProxyLocationInput"}>
+Geographic Proxy location to route the browser traffic through. This is only available in Skyvern Cloud.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"webhook_url"} type={"str | None"}>
+URL to send workflow status updates to after a run is finished. Refer to https://www.skyvern.com/docs/running-tasks/webhooks-faq for webhook questions.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"totp_url"} type={"str | None"}>
+URL that serves TOTP/2FA/MFA codes for Skyvern to use during the workflow run. Refer to https://www.skyvern.com/docs/credentials/totp#option-2-get-code-from-your-endpoint for more details.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"totp_identifier"} type={"str | None"}>
+Identifier for the TOTP/2FA/MFA code when the code is pushed to Skyvern. Refer to https://www.skyvern.com/docs/credentials/totp#option-3-push-code-to-skyvern for more details.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"browser_session_id"} type={"str | None"}>
+ID of a Skyvern browser session to reuse, having it continue from the current screen state
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"max_steps_override"} type={"int | None"}>
+Override the agent's maximum number of steps for this run.
+
+Default: `None` · TypeScript: `x-max-steps-override`
+</ParamField>
+
+<ParamField path={"user_agent"} type={"str | None"}>
+User-Agent string the browser sends.
+
+Default: `None` · TypeScript: `x-user-agent`
+</ParamField>
+
+<ParamField path={"browser_profile_id"} type={"str | None"}>
+ID of a browser profile to reuse for this workflow run
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"max_screenshot_scrolls"} type={"int | None"}>
+The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"max_elapsed_time_minutes"} type={"int | None"}>
+Timeout this workflow run after the configured elapsed runtime in minutes. When omitted, the platform default is 240 minutes. The maximum configurable value is 480 minutes.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"extra_http_headers"} type={"dict[str, str] | None"}>
+The extra HTTP headers for the requests in browser.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"browser_address"} type={"str | None"}>
+The CDP address for the workflow run.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"ai_fallback"} type={"bool | None"}>
+Whether to fallback to AI if the workflow run fails.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"run_with"} type={"str | None"}>
+Whether to run the workflow with agent or code. Null inherits from the workflow setting.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"run_metadata"} type={"dict[str, str] | None"}>
+String key/value metadata to attach to this workflow run for analytics tag filtering.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"wait_for_completion"} type={"bool"}>
+Wait for the run to reach a final status before returning.
+
+Default: `False` · TypeScript: `waitForCompletion`
+</ParamField>
+
+<ParamField path={"timeout"} type={"float"}>
+Maximum time to wait for completion, in seconds.
+
+Default: `1800`
+</ParamField>
+
+<ParamField path={"cdp_connect_headers"} type={"Record<string, string | undefined>"}>
+HTTP headers attached ONLY to the CDP WebSocket handshake when connecting to a remote browser via browser_address. Use this for browser-provider auth (e.g., x-api-key for Skyvern Cloud, Browserless, or similar). These headers are NEVER forwarded to target websites.
+
+TypeScript only
+</ParamField>
**Returns** `WorkflowRunResponse` · TypeScript `Promise<WorkflowRunResponse>`
@@ -163,11 +268,23 @@ skyvern.retryWorkflowRun(workflowRunId: string, request?: RetryWorkflowRunReques
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `workflow_run_id` | `workflowRunId` | `str` | Yes | — | The id of the workflow run to retry. |
-| `max_steps_override` | `x-max-steps-override` | `int \| None` | No | `None` | Override the agent's maximum number of steps for this run. |
-| `user_agent` | `x-user-agent` | `str \| None` | No | `None` | User-Agent string the browser sends. |
+<ParamField path={"workflow_run_id"} type={"str"} required>
+The id of the workflow run to retry.
+
+TypeScript: `workflowRunId`
+</ParamField>
+
+<ParamField path={"max_steps_override"} type={"int | None"}>
+Override the agent's maximum number of steps for this run.
+
+Default: `None` · TypeScript: `x-max-steps-override`
+</ParamField>
+
+<ParamField path={"user_agent"} type={"str | None"}>
+User-Agent string the browser sends.
+
+Default: `None` · TypeScript: `x-user-agent`
+</ParamField>
**Returns** `WorkflowRunResponse` · TypeScript `Promise<WorkflowRunResponse>`
@@ -252,12 +369,27 @@ skyvern.createWorkflow(request: CreateWorkflowRequest): Promise<Workflow>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `folder_id` | `folder_id` | `str \| None` | No | `None` | Optional folder ID to assign the workflow to |
-| `json_definition` | `body.json_definition` | `WorkflowCreateYamlRequest \| None` | No | — | Workflow definition in JSON format |
-| `yaml_definition` | `body.yaml_definition` | `str \| None` | No | — | Workflow definition in YAML format |
-| — | `body` | `WorkflowRequest` | No | — | TypeScript only. |
+<ParamField path={"folder_id"} type={"str | None"}>
+Optional folder ID to assign the workflow to
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"json_definition"} type={"WorkflowCreateYamlRequest | None"}>
+Workflow definition in JSON format
+
+Sent only when you pass it · TypeScript: `body.json_definition`
+</ParamField>
+
+<ParamField path={"yaml_definition"} type={"str | None"}>
+Workflow definition in YAML format
+
+Sent only when you pass it · TypeScript: `body.yaml_definition`
+</ParamField>
+
+<ParamField path={"body"} type={"WorkflowRequest"} required>
+TypeScript only
+</ParamField>
**Returns** `Workflow` · TypeScript `Promise<Workflow>`
@@ -391,11 +523,19 @@ skyvern.getWorkflow(workflowPermanentId: string, request?: GetWorkflowRequest):
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `workflow_permanent_id` | `workflowPermanentId` | `str` | Yes | — | ID of the agent (`wpid_…`). |
-| `version` | `version` | `int \| None` | No | `None` | |
-| `template` | `template` | `bool \| None` | No | `None` | |
+<ParamField path={"workflow_permanent_id"} type={"str"} required>
+ID of the agent (`wpid_…`).
+
+TypeScript: `workflowPermanentId`
+</ParamField>
+
+<ParamField path={"version"} type={"int | None"}>
+Default: `None`
+</ParamField>
+
+<ParamField path={"template"} type={"bool | None"}>
+Default: `None`
+</ParamField>
**Returns** `Workflow` · TypeScript `Promise<Workflow>`
@@ -512,19 +652,57 @@ skyvern.getWorkflows(request?: GetWorkflowsRequest): Promise<Workflow[]>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `page` | `page` | `int \| None` | No | `None` | |
-| `page_size` | `page_size` | `int \| None` | No | `None` | |
-| `only_saved_tasks` | `only_saved_tasks` | `bool \| None` | No | `None` | |
-| `only_workflows` | `only_workflows` | `bool \| None` | No | `None` | |
-| `only_templates` | `only_templates` | `bool \| None` | No | `None` | |
-| `search_key` | `search_key` | `str \| None` | No | `None` | Case-insensitive substring search across: workflow title, folder name, and parameter metadata (key, description, default_value). A workflow is returned if any of these fields match. Soft-deleted parameter definitions are excluded. Takes precedence over the deprecated `title` parameter. |
-| `title` | `title` | `str \| None` | No | `None` | Deprecated: use search_key instead. Falls back to title-only search if search_key is not provided. |
-| `folder_id` | `folder_id` | `str \| None` | No | `None` | Filter workflows by folder ID |
-| `status` | `status` | `WorkflowStatus \| Sequence[WorkflowStatus] \| None` | No | `None` | |
-| `tags` | `tags` | `str \| Sequence[str] \| None` | No | `None` | Filter by tags. Each term is a label (`production`), a group (`env:*`), or a group:label (`env:prod`). Repeat the param or comma-separate (`?tags=env:prod,env:staging`). AND across distinct terms, OR within a group's labels (`?tags=customer:acme,env:prod,env:staging` -&gt; customer=acme AND env in (prod, staging)). A label term matches the value across any/no group. Matches current tag values only. Not supported with `template=true`. |
-| `template` | `template` | `bool \| None` | No | `None` | |
+<ParamField path={"page"} type={"int | None"}>
+Default: `None`
+</ParamField>
+
+<ParamField path={"page_size"} type={"int | None"}>
+Default: `None`
+</ParamField>
+
+<ParamField path={"only_saved_tasks"} type={"bool | None"}>
+Default: `None`
+</ParamField>
+
+<ParamField path={"only_workflows"} type={"bool | None"}>
+Default: `None`
+</ParamField>
+
+<ParamField path={"only_templates"} type={"bool | None"}>
+Default: `None`
+</ParamField>
+
+<ParamField path={"search_key"} type={"str | None"}>
+Case-insensitive substring search across: workflow title, folder name, and parameter metadata (key, description, default_value). A workflow is returned if any of these fields match. Soft-deleted parameter definitions are excluded. Takes precedence over the deprecated `title` parameter.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"title"} type={"str | None"}>
+Deprecated: use search_key instead. Falls back to title-only search if search_key is not provided.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"folder_id"} type={"str | None"}>
+Filter workflows by folder ID
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"status"} type={"WorkflowStatus | Sequence[WorkflowStatus] | None"}>
+Default: `None`
+</ParamField>
+
+<ParamField path={"tags"} type={"str | Sequence[str] | None"}>
+Filter by tags. Each term is a label (`production`), a group (`env:*`), or a group:label (`env:prod`). Repeat the param or comma-separate (`?tags=env:prod,env:staging`). AND across distinct terms, OR within a group's labels (`?tags=customer:acme,env:prod,env:staging` -&gt; customer=acme AND env in (prod, staging)). A label term matches the value across any/no group. Matches current tag values only. Not supported with `template=true`.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"template"} type={"bool | None"}>
+Default: `None`
+</ParamField>
**Returns** `list[Workflow]` · TypeScript `Promise<Workflow[]>`
@@ -625,10 +803,15 @@ skyvern.getWorkflowVersions(workflowPermanentId: string, request?: GetWorkflowVe
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `workflow_permanent_id` | `workflowPermanentId` | `str` | Yes | — | ID of the agent (`wpid_…`). |
-| `template` | `template` | `bool \| None` | No | `None` | |
+<ParamField path={"workflow_permanent_id"} type={"str"} required>
+ID of the agent (`wpid_…`).
+
+TypeScript: `workflowPermanentId`
+</ParamField>
+
+<ParamField path={"template"} type={"bool | None"}>
+Default: `None`
+</ParamField>
**Returns** `list[Workflow]` · TypeScript `Promise<Workflow[]>`
@@ -730,11 +913,23 @@ skyvern.updateWorkflow(workflowId: string, request: WorkflowRequest): Promise<Wo
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `workflow_id` | `workflowId` | `str` | Yes | — | The ID of the agent to update. Starts with `wpid_`. |
-| `json_definition` | `json_definition` | `WorkflowCreateYamlRequest \| None` | No | — | Workflow definition in JSON format |
-| `yaml_definition` | `yaml_definition` | `str \| None` | No | — | Workflow definition in YAML format |
+<ParamField path={"workflow_id"} type={"str"} required>
+The ID of the agent to update. Starts with `wpid_`.
+
+TypeScript: `workflowId`
+</ParamField>
+
+<ParamField path={"json_definition"} type={"WorkflowCreateYamlRequest | None"}>
+Workflow definition in JSON format
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"yaml_definition"} type={"str | None"}>
+Workflow definition in YAML format
+
+Sent only when you pass it
+</ParamField>
**Returns** `Workflow` · TypeScript `Promise<Workflow>`
@@ -862,11 +1057,13 @@ skyvern.deleteWorkflow(workflowId: string): Promise<unknown>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `workflow_id` | `workflowId` | `str` | Yes | — | The ID of the agent to delete. Starts with `wpid_`. |
+<ParamField path={"workflow_id"} type={"str"} required>
+The ID of the agent to delete. Starts with `wpid_`.
-**Returns** `Any \| None` · TypeScript `Promise<unknown>`
+TypeScript: `workflowId`
+</ParamField>
+
+**Returns** `Any | None` · TypeScript `Promise<unknown>`
**Example**
@@ -947,13 +1144,35 @@ skyvern.getWorkflowRuns(request?: GetWorkflowRunsRequest): Promise<WorkflowRun[]
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `page` | `page` | `int \| None` | No | `None` | Page number for pagination. |
-| `page_size` | `page_size` | `int \| None` | No | `None` | Number of runs to return per page. |
-| `status` | `status` | `WorkflowRunStatus \| Sequence[WorkflowRunStatus] \| None` | No | `None` | Filter by one or more run statuses. |
-| `search_key` | `search_key` | `str \| None` | No | `None` | Case-insensitive substring search across: workflow run ID, parameter key, parameter description, run parameter value, and extra HTTP headers. A run is returned if any of these fields match. Soft-deleted parameter definitions are excluded from key/description matching. |
-| `error_code` | `error_code` | `str \| None` | No | `None` | Exact-match filter on the error_code field inside each task's errors JSON array. A run matches if any of its tasks contains an error with a matching error_code. Error codes are user-defined strings set during workflow execution. |
+<ParamField path={"page"} type={"int | None"}>
+Page number for pagination.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"page_size"} type={"int | None"}>
+Number of runs to return per page.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"status"} type={"WorkflowRunStatus | Sequence[WorkflowRunStatus] | None"}>
+Filter by one or more run statuses.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"search_key"} type={"str | None"}>
+Case-insensitive substring search across: workflow run ID, parameter key, parameter description, run parameter value, and extra HTTP headers. A run is returned if any of these fields match. Soft-deleted parameter definitions are excluded from key/description matching.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"error_code"} type={"str | None"}>
+Exact-match filter on the error_code field inside each task's errors JSON array. A run matches if any of its tasks contains an error with a matching error_code. Error codes are user-defined strings set during workflow execution.
+
+Default: `None`
+</ParamField>
**Returns** `list[WorkflowRun]` · TypeScript `Promise<WorkflowRun[]>`
@@ -1069,16 +1288,53 @@ skyvern.getWorkflowRunsById(workflowId: string, request?: GetWorkflowRunsByIdReq
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `workflow_id` | `workflowId` | `str` | Yes | — | ID of the agent (`wpid_…`). |
-| `page` | `page` | `int \| None` | No | `None` | Page number for pagination. |
-| `page_size` | `page_size` | `int \| None` | No | `None` | Number of runs to return per page. |
-| `status` | `status` | `WorkflowRunStatus \| Sequence[WorkflowRunStatus] \| None` | No | `None` | Filter by one or more run statuses. |
-| `search_key` | `search_key` | `str \| None` | No | `None` | Case-insensitive substring search across: workflow run ID, parameter key, parameter description, run parameter value, and extra HTTP headers. A run is returned if any of these fields match. Soft-deleted parameter definitions are excluded from key/description matching. |
-| `error_code` | `error_code` | `str \| None` | No | `None` | Exact-match filter on the error_code field inside each task's errors JSON array. A run matches if any of its tasks contains an error with a matching error_code. Error codes are user-defined strings set during workflow execution. |
-| `created_at_start` | `created_at_start` | `datetime \| None` | No | `None` | Only include runs created at or after this UTC timestamp (ISO 8601). |
-| `created_at_end` | `created_at_end` | `datetime \| None` | No | `None` | Only include runs created strictly before this UTC timestamp (ISO 8601). |
+<ParamField path={"workflow_id"} type={"str"} required>
+ID of the agent (`wpid_…`).
+
+TypeScript: `workflowId`
+</ParamField>
+
+<ParamField path={"page"} type={"int | None"}>
+Page number for pagination.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"page_size"} type={"int | None"}>
+Number of runs to return per page.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"status"} type={"WorkflowRunStatus | Sequence[WorkflowRunStatus] | None"}>
+Filter by one or more run statuses.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"search_key"} type={"str | None"}>
+Case-insensitive substring search across: workflow run ID, parameter key, parameter description, run parameter value, and extra HTTP headers. A run is returned if any of these fields match. Soft-deleted parameter definitions are excluded from key/description matching.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"error_code"} type={"str | None"}>
+Exact-match filter on the error_code field inside each task's errors JSON array. A run matches if any of its tasks contains an error with a matching error_code. Error codes are user-defined strings set during workflow execution.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"created_at_start"} type={"datetime | None"}>
+Only include runs created at or after this UTC timestamp (ISO 8601).
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"created_at_end"} type={"datetime | None"}>
+Only include runs created strictly before this UTC timestamp (ISO 8601).
+
+Default: `None`
+</ParamField>
**Returns** `list[WorkflowRun]` · TypeScript `Promise<WorkflowRun[]>`
diff --git a/docs/sdk-reference/artifacts.mdx b/docs/sdk-reference/artifacts.mdx
index 7732b10ad..5313cdb43 100644
--- a/docs/sdk-reference/artifacts.mdx
+++ b/docs/sdk-reference/artifacts.mdx
@@ -36,10 +36,15 @@ skyvern.getRunArtifacts(runId: string, request?: GetRunArtifactsRequest): Promis
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `run_id` | `runId` | `str` | Yes | — | The id of the task run or the workflow run. |
-| `artifact_type` | `artifact_type` | `ArtifactType \| Sequence[ArtifactType] \| None` | No | `None` | |
+<ParamField path={"run_id"} type={"str"} required>
+The id of the task run or the workflow run.
+
+TypeScript: `runId`
+</ParamField>
+
+<ParamField path={"artifact_type"} type={"ArtifactType | Sequence[ArtifactType] | None"}>
+Default: `None`
+</ParamField>
**Returns** `list[Artifact]` · TypeScript `Promise<Artifact[]>`
@@ -115,11 +120,11 @@ skyvern.artifacts.getArtifactContent(artifactId: string): Promise<unknown>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `artifact_id` | `artifactId` | `str` | Yes | — | |
+<ParamField path={"artifact_id"} type={"str"} required>
+TypeScript: `artifactId`
+</ParamField>
-**Returns** `Any \| None` · TypeScript `Promise<unknown>` — Raw artifact content
+**Returns** `Any | None` · TypeScript `Promise<unknown>` — Raw artifact content
**Example**
diff --git a/docs/sdk-reference/browser-automation/agent.mdx b/docs/sdk-reference/browser-automation/agent.mdx
index 88dca2106..d0b3d8173 100644
--- a/docs/sdk-reference/browser-automation/agent.mdx
+++ b/docs/sdk-reference/browser-automation/agent.mdx
@@ -44,21 +44,81 @@ page.agent.runTask(prompt: string, options?: { engine?: RunEngine; model?: Recor
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `prompt` | `prompt` | `str` | Yes | — | Natural language description of the task to perform. |
-| `engine` | `engine` | `RunEngine` | No | `RunEngine.skyvern_v1` | The engine that runs the task. Defaults to `skyvern_v1` (`"skyvern-1.0"`), suited to simple, single-goal tasks. `skyvern_v3` (`"skyvern-3.0"`) is the newest engine; the REST API and the Python SDK accept it, but the published TypeScript client's type does not list it yet. `skyvern_v2` remains for existing 2.0 runs. `openai_cua` and `anthropic_cua` use OpenAI's and Anthropic's computer-use models; `ui_tars` and `yutori_navigator` are also accepted. |
-| `model` | `model` | `dict[str, Any] \| None` | No | `None` | LLM model configuration options. |
-| `url` | `url` | `str \| None` | No | `None` | URL to navigate to. If not provided, uses the current page URL. |
-| `webhook_url` | `webhookUrl` | `str \| None` | No | `None` | URL to receive webhook notifications about task progress. |
-| `totp_identifier` | `totpIdentifier` | `str \| None` | No | `None` | Identifier for TOTP (Time-based One-Time Password) authentication. |
-| `totp_url` | `totpUrl` | `str \| None` | No | `None` | URL to fetch TOTP codes from. |
-| `title` | `title` | `str \| None` | No | `None` | Human-readable title for this task run. |
-| `error_code_mapping` | `errorCodeMapping` | `dict[str, str] \| None` | No | `None` | Mapping of error codes to custom error messages. |
-| `data_extraction_schema` | `dataExtractionSchema` | `dict[str, Any] \| str \| None` | No | `None` | Schema defining what data to extract from the page. |
-| `max_steps` | `maxSteps` | `int \| None` | No | `None` | Maximum number of steps the agent can take. |
-| `timeout` | `timeout` | `float` | No | `1800` | Maximum time in seconds to wait for task completion. |
-| `user_agent` | — | `str \| None` | No | `None` | Custom user agent string to use. |
+<ParamField path={"prompt"} type={"str"} required>
+Natural language description of the task to perform.
+</ParamField>
+
+<ParamField path={"engine"} type={"RunEngine"}>
+The engine that runs the task. Defaults to `skyvern_v1` (`"skyvern-1.0"`), suited to simple, single-goal tasks. `skyvern_v3` (`"skyvern-3.0"`) is the newest engine; the REST API and the Python SDK accept it, but the published TypeScript client's type does not list it yet. `skyvern_v2` remains for existing 2.0 runs. `openai_cua` and `anthropic_cua` use OpenAI's and Anthropic's computer-use models; `ui_tars` and `yutori_navigator` are also accepted.
+
+Default: `RunEngine.skyvern_v1`
+</ParamField>
+
+<ParamField path={"model"} type={"dict[str, Any] | None"}>
+LLM model configuration options.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"url"} type={"str | None"}>
+URL to navigate to. If not provided, uses the current page URL.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"webhook_url"} type={"str | None"}>
+URL to receive webhook notifications about task progress.
+
+Default: `None` · TypeScript: `webhookUrl`
+</ParamField>
+
+<ParamField path={"totp_identifier"} type={"str | None"}>
+Identifier for TOTP (Time-based One-Time Password) authentication.
+
+Default: `None` · TypeScript: `totpIdentifier`
+</ParamField>
+
+<ParamField path={"totp_url"} type={"str | None"}>
+URL to fetch TOTP codes from.
+
+Default: `None` · TypeScript: `totpUrl`
+</ParamField>
+
+<ParamField path={"title"} type={"str | None"}>
+Human-readable title for this task run.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"error_code_mapping"} type={"dict[str, str] | None"}>
+Mapping of error codes to custom error messages.
+
+Default: `None` · TypeScript: `errorCodeMapping`
+</ParamField>
+
+<ParamField path={"data_extraction_schema"} type={"dict[str, Any] | str | None"}>
+Schema defining what data to extract from the page.
+
+Default: `None` · TypeScript: `dataExtractionSchema`
+</ParamField>
+
+<ParamField path={"max_steps"} type={"int | None"}>
+Maximum number of steps the agent can take.
+
+Default: `None` · TypeScript: `maxSteps`
+</ParamField>
+
+<ParamField path={"timeout"} type={"float"}>
+Maximum time in seconds to wait for task completion.
+
+Default: `1800`
+</ParamField>
+
+<ParamField path={"user_agent"} type={"str | None"}>
+Custom user agent string to use.
+
+Default: `None` · Python only
+</ParamField>
**Returns** `TaskRunResponse` · TypeScript `Promise<TaskRunResponse>` — TaskRunResponse containing the task execution results.
@@ -200,25 +260,107 @@ page.agent.login(credentialType: "azure_vault", options: { azureVaultName: strin
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `credential_type` | `credentialType` | `CredentialType \| str` | No | `CredentialType.skyvern` | Type of credential store to use. Defaults to CredentialType.skyvern. |
-| `url` | `url` | `str \| None` | No | `None` | URL to navigate to for login. If not provided, uses the current page URL. |
-| `credential_id` | `credentialId` | `str \| None` | No | `None` | ID of the Skyvern credential to use (required for skyvern credential_type). |
-| `bitwarden_collection_id` | `bitwardenCollectionId` | `str \| None` | No | `None` | Bitwarden collection ID (optional for bitwarden credential_type). |
-| `bitwarden_item_id` | `bitwardenItemId` | `str \| None` | No | `None` | Bitwarden item ID (required for bitwarden credential_type). |
-| `onepassword_vault_id` | `onepasswordVaultId` | `str \| None` | No | `None` | 1Password vault ID (required for onepassword credential_type). |
-| `onepassword_item_id` | `onepasswordItemId` | `str \| None` | No | `None` | 1Password item ID (required for onepassword credential_type). |
-| `azure_vault_name` | `azureVaultName` | `str \| None` | No | `None` | Azure Vault name (required for azure_vault credential_type). |
-| `azure_vault_username_key` | `azureVaultUsernameKey` | `str \| None` | No | `None` | Azure Vault username key (required for azure_vault credential_type). |
-| `azure_vault_password_key` | `azureVaultPasswordKey` | `str \| None` | No | `None` | Azure Vault password key (required for azure_vault credential_type). |
-| `azure_vault_totp_secret_key` | `azureVaultTotpSecretKey` | `str \| None` | No | `None` | Azure Vault TOTP secret key (optional for azure_vault credential_type). |
-| `prompt` | `prompt` | `str \| None` | No | `None` | Additional instructions for the login process. |
-| `webhook_url` | `webhookUrl` | `str \| None` | No | `None` | URL to receive webhook notifications about login progress. |
-| `totp_identifier` | `totpIdentifier` | `str \| None` | No | `None` | Identifier for TOTP authentication. |
-| `totp_url` | `totpUrl` | `str \| None` | No | `None` | URL to fetch TOTP codes from. |
-| `extra_http_headers` | `extraHttpHeaders` | `dict[str, str] \| None` | No | `None` | Additional HTTP headers to include in requests. |
-| `timeout` | `timeout` | `float` | No | `1800` | Maximum time in seconds to wait for login completion. |
+<ParamField path={"credential_type"} type={"CredentialType | str"}>
+Type of credential store to use. Defaults to CredentialType.skyvern.
+
+Default: `CredentialType.skyvern` · TypeScript: `credentialType` (required)
+</ParamField>
+
+<ParamField path={"url"} type={"str | None"}>
+URL to navigate to for login. If not provided, uses the current page URL.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"credential_id"} type={"str | None"}>
+ID of the Skyvern credential to use (required for skyvern credential_type).
+
+Default: `None` · TypeScript: `credentialId`
+</ParamField>
+
+<ParamField path={"bitwarden_collection_id"} type={"str | None"}>
+Bitwarden collection ID (optional for bitwarden credential_type).
+
+Default: `None` · TypeScript: `bitwardenCollectionId`
+</ParamField>
+
+<ParamField path={"bitwarden_item_id"} type={"str | None"}>
+Bitwarden item ID (required for bitwarden credential_type).
+
+Default: `None` · TypeScript: `bitwardenItemId`
+</ParamField>
+
+<ParamField path={"onepassword_vault_id"} type={"str | None"}>
+1Password vault ID (required for onepassword credential_type).
+
+Default: `None` · TypeScript: `onepasswordVaultId`
+</ParamField>
+
+<ParamField path={"onepassword_item_id"} type={"str | None"}>
+1Password item ID (required for onepassword credential_type).
+
+Default: `None` · TypeScript: `onepasswordItemId`
+</ParamField>
+
+<ParamField path={"azure_vault_name"} type={"str | None"}>
+Azure Vault name (required for azure_vault credential_type).
+
+Default: `None` · TypeScript: `azureVaultName`
+</ParamField>
+
+<ParamField path={"azure_vault_username_key"} type={"str | None"}>
+Azure Vault username key (required for azure_vault credential_type).
+
+Default: `None` · TypeScript: `azureVaultUsernameKey`
+</ParamField>
+
+<ParamField path={"azure_vault_password_key"} type={"str | None"}>
+Azure Vault password key (required for azure_vault credential_type).
+
+Default: `None` · TypeScript: `azureVaultPasswordKey`
+</ParamField>
+
+<ParamField path={"azure_vault_totp_secret_key"} type={"str | None"}>
+Azure Vault TOTP secret key (optional for azure_vault credential_type).
+
+Default: `None` · TypeScript: `azureVaultTotpSecretKey`
+</ParamField>
+
+<ParamField path={"prompt"} type={"str | None"}>
+Additional instructions for the login process.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"webhook_url"} type={"str | None"}>
+URL to receive webhook notifications about login progress.
+
+Default: `None` · TypeScript: `webhookUrl`
+</ParamField>
+
+<ParamField path={"totp_identifier"} type={"str | None"}>
+Identifier for TOTP authentication.
+
+Default: `None` · TypeScript: `totpIdentifier`
+</ParamField>
+
+<ParamField path={"totp_url"} type={"str | None"}>
+URL to fetch TOTP codes from.
+
+Default: `None` · TypeScript: `totpUrl`
+</ParamField>
+
+<ParamField path={"extra_http_headers"} type={"dict[str, str] | None"}>
+Additional HTTP headers to include in requests.
+
+Default: `None` · TypeScript: `extraHttpHeaders`
+</ParamField>
+
+<ParamField path={"timeout"} type={"float"}>
+Maximum time in seconds to wait for login completion.
+
+Default: `1800`
+</ParamField>
**Returns** `WorkflowRunResponse` · TypeScript `Promise<WorkflowRunResponse>` — WorkflowRunResponse containing the login workflow execution results.
@@ -321,18 +463,63 @@ page.agent.downloadFiles(prompt: string, options?: { url?: string; downloadSuffi
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `prompt` | `prompt` | `str` | Yes | — | Instructions for navigating to and downloading the file. |
-| `url` | `url` | `str \| None` | No | `None` | URL to navigate to for file download. If not provided, uses the current page URL. |
-| `download_suffix` | `downloadSuffix` | `str \| None` | No | `None` | Complete filename for the downloaded file. Supports \{\{ original_filename \}\} to keep the name the site gave the file. |
-| `download_timeout` | `downloadTimeout` | `float \| None` | No | `None` | Timeout in seconds for the download operation. |
-| `max_steps_per_run` | `maxStepsPerRun` | `int \| None` | No | `None` | Maximum number of steps to execute. |
-| `webhook_url` | `webhookUrl` | `str \| None` | No | `None` | URL to receive webhook notifications about download progress. |
-| `totp_identifier` | `totpIdentifier` | `str \| None` | No | `None` | Identifier for TOTP authentication. |
-| `totp_url` | `totpUrl` | `str \| None` | No | `None` | URL to fetch TOTP codes from. |
-| `extra_http_headers` | `extraHttpHeaders` | `dict[str, str] \| None` | No | `None` | Additional HTTP headers to include in requests. |
-| `timeout` | `timeout` | `float` | No | `1800` | Maximum time in seconds to wait for download completion. |
+<ParamField path={"prompt"} type={"str"} required>
+Instructions for navigating to and downloading the file.
+</ParamField>
+
+<ParamField path={"url"} type={"str | None"}>
+URL to navigate to for file download. If not provided, uses the current page URL.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"download_suffix"} type={"str | None"}>
+Complete filename for the downloaded file. Supports \{\{ original_filename \}\} to keep the name the site gave the file.
+
+Default: `None` · TypeScript: `downloadSuffix`
+</ParamField>
+
+<ParamField path={"download_timeout"} type={"float | None"}>
+Timeout in seconds for the download operation.
+
+Default: `None` · TypeScript: `downloadTimeout`
+</ParamField>
+
+<ParamField path={"max_steps_per_run"} type={"int | None"}>
+Maximum number of steps to execute.
+
+Default: `None` · TypeScript: `maxStepsPerRun`
+</ParamField>
+
+<ParamField path={"webhook_url"} type={"str | None"}>
+URL to receive webhook notifications about download progress.
+
+Default: `None` · TypeScript: `webhookUrl`
+</ParamField>
+
+<ParamField path={"totp_identifier"} type={"str | None"}>
+Identifier for TOTP authentication.
+
+Default: `None` · TypeScript: `totpIdentifier`
+</ParamField>
+
+<ParamField path={"totp_url"} type={"str | None"}>
+URL to fetch TOTP codes from.
+
+Default: `None` · TypeScript: `totpUrl`
+</ParamField>
+
+<ParamField path={"extra_http_headers"} type={"dict[str, str] | None"}>
+Additional HTTP headers to include in requests.
+
+Default: `None` · TypeScript: `extraHttpHeaders`
+</ParamField>
+
+<ParamField path={"timeout"} type={"float"}>
+Maximum time in seconds to wait for download completion.
+
+Default: `1800`
+</ParamField>
**Returns** `WorkflowRunResponse` · TypeScript `Promise<WorkflowRunResponse>` — WorkflowRunResponse containing the file download workflow execution results.
@@ -431,18 +618,65 @@ page.agent.runWorkflow(workflowId: string, options?: { parameters?: Record<strin
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `workflow_id` | `workflowId` | `str` | Yes | — | ID of the workflow to execute. |
-| `parameters` | `parameters` | `dict[str, Any] \| None` | No | `None` | Dictionary of parameters to pass to the workflow. |
-| `template` | `template` | `bool \| None` | No | `None` | Whether this is a workflow template. |
-| `title` | `title` | `str \| None` | No | `None` | Human-readable title for this workflow run. |
-| `webhook_url` | `webhookUrl` | `str \| None` | No | `None` | URL to receive webhook notifications about workflow progress. |
-| `totp_url` | `totpUrl` | `str \| None` | No | `None` | URL to fetch TOTP codes from. |
-| `totp_identifier` | `totpIdentifier` | `str \| None` | No | `None` | Identifier for TOTP authentication. |
-| `max_elapsed_time_minutes` | — | `int \| None` | No | `None` | Timeout this workflow run after the configured elapsed runtime in minutes. |
-| `run_metadata` | — | `dict[str, str] \| None` | No | `None` | String key/value metadata to attach to this workflow run. |
-| `timeout` | `timeout` | `float` | No | `1800` | Maximum time in seconds to wait for workflow completion. |
+<ParamField path={"workflow_id"} type={"str"} required>
+ID of the workflow to execute.
+
+TypeScript: `workflowId`
+</ParamField>
+
+<ParamField path={"parameters"} type={"dict[str, Any] | None"}>
+Dictionary of parameters to pass to the workflow.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"template"} type={"bool | None"}>
+Whether this is a workflow template.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"title"} type={"str | None"}>
+Human-readable title for this workflow run.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"webhook_url"} type={"str | None"}>
+URL to receive webhook notifications about workflow progress.
+
+Default: `None` · TypeScript: `webhookUrl`
+</ParamField>
+
+<ParamField path={"totp_url"} type={"str | None"}>
+URL to fetch TOTP codes from.
+
+Default: `None` · TypeScript: `totpUrl`
+</ParamField>
+
+<ParamField path={"totp_identifier"} type={"str | None"}>
+Identifier for TOTP authentication.
+
+Default: `None` · TypeScript: `totpIdentifier`
+</ParamField>
+
+<ParamField path={"max_elapsed_time_minutes"} type={"int | None"}>
+Timeout this workflow run after the configured elapsed runtime in minutes.
+
+Default: `None` · Python only
+</ParamField>
+
+<ParamField path={"run_metadata"} type={"dict[str, str] | None"}>
+String key/value metadata to attach to this workflow run.
+
+Default: `None` · Python only
+</ParamField>
+
+<ParamField path={"timeout"} type={"float"}>
+Maximum time in seconds to wait for workflow completion.
+
+Default: `1800`
+</ParamField>
**Returns** `WorkflowRunResponse` · TypeScript `Promise<WorkflowRunResponse>` — WorkflowRunResponse containing the workflow execution results.
diff --git a/docs/sdk-reference/browser-automation/browsers.mdx b/docs/sdk-reference/browser-automation/browsers.mdx
index fbae70998..6c4ed71b3 100644
--- a/docs/sdk-reference/browser-automation/browsers.mdx
+++ b/docs/sdk-reference/browser-automation/browsers.mdx
@@ -40,13 +40,35 @@ skyvern.launchCloudBrowser(options?: { timeout?: number; proxyLocation?: ProxyLo
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `timeout` | `timeout` | `int \| None` | No | `None` | Timeout in minutes for the session. Timeout is applied after the session is started. Must be between 5 and 240; values above 240 are rejected with a 400. Defaults to 60. |
-| `proxy_location` | `proxyLocation` | `ProxyLocationInput` | No | `None` | Geographic proxy location to route the browser traffic through. This is only available in Skyvern Cloud. |
-| `extensions` | — | `list[Extensions] \| None` | No | `None` | Browser extensions to install in the session. |
-| `browser_profile_id` | — | `str \| None` | No | `None` | Browser profile ID to load into the session. |
-| `browser_type` | — | `PersistentBrowserType \| None` | No | `None` | Browser engine for the session (msedge, chrome, or stealth-chromium). |
+<ParamField path={"timeout"} type={"int | None"}>
+Timeout in minutes for the session. Timeout is applied after the session is started. Must be between 5 and 240; values above 240 are rejected with a 400. Defaults to 60.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"proxy_location"} type={"ProxyLocationInput"}>
+Geographic proxy location to route the browser traffic through. This is only available in Skyvern Cloud.
+
+Default: `None` · TypeScript: `proxyLocation`
+</ParamField>
+
+<ParamField path={"extensions"} type={"list[Extensions] | None"}>
+Browser extensions to install in the session.
+
+Default: `None` · Python only
+</ParamField>
+
+<ParamField path={"browser_profile_id"} type={"str | None"}>
+Browser profile ID to load into the session.
+
+Default: `None` · Python only
+</ParamField>
+
+<ParamField path={"browser_type"} type={"PersistentBrowserType | None"}>
+Browser engine for the session (msedge, chrome, or stealth-chromium).
+
+Default: `None` · Python only
+</ParamField>
**Returns** `SkyvernBrowser` · TypeScript `Promise<SkyvernBrowser>` — A browser instance connected to the new cloud session.
@@ -103,10 +125,17 @@ skyvern.useCloudBrowser(options?: { timeout?: number; proxyLocation?: ProxyLocat
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `timeout` | `timeout` | `int \| None` | No | `None` | Timeout in minutes for the session. Timeout is applied after the session is started. Must be between 5 and 240; values above 240 are rejected with a 400. Defaults to 60. Only used when creating a new session. |
-| `proxy_location` | `proxyLocation` | `ProxyLocationInput` | No | `None` | Geographic proxy location to route the browser traffic through. This is only available in Skyvern Cloud. Only used when creating a new session. |
+<ParamField path={"timeout"} type={"int | None"}>
+Timeout in minutes for the session. Timeout is applied after the session is started. Must be between 5 and 240; values above 240 are rejected with a 400. Defaults to 60. Only used when creating a new session.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"proxy_location"} type={"ProxyLocationInput"}>
+Geographic proxy location to route the browser traffic through. This is only available in Skyvern Cloud. Only used when creating a new session.
+
+Default: `None` · TypeScript: `proxyLocation`
+</ParamField>
**Returns** `SkyvernBrowser` · TypeScript `Promise<SkyvernBrowser>` — A browser instance connected to an existing or new cloud session.
@@ -157,9 +186,11 @@ skyvern.connectToCloudBrowserSession(browserSessionId: string): Promise<SkyvernB
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `browser_session_id` | `browserSessionId` | `str` | Yes | — | The ID of the cloud browser session to connect to. |
+<ParamField path={"browser_session_id"} type={"str"} required>
+The ID of the cloud browser session to connect to.
+
+TypeScript: `browserSessionId`
+</ParamField>
**Returns** `SkyvernBrowser` · TypeScript `Promise<SkyvernBrowser>` — A browser instance connected to the cloud session.
@@ -211,9 +242,11 @@ skyvern.connectToBrowserOverCdp(cdpUrl: string): Promise<SkyvernBrowser>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `cdp_url` | `cdpUrl` | `str` | Yes | — | The CDP WebSocket URL (e.g., "http://localhost:9222"). |
+<ParamField path={"cdp_url"} type={"str"} required>
+The CDP WebSocket URL (e.g., "http://localhost:9222").
+
+TypeScript: `cdpUrl`
+</ParamField>
**Returns** `SkyvernBrowser` · TypeScript `Promise<SkyvernBrowser>` — A browser instance connected to the existing browser.
@@ -269,12 +302,27 @@ await skyvern.launch_local_browser(
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `headless` | — | `bool` | No | `False` | Whether to run the browser in headless mode. Defaults to False. |
-| `port` | — | `int \| None` | No | `None` | The port number for the CDP endpoint. Anonymous launches use an OS-assigned port; explicitly configured launches retain DEFAULT_CDP_PORT. |
-| `args` | — | `list[str] \| None` | No | `None` | Additional command-line arguments to pass to Chromium. Defaults to None. Example: ["--disable-blink-features=AutomationControlled", "--window-size=1920,1080"] |
-| `user_data_dir` | — | `str \| None` | No | `None` | |
+<ParamField path={"headless"} type={"bool"}>
+Whether to run the browser in headless mode. Defaults to False.
+
+Default: `False`
+</ParamField>
+
+<ParamField path={"port"} type={"int | None"}>
+The port number for the CDP endpoint. Anonymous launches use an OS-assigned port; explicitly configured launches retain DEFAULT_CDP_PORT.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"args"} type={"list[str] | None"}>
+Additional command-line arguments to pass to Chromium. Defaults to None. Example: ["--disable-blink-features=AutomationControlled", "--window-size=1920,1080"]
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"user_data_dir"} type={"str | None"}>
+Default: `None`
+</ParamField>
**Returns** `SkyvernBrowser` — A browser instance with Skyvern capabilities.
@@ -464,9 +512,8 @@ await browser.get_page_for(page: Page) -> SkyvernBrowserPage
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `page` | — | `Page` | Yes | — | |
+<ParamField path={"page"} type={"Page"} required>
+</ParamField>
**Returns** `SkyvernBrowserPage`
@@ -513,9 +560,11 @@ browser.close(): Promise<void>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `**kwargs` | — | `Any` | No | — | Arguments passed to the underlying BrowserContext.close() method. |
+<ParamField path={"**kwargs"} type={"Any"}>
+Arguments passed to the underlying BrowserContext.close() method.
+
+Sent only when you pass it · Python only
+</ParamField>
**Returns** `None` · TypeScript `Promise<void>`
diff --git a/docs/sdk-reference/browser-automation/forms.mdx b/docs/sdk-reference/browser-automation/forms.mdx
index b8249c83f..9070e3d66 100644
--- a/docs/sdk-reference/browser-automation/forms.mdx
+++ b/docs/sdk-reference/browser-automation/forms.mdx
@@ -34,10 +34,15 @@ await page.fill_form(data: dict[str, Any], *, prompt: str = 'Fill out the form')
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `data` | — | `dict[str, Any]` | Yes | — | Dict of data keys/values to fill into the form. |
-| `prompt` | — | `str` | No | `'Fill out the form'` | User instructions for how to fill the form. |
+<ParamField path={"data"} type={"dict[str, Any]"} required>
+Dict of data keys/values to fill into the form.
+</ParamField>
+
+<ParamField path={"prompt"} type={"str"}>
+User instructions for how to fill the form.
+
+Default: `'Fill out the form'`
+</ParamField>
**Returns** `None`
@@ -93,14 +98,37 @@ await page.fill_multipage_form(
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `data` | — | `dict[str, Any]` | Yes | — | Dict of data keys/values to fill into the form. |
-| `prompt` | — | `str` | No | `'Fill out the form'` | User instructions for how to fill the form. |
-| `next_button` | — | `str` | No | `'button:has-text("Save and Continue"), button:has-text("Next"), button:has-text("Continue")'` | CSS selector(s) for the next/continue button. |
-| `max_pages` | — | `int` | No | `10` | Safety limit on number of pages to fill. |
-| `timeout_seconds` | — | `float` | No | `300` | Wall-clock timeout for the entire multi-page fill (default 5 min). |
-| `debug_dir` | — | `str \| None` | No | `None` | |
+<ParamField path={"data"} type={"dict[str, Any]"} required>
+Dict of data keys/values to fill into the form.
+</ParamField>
+
+<ParamField path={"prompt"} type={"str"}>
+User instructions for how to fill the form.
+
+Default: `'Fill out the form'`
+</ParamField>
+
+<ParamField path={"next_button"} type={"str"}>
+CSS selector(s) for the next/continue button.
+
+Default: `'button:has-text("Save and Continue"), button:has-text("Next"), button:has-text("Continue")'`
+</ParamField>
+
+<ParamField path={"max_pages"} type={"int"}>
+Safety limit on number of pages to fill.
+
+Default: `10`
+</ParamField>
+
+<ParamField path={"timeout_seconds"} type={"float"}>
+Wall-clock timeout for the entire multi-page fill (default 5 min).
+
+Default: `300`
+</ParamField>
+
+<ParamField path={"debug_dir"} type={"str | None"}>
+Default: `None`
+</ParamField>
**Returns** `int`
@@ -199,13 +227,19 @@ await page.dynamic_field_map(
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `form_fields` | — | `list[dict[str, Any]]` | Yes | — | Output of `extract_form_fields`. |
-| `data` | — | `dict[str, Any]` | Yes | — | Flat dict of data keys/values to map to form fields. |
-| `prompt` | — | `str \| None` | No | `None` | |
+<ParamField path={"form_fields"} type={"list[dict[str, Any]]"} required>
+Output of `extract_form_fields`.
+</ParamField>
+
+<ParamField path={"data"} type={"dict[str, Any]"} required>
+Flat dict of data keys/values to map to form fields.
+</ParamField>
-**Returns** `dict[int, str \| list \| bool \| None]` — Mapping of 0-based field index -&gt; value to fill (or None to skip).
+<ParamField path={"prompt"} type={"str | None"}>
+Default: `None`
+</ParamField>
+
+**Returns** `dict[int, str | list | bool | None]` — Mapping of 0-based field index -&gt; value to fill (or None to skip).
**Example**
@@ -257,11 +291,19 @@ await page.fill_from_mapping(
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `form_fields` | — | `list[dict[str, Any]]` | Yes | — | Output of `extract_form_fields`. |
-| `mapping` | — | `dict[int, str \| list \| bool \| None]` | Yes | — | Output of `dynamic_field_map` (index -&gt; value). |
-| `data` | — | `dict[str, Any] \| None` | No | `None` | Original data dict for post-fill file upload matching. |
+<ParamField path={"form_fields"} type={"list[dict[str, Any]]"} required>
+Output of `extract_form_fields`.
+</ParamField>
+
+<ParamField path={"mapping"} type={"dict[int, str | list | bool | None]"} required>
+Output of `dynamic_field_map` (index -&gt; value).
+</ParamField>
+
+<ParamField path={"data"} type={"dict[str, Any] | None"}>
+Original data dict for post-fill file upload matching.
+
+Default: `None`
+</ParamField>
**Returns** `None`
@@ -317,11 +359,17 @@ await page.validate_mapping(
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `form_fields` | — | `list[dict[str, Any]]` | Yes | — | Output of `extract_form_fields`. |
-| `mapping` | — | `dict[int, str \| list \| bool \| None]` | Yes | — | Output of `dynamic_field_map`. |
-| `prompt` | — | `str \| None` | Yes | — | The user's instructions/prompt for this automation. |
+<ParamField path={"form_fields"} type={"list[dict[str, Any]]"} required>
+Output of `extract_form_fields`.
+</ParamField>
+
+<ParamField path={"mapping"} type={"dict[int, str | list | bool | None]"} required>
+Output of `dynamic_field_map`.
+</ParamField>
+
+<ParamField path={"prompt"} type={"str | None"} required>
+The user's instructions/prompt for this automation.
+</ParamField>
**Returns** `bool` — True to complete, False to terminate.
@@ -390,14 +438,41 @@ await page.fill_autocomplete(
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `selector` | — | `str \| None` | No | `None` | CSS selector for the input field. |
-| `value` | — | `str \| None` | No | `None` | The text to type (e.g. "San Francisco, CA"). |
-| `prompt` | — | `str \| None` | No | `None` | Natural language description for AI fallback. |
-| `ai` | — | `str \| None` | No | `'fallback'` | AI behavior mode (same as fill). Defaults to "fallback". |
-| `option_selector` | — | `str \| None` | No | `None` | CSS selector for the dropdown options. If not provided, tries common patterns: `[role="option"]`, `.pac-item`, `li[role="option"]`, `[data-option-id]`. |
-| `wait_seconds` | — | `float` | No | `1.5` | How long to wait for dropdown options to appear after typing. Defaults to 1.5 seconds. |
+<ParamField path={"selector"} type={"str | None"}>
+CSS selector for the input field.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"value"} type={"str | None"}>
+The text to type (e.g. "San Francisco, CA").
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"prompt"} type={"str | None"}>
+Natural language description for AI fallback.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"ai"} type={"str | None"}>
+AI behavior mode (same as fill). Defaults to "fallback".
+
+Default: `'fallback'`
+</ParamField>
+
+<ParamField path={"option_selector"} type={"str | None"}>
+CSS selector for the dropdown options. If not provided, tries common patterns: `[role="option"]`, `.pac-item`, `li[role="option"]`, `[data-option-id]`.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"wait_seconds"} type={"float"}>
+How long to wait for dropdown options to appear after typing. Defaults to 1.5 seconds.
+
+Default: `1.5`
+</ParamField>
**Returns** `str` — The value that was selected from the dropdown, or the typed value if no dropdown appeared.
diff --git a/docs/sdk-reference/browser-automation/frames.mdx b/docs/sdk-reference/browser-automation/frames.mdx
index 1151009e4..24a69dc23 100644
--- a/docs/sdk-reference/browser-automation/frames.mdx
+++ b/docs/sdk-reference/browser-automation/frames.mdx
@@ -32,11 +32,23 @@ await page.frame_switch(
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `selector` | — | `str \| None` | No | `None` | CSS selector for the iframe element (uses content_frame()). |
-| `name` | — | `str \| None` | No | `None` | Frame name attribute. |
-| `index` | — | `int \| None` | No | `None` | Frame index in page.frames list (0 = main frame). |
+<ParamField path={"selector"} type={"str | None"}>
+CSS selector for the iframe element (uses content_frame()).
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"name"} type={"str | None"}>
+Frame name attribute.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"index"} type={"int | None"}>
+Frame index in page.frames list (0 = main frame).
+
+Default: `None`
+</ParamField>
**Returns** `dict[str, Any]` — Dict with frame name, url, and the parameter used to switch.
diff --git a/docs/sdk-reference/browser-automation/page.mdx b/docs/sdk-reference/browser-automation/page.mdx
index 575ce204e..75ab65fe2 100644
--- a/docs/sdk-reference/browser-automation/page.mdx
+++ b/docs/sdk-reference/browser-automation/page.mdx
@@ -36,11 +36,17 @@ page.act(prompt: string): Promise<void>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `prompt` | `prompt` | `str` | Yes | — | Natural language description of the action to perform. |
-| `skip_refresh` | — | `bool` | No | `False` | |
-| `use_economy_tree` | — | `bool` | No | `False` | |
+<ParamField path={"prompt"} type={"str"} required>
+Natural language description of the action to perform.
+</ParamField>
+
+<ParamField path={"skip_refresh"} type={"bool"}>
+Default: `False` · Python only
+</ParamField>
+
+<ParamField path={"use_economy_tree"} type={"bool"}>
+Default: `False` · Python only
+</ParamField>
**Returns** `None` · TypeScript `Promise<void>`
@@ -100,15 +106,33 @@ page.extract(options: { prompt: string; schema?: Record<string, unknown> | unkno
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `prompt` | `prompt` | `str` | Yes | — | Natural language description of what data to extract. |
-| `schema` | `schema` | `dict[str, Any] \| list \| str \| None` | No | `None` | JSON Schema defining the structure of data to extract. |
-| `error_code_mapping` | `errorCodeMapping` | `dict[str, str] \| None` | No | `None` | Mapping of error codes to custom error messages. |
-| `intention` | `intention` | `str \| None` | No | `None` | Additional context about the extraction intent. |
-| — | `data` | `string \| Record<string, unknown>` | No | — | TypeScript only. |
+<ParamField path={"prompt"} type={"str"} required>
+Natural language description of what data to extract.
+</ParamField>
+
+<ParamField path={"schema"} type={"dict[str, Any] | list | str | None"}>
+JSON Schema defining the structure of data to extract.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"error_code_mapping"} type={"dict[str, str] | None"}>
+Mapping of error codes to custom error messages.
+
+Default: `None` · TypeScript: `errorCodeMapping`
+</ParamField>
-**Returns** `dict[str, Any] \| list \| str \| None` · TypeScript `Promise<Record<string, unknown> \| unknown[] \| string \| null>` — Extracted data matching the provided schema, or None if extraction fails.
+<ParamField path={"intention"} type={"str | None"}>
+Additional context about the extraction intent.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"data"} type={"string | Record<string, unknown>"}>
+TypeScript only
+</ParamField>
+
+**Returns** `dict[str, Any] | list | str | None` · TypeScript `Promise<Record<string, unknown> | unknown[] | string | null>` — Extracted data matching the provided schema, or None if extraction fails.
**Example**
@@ -165,10 +189,15 @@ page.validate(prompt: string, model?: Record<string, unknown> | string): Promise
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `prompt` | `prompt` | `str` | Yes | — | Validation criteria or condition to check |
-| `model` | `model` | `dict[str, Any] \| str \| None` | No | `None` | Optional model configuration. Can be either: - A dict with model configuration (e.g., \{"model_name": "gemini-2.5-flash-lite", "max_tokens": 2048\}) - A string with just the model name (e.g., "gpt-4") |
+<ParamField path={"prompt"} type={"str"} required>
+Validation criteria or condition to check
+</ParamField>
+
+<ParamField path={"model"} type={"dict[str, Any] | str | None"}>
+Optional model configuration. Can be either: - A dict with model configuration (e.g., \{"model_name": "gemini-2.5-flash-lite", "max_tokens": 2048\}) - A string with just the model name (e.g., "gpt-4")
+
+Default: `None`
+</ParamField>
**Returns** `bool` · TypeScript `Promise<boolean>` — True if validation passes, False otherwise
@@ -232,13 +261,23 @@ page.prompt(prompt: string, schema?: Record<string, unknown>, model?: Record<str
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `prompt` | `prompt` | `str` | Yes | — | The prompt to send to the LLM |
-| `schema` | `schema` | `dict[str, Any] \| None` | No | `None` | Optional JSON schema to structure the response. If provided, the LLM response will be validated against this schema. |
-| `model` | `model` | `dict[str, Any] \| str \| None` | No | `None` | Optional model configuration. Can be either: - A dict with model configuration (e.g., \{"model_name": "gemini-2.5-flash-lite", "max_tokens": 2048\}) - A string with just the model name (e.g., "gemini-2.5-flash-lite") |
+<ParamField path={"prompt"} type={"str"} required>
+The prompt to send to the LLM
+</ParamField>
-**Returns** `dict[str, Any] \| list \| str \| None` · TypeScript `Promise<Record<string, unknown> \| unknown[] \| string \| null>` — LLM response structured according to the schema if provided, or unstructured response otherwise.
+<ParamField path={"schema"} type={"dict[str, Any] | None"}>
+Optional JSON schema to structure the response. If provided, the LLM response will be validated against this schema.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"model"} type={"dict[str, Any] | str | None"}>
+Optional model configuration. Can be either: - A dict with model configuration (e.g., \{"model_name": "gemini-2.5-flash-lite", "max_tokens": 2048\}) - A string with just the model name (e.g., "gemini-2.5-flash-lite")
+
+Default: `None`
+</ParamField>
+
+**Returns** `dict[str, Any] | list | str | None` · TypeScript `Promise<Record<string, unknown> | unknown[] | string | null>` — LLM response structured according to the schema if provided, or unstructured response otherwise.
**Example**
@@ -277,67 +316,6 @@ await browser.close();
---
-### page.classify
-
-Classify the current page state against named options using a tiered cascade.
-
-This method uses a three-tier approach to minimize cost:
-1. URL pattern matching against current URL (FREE)
-2. Text substring check in page content (FREE)
-3. LLM-based classification as last resort (~$0.001)
-
-<Note>Python only: the TypeScript SDK has no equivalent.</Note>
-
-<CodeGroup>
-```python Python
-await page.classify(
- options: dict[str, str],
- url_patterns: dict[str, str] | None = None,
- text_patterns: dict[str, str | list[str]] | None = None,
-) -> str
-```
-</CodeGroup>
-
-**Parameters**
-
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `options` | — | `dict[str, str]` | Yes | — | Dict mapping option keys to descriptions. e.g. \{"eligible": "The page shows eligibility confirmation", "not_eligible": "The page shows a rejection message"\} |
-| `url_patterns` | — | `dict[str, str] \| None` | No | `None` | Optional dict mapping option keys to regex patterns to match against the current URL. |
-| `text_patterns` | — | `dict[str, str \| list[str]] \| None` | No | `None` | Optional dict mapping option keys to text substrings to search for in the page's extracted text. |
-
-**Returns** `str` — The matching option key, or "UNKNOWN" if no option matches.
-
-**Example**
-
-<CodeGroup>
-```python Python
-import asyncio
-
-from skyvern import Skyvern
-
-
-async def main() -> None:
- skyvern = Skyvern(api_key="YOUR_API_KEY")
- browser = await skyvern.launch_cloud_browser()
- page = await browser.get_working_page()
- await page.goto("https://example.com")
- result = await page.classify(
- options={
- "logged_in": "The page shows the account dashboard",
- "logged_out": "The page shows a sign-in form",
- },
- )
- print(result)
- await browser.close()
-
-
-asyncio.run(main())
-```
-</CodeGroup>
-
----
-
### page.locator
Get a Playwright locator using a CSS selector, AI-powered prompt, or both.
@@ -367,69 +345,31 @@ page.locator(
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `selector` | — | `str \| None` | No | `None` | CSS selector for the target element. |
-| `prompt` | — | `str \| None` | No | `None` | Natural language description of which element to locate. |
-| `ai` | — | `str \| None` | No | `'fallback'` | AI behavior mode. Defaults to "fallback" which tries selector first, then AI. |
-| `**kwargs` | — | `Any` | No | — | All Playwright locator parameters (has_text, has, etc.) |
-
-**Returns** `Locator` — A Playwright Locator object (or AILocator proxy that acts like one).
-
-**Example**
-
-<CodeGroup>
-```python Python
-import asyncio
-
-from skyvern import Skyvern
+<ParamField path={"selector"} type={"str | None"}>
+CSS selector for the target element.
+Default: `None`
+</ParamField>
-async def main() -> None:
- skyvern = Skyvern(api_key="YOUR_API_KEY")
- browser = await skyvern.launch_cloud_browser()
- page = await browser.get_working_page()
- await page.goto("https://example.com")
- result = page.locator(prompt="the search box")
- print(result)
- await browser.close()
+<ParamField path={"prompt"} type={"str | None"}>
+Natural language description of which element to locate.
+Default: `None`
+</ParamField>
-asyncio.run(main())
-```
-</CodeGroup>
-
----
+<ParamField path={"ai"} type={"str | None"}>
+AI behavior mode. Defaults to "fallback" which tries selector first, then AI.
-### page.element_fallback
+Default: `'fallback'`
+</ParamField>
-Activate the AI agent from the CURRENT page position to achieve a goal.
+<ParamField path={"**kwargs"} type={"Any"}>
+All Playwright locator parameters (has_text, has, etc.)
-Instead of re-running the entire block when cached code encounters an unknown
-state, this method activates the AI agent from the current page position.
-Much cheaper than a full block re-execution.
-
-<Note>Python only: the TypeScript SDK has no equivalent.</Note>
+Sent only when you pass it
+</ParamField>
-<CodeGroup>
-```python Python
-await page.element_fallback(
- navigation_goal: str,
- max_steps: int = 5,
- validate_first: bool = False,
-) -> None
-```
-</CodeGroup>
-
-**Parameters**
-
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `navigation_goal` | — | `str` | Yes | — | The goal for the AI agent to achieve from the current page. |
-| `max_steps` | — | `int` | No | `5` | Maximum number of agent steps before giving up. Defaults to 5. |
-| `validate_first` | — | `bool` | No | `False` | When True, run an AI validation before the first action to short-circuit if the page already satisfies the goal. Defaults to False because the documented call site (else branch of `classify`) cannot be on the success state — pass True for defensive calls that may invoke this on a possibly-complete page. |
-
-**Returns** `None`
+**Returns** `Locator` — A Playwright Locator object (or AILocator proxy that acts like one).
**Example**
@@ -445,7 +385,8 @@ async def main() -> None:
browser = await skyvern.launch_cloud_browser()
page = await browser.get_working_page()
await page.goto("https://example.com")
- await page.element_fallback(navigation_goal="Open the most recent invoice")
+ result = page.locator(prompt="the search box")
+ print(result)
await browser.close()
@@ -486,17 +427,49 @@ page.click(selector: string, options: { prompt: string; } & Partial<Parameters<P
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `selector` | `selector` | `str \| None` | No | `None` | CSS selector for the target element. |
-| `prompt` | `prompt` | `str \| None` | No | `None` | Natural language description of which element to click. |
-| `ai` | — | `str \| None` | No | `'fallback'` | AI behavior mode. Defaults to "fallback" which tries selector first, then AI. |
-| `mode` | — | `str \| None` | No | `None` | When `"direct"`, perform a raw Playwright click with no AI fallback or element preparation. The action is still recorded in the DB so it appears in the timeline. |
-| `desired_state` | — | `bool \| None` | No | `None` | Level-triggered toggle intent recorded with the action. When set, a selector-first click is suppressed if the control already holds that state, so a replay never toggles an already-satisfied control back off. Ignored by `mode="direct"`. |
-| `**kwargs` | — | `Any` | No | — | All Playwright click parameters (timeout, force, modifiers, etc.) |
-| — | `options` | `Parameters<Page["click"]>[1]` | No | — | Playwright options for this call. |
+<ParamField path={"selector"} type={"str | None"}>
+CSS selector for the target element.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"prompt"} type={"str | None"}>
+Natural language description of which element to click.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"ai"} type={"str | None"}>
+AI behavior mode. Defaults to "fallback" which tries selector first, then AI.
+
+Default: `'fallback'` · Python only
+</ParamField>
+
+<ParamField path={"mode"} type={"str | None"}>
+When `"direct"`, perform a raw Playwright click with no AI fallback or element preparation. The action is still recorded in the DB so it appears in the timeline.
+
+Default: `None` · Python only
+</ParamField>
+
+<ParamField path={"desired_state"} type={"bool | None"}>
+Level-triggered toggle intent recorded with the action. When set, a selector-first click is suppressed if the control already holds that state, so a replay never toggles an already-satisfied control back off. Ignored by `mode="direct"`.
+
+Default: `None` · Python only
+</ParamField>
+
+<ParamField path={"**kwargs"} type={"Any"}>
+All Playwright click parameters (timeout, force, modifiers, etc.)
+
+Sent only when you pass it · Python only
+</ParamField>
+
+<ParamField path={"options"} type={"Parameters<Page[\"click\"]>[1]"}>
+Playwright options for this call.
+
+TypeScript only
+</ParamField>
-**Returns** `str \| None` · TypeScript `Promise<void>` — The selector string that was successfully used to click the element, or None.
+**Returns** `str | None` · TypeScript `Promise<void>` — The selector string that was successfully used to click the element, or None.
**Example**
@@ -566,16 +539,53 @@ page.fill(selector: string, value: string, options: { prompt: string; } & Partia
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `selector` | `selector` | `str \| None` | No | `None` | CSS selector for the target input element. |
-| `value` | `value` | `str \| None` | No | `None` | The text value to input into the field. |
-| `prompt` | `prompt` | `str \| None` | No | `None` | Natural language description of which field to fill and what value. |
-| `ai` | — | `str \| None` | No | `'fallback'` | AI behavior mode. Defaults to "fallback" which tries selector first, then AI. |
-| `mode` | — | `str \| None` | No | `None` | When `"direct"`, perform a raw Playwright fill with no AI fallback or element preparation. The action is still recorded in the DB so it appears in the timeline. |
-| `totp_identifier` | — | `str \| None` | No | `None` | TOTP identifier for time-based one-time password fields. |
-| `totp_url` | — | `str \| None` | No | `None` | URL to fetch TOTP codes from for authentication. |
-| — | `options` | `Parameters<Page["fill"]>[2]` | No | — | Playwright options for this call. |
+<ParamField path={"selector"} type={"str | None"}>
+CSS selector for the target input element.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"value"} type={"str | None"}>
+The text value to input into the field.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"prompt"} type={"str | None"}>
+Natural language description of which field to fill and what value.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"ai"} type={"str | None"}>
+AI behavior mode. Defaults to "fallback" which tries selector first, then AI.
+
+Default: `'fallback'` · Python only
+</ParamField>
+
+<ParamField path={"mode"} type={"str | None"}>
+When `"direct"`, perform a raw Playwright fill with no AI fallback or element preparation. The action is still recorded in the DB so it appears in the timeline.
+
+Default: `None` · Python only
+</ParamField>
+
+<ParamField path={"totp_identifier"} type={"str | None"}>
+TOTP identifier for time-based one-time password fields.
+
+Default: `None` · Python only
+</ParamField>
+
+<ParamField path={"totp_url"} type={"str | None"}>
+URL to fetch TOTP codes from for authentication.
+
+Default: `None` · Python only
+</ParamField>
+
+<ParamField path={"options"} type={"Parameters<Page[\"fill\"]>[2]"}>
+Playwright options for this call.
+
+TypeScript only
+</ParamField>
**Returns** `str` · TypeScript `Promise<void>` — The value that was successfully filled into the field.
@@ -644,16 +654,41 @@ page.selectOption(selector: string, values: string | string[], options: { prompt
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `selector` | `selector` | `str \| None` | No | `None` | CSS selector for the target select/dropdown element. |
-| `value` | `value` | `str \| None` | No | `None` | The option value to select. |
-| `prompt` | `prompt` | `str \| None` | No | `None` | Natural language description of which option to select. |
-| `ai` | — | `str \| None` | No | `'fallback'` | AI behavior mode. Defaults to "fallback" which tries selector first, then AI. |
-| — | `values` | `string \| string[]` | No | — | TypeScript only. |
-| — | `options` | `Parameters<Page["selectOption"]>[2]` | No | — | Playwright options for this call. |
+<ParamField path={"selector"} type={"str | None"}>
+CSS selector for the target select/dropdown element.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"value"} type={"str | None"}>
+The option value to select.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"prompt"} type={"str | None"}>
+Natural language description of which option to select.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"ai"} type={"str | None"}>
+AI behavior mode. Defaults to "fallback" which tries selector first, then AI.
-**Returns** `str \| None` · TypeScript `Promise<void>` — The value that was successfully selected.
+Default: `'fallback'` · Python only
+</ParamField>
+
+<ParamField path={"values"} type={"string | string[]"}>
+TypeScript only
+</ParamField>
+
+<ParamField path={"options"} type={"Parameters<Page[\"selectOption\"]>[2]"}>
+Playwright options for this call.
+
+TypeScript only
+</ParamField>
+
+**Returns** `str | None` · TypeScript `Promise<void>` — The value that was successfully selected.
**Example**
@@ -716,15 +751,47 @@ await page.type(
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `selector` | — | `str \| None` | No | `None` | CSS selector for the input. |
-| `value` | — | `str \| None` | No | `None` | The text to enter. |
-| `ai` | — | `str \| None` | No | `'fallback'` | AI behavior mode. Defaults to "fallback", which tries the selector first, then AI. |
-| `prompt` | — | `str \| None` | No | `None` | Natural language description of which input to type into. |
-| `totp_identifier` | — | `str \| None` | No | `None` | Identifier of the 2FA code to type, when `value` is a TOTP placeholder. |
-| `totp_url` | — | `str \| None` | No | `None` | URL Skyvern calls to fetch the 2FA code, when `value` is a TOTP placeholder. |
-| `**kwargs` | — | `Any` | No | — | Playwright options such as `timeout`. |
+<ParamField path={"selector"} type={"str | None"}>
+CSS selector for the input.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"value"} type={"str | None"}>
+The text to enter.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"ai"} type={"str | None"}>
+AI behavior mode. Defaults to "fallback", which tries the selector first, then AI.
+
+Default: `'fallback'`
+</ParamField>
+
+<ParamField path={"prompt"} type={"str | None"}>
+Natural language description of which input to type into.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"totp_identifier"} type={"str | None"}>
+Identifier of the 2FA code to type, when `value` is a TOTP placeholder.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"totp_url"} type={"str | None"}>
+URL Skyvern calls to fetch the 2FA code, when `value` is a TOTP placeholder.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"**kwargs"} type={"Any"}>
+Playwright options such as `timeout`.
+
+Sent only when you pass it
+</ParamField>
**Returns** `str` — The value that was entered.
@@ -773,12 +840,27 @@ await page.hover(
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `selector` | — | `str` | Yes | — | CSS selector for the element. |
-| `timeout` | — | `float` | No | `5000` | Maximum time to wait for the element, in milliseconds. |
-| `hold_seconds` | — | `float` | No | `0.0` | How long to keep the mouse over the element, in seconds. |
-| `intention` | — | `str \| None` | No | `None` | Description of why you are hovering, recorded with the action. |
+<ParamField path={"selector"} type={"str"} required>
+CSS selector for the element.
+</ParamField>
+
+<ParamField path={"timeout"} type={"float"}>
+Maximum time to wait for the element, in milliseconds.
+
+Default: `5000`
+</ParamField>
+
+<ParamField path={"hold_seconds"} type={"float"}>
+How long to keep the mouse over the element, in seconds.
+
+Default: `0.0`
+</ParamField>
+
+<ParamField path={"intention"} type={"str | None"}>
+Description of why you are hovering, recorded with the action.
+
+Default: `None`
+</ParamField>
**Returns** `str` — The selector that was hovered.
@@ -827,12 +909,29 @@ await page.upload_file(
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `selector` | — | `str \| None` | No | `None` | CSS selector for the file input. |
-| `files` | — | `str \| None` | No | `None` | URL of the file to upload. One file per call. |
-| `prompt` | — | `str \| None` | No | `None` | Natural language description of which file input to use. |
-| `ai` | — | `str \| None` | No | `'fallback'` | AI behavior mode. With the default "fallback", a selector-only call uploads through the selector. When a prompt is passed, the selector is tried first and AI then always runs the upload, using the selector only if it worked. |
+<ParamField path={"selector"} type={"str | None"}>
+CSS selector for the file input.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"files"} type={"str | None"}>
+URL of the file to upload. One file per call.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"prompt"} type={"str | None"}>
+Natural language description of which file input to use.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"ai"} type={"str | None"}>
+AI behavior mode. With the default "fallback", a selector-only call uploads through the selector. When a prompt is passed, the selector is tried first and AI then always runs the upload, using the selector only if it worked.
+
+Default: `'fallback'`
+</ParamField>
**Returns** `str` — The file URL that was uploaded.
@@ -878,11 +977,21 @@ await page.keypress(keys: list[str], hold: bool = False, duration: float = 0) ->
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `keys` | — | `list[str]` | Yes | — | Keys to press, using Playwright key names. |
-| `hold` | — | `bool` | No | `False` | Hold the keys down for `duration` seconds instead of tapping them. |
-| `duration` | — | `float` | No | `0` | How long to hold the keys, in seconds, when `hold` is true. |
+<ParamField path={"keys"} type={"list[str]"} required>
+Keys to press, using Playwright key names.
+</ParamField>
+
+<ParamField path={"hold"} type={"bool"}>
+Hold the keys down for `duration` seconds instead of tapping them.
+
+Default: `False`
+</ParamField>
+
+<ParamField path={"duration"} type={"float"}>
+How long to hold the keys, in seconds, when `hold` is true.
+
+Default: `0`
+</ParamField>
**Returns** `None`
@@ -924,10 +1033,13 @@ await page.scroll(scroll_x: int, scroll_y: int) -> None
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `scroll_x` | — | `int` | Yes | — | Pixels to scroll horizontally (negative scrolls left). |
-| `scroll_y` | — | `int` | Yes | — | Pixels to scroll vertically (negative scrolls up). |
+<ParamField path={"scroll_x"} type={"int"} required>
+Pixels to scroll horizontally (negative scrolls left).
+</ParamField>
+
+<ParamField path={"scroll_y"} type={"int"} required>
+Pixels to scroll vertically (negative scrolls up).
+</ParamField>
**Returns** `None`
@@ -969,11 +1081,17 @@ await page.drag(start_x: int, start_y: int, path: list[tuple[int, int]]) -> None
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `start_x` | — | `int` | Yes | — | Horizontal start position in pixels. |
-| `start_y` | — | `int` | Yes | — | Vertical start position in pixels. |
-| `path` | — | `list[tuple[int, int]]` | Yes | — | Points `(x, y)` to drag through, ending where the mouse is released. |
+<ParamField path={"start_x"} type={"int"} required>
+Horizontal start position in pixels.
+</ParamField>
+
+<ParamField path={"start_y"} type={"int"} required>
+Vertical start position in pixels.
+</ParamField>
+
+<ParamField path={"path"} type={"list[tuple[int, int]]"} required>
+Points `(x, y)` to drag through, ending where the mouse is released.
+</ParamField>
**Returns** `None`
@@ -1015,10 +1133,13 @@ await page.move(x: int, y: int) -> None
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `x` | — | `int` | Yes | — | Horizontal position in pixels from the left of the viewport. |
-| `y` | — | `int` | Yes | — | Vertical position in pixels from the top of the viewport. |
+<ParamField path={"x"} type={"int"} required>
+Horizontal position in pixels from the left of the viewport.
+</ParamField>
+
+<ParamField path={"y"} type={"int"} required>
+Vertical position in pixels from the top of the viewport.
+</ParamField>
**Returns** `None`
@@ -1060,9 +1181,11 @@ await page.wait(seconds: float | None = None) -> None
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `seconds` | — | `float \| None` | No | `None` | How long to wait, in seconds. |
+<ParamField path={"seconds"} type={"float | None"}>
+How long to wait, in seconds.
+
+Default: `None`
+</ParamField>
**Returns** `None`
@@ -1107,10 +1230,17 @@ await page.download_file(
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `file_name` | — | `str \| None` | No | `None` | The original file name (for logging/reference). Defaults to UUID if empty. |
-| `download_url` | — | `str \| None` | No | `None` | The URL to download the file from. |
+<ParamField path={"file_name"} type={"str | None"}>
+The original file name (for logging/reference). Defaults to UUID if empty.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"download_url"} type={"str | None"}>
+The URL to download the file from.
+
+Default: `None`
+</ParamField>
**Returns** `str` — The local file path where the file was saved.
diff --git a/docs/sdk-reference/browser-profiles.mdx b/docs/sdk-reference/browser-profiles.mdx
index bbb18f10a..c0c3bc0df 100644
--- a/docs/sdk-reference/browser-profiles.mdx
+++ b/docs/sdk-reference/browser-profiles.mdx
@@ -39,14 +39,39 @@ skyvern.createBrowserProfile(request: CreateBrowserProfileRequest): Promise<Brow
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `name` | `name` | `str` | Yes | — | Name for the browser profile |
-| `description` | `description` | `str \| None` | No | — | Optional profile description |
-| `browser_session_id` | `browser_session_id` | `str \| None` | No | — | Persistent browser session to convert into a profile. Omit for a blank profile. |
-| `workflow_run_id` | `workflow_run_id` | `str \| None` | No | — | Workflow run whose persisted session should be captured. Omit for a blank profile. |
-| `proxy_location` | `proxy_location` | `CreateBrowserProfileRequestProxyLocation \| None` | No | — | Optional proxy location for this profile's pinned proxy identity. |
-| `proxy_session_id` | `proxy_session_id` | `str \| None` | No | — | Explicit sticky-session id for this profile's pinned proxy identity. |
+<ParamField path={"name"} type={"str"} required>
+Name for the browser profile
+</ParamField>
+
+<ParamField path={"description"} type={"str | None"}>
+Optional profile description
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"browser_session_id"} type={"str | None"}>
+Persistent browser session to convert into a profile. Omit for a blank profile.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"workflow_run_id"} type={"str | None"}>
+Workflow run whose persisted session should be captured. Omit for a blank profile.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"proxy_location"} type={"CreateBrowserProfileRequestProxyLocation | None"}>
+Optional proxy location for this profile's pinned proxy identity.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"proxy_session_id"} type={"str | None"}>
+Explicit sticky-session id for this profile's pinned proxy identity.
+
+Sent only when you pass it
+</ParamField>
**Returns** `BrowserProfile` · TypeScript `Promise<BrowserProfile>`
@@ -121,9 +146,11 @@ skyvern.getBrowserProfile(profileId: string): Promise<BrowserProfile>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `profile_id` | `profileId` | `str` | Yes | — | The ID of the browser profile. browser_profile_id starts with `bp_` |
+<ParamField path={"profile_id"} type={"str"} required>
+The ID of the browser profile. browser_profile_id starts with `bp_`
+
+TypeScript: `profileId`
+</ParamField>
**Returns** `BrowserProfile` · TypeScript `Promise<BrowserProfile>`
@@ -199,13 +226,31 @@ skyvern.listBrowserProfiles(request?: ListBrowserProfilesRequest): Promise<Brows
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `page` | `page` | `int \| None` | No | `None` | |
-| `page_size` | `page_size` | `int \| None` | No | `None` | |
-| `include_deleted` | `include_deleted` | `bool \| None` | No | `None` | Include deleted browser profiles |
-| `search_key` | `search_key` | `str \| None` | No | `None` | Case-insensitive substring search across: browser profile name and description. A profile is returned if either field matches. |
-| `managed` | `managed` | `bool \| None` | No | `None` | Omit to return all profiles; false returns only user-created profiles; true returns only auto-managed profiles. |
+<ParamField path={"page"} type={"int | None"}>
+Default: `None`
+</ParamField>
+
+<ParamField path={"page_size"} type={"int | None"}>
+Default: `None`
+</ParamField>
+
+<ParamField path={"include_deleted"} type={"bool | None"}>
+Include deleted browser profiles
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"search_key"} type={"str | None"}>
+Case-insensitive substring search across: browser profile name and description. A profile is returned if either field matches.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"managed"} type={"bool | None"}>
+Omit to return all profiles; false returns only user-created profiles; true returns only auto-managed profiles.
+
+Default: `None`
+</ParamField>
**Returns** `list[BrowserProfile]` · TypeScript `Promise<BrowserProfile[]>`
@@ -282,14 +327,41 @@ skyvern.updateBrowserProfile(profileId: string, request?: UpdateBrowserProfileRe
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `profile_id` | `profileId` | `str` | Yes | — | The ID of the browser profile to update. browser_profile_id starts with `bp_` |
-| `name` | `name` | `str \| None` | No | — | New name for the browser profile |
-| `description` | `description` | `str \| None` | No | — | New description for the browser profile |
-| `proxy_location` | `proxy_location` | `UpdateBrowserProfileRequestProxyLocation \| None` | No | — | Optional proxy location for this profile's pinned proxy identity. |
-| `proxy_session_id` | `proxy_session_id` | `str \| None` | No | — | Opaque Skyvern-managed proxy sticky-session id. |
-| `rotate_proxy_session_id` | `rotate_proxy_session_id` | `bool \| None` | No | — | Rotate the Skyvern-managed proxy sticky-session id for this profile. |
+<ParamField path={"profile_id"} type={"str"} required>
+The ID of the browser profile to update. browser_profile_id starts with `bp_`
+
+TypeScript: `profileId`
+</ParamField>
+
+<ParamField path={"name"} type={"str | None"}>
+New name for the browser profile
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"description"} type={"str | None"}>
+New description for the browser profile
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"proxy_location"} type={"UpdateBrowserProfileRequestProxyLocation | None"}>
+Optional proxy location for this profile's pinned proxy identity.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"proxy_session_id"} type={"str | None"}>
+Opaque Skyvern-managed proxy sticky-session id.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"rotate_proxy_session_id"} type={"bool | None"}>
+Rotate the Skyvern-managed proxy sticky-session id for this profile.
+
+Sent only when you pass it
+</ParamField>
**Returns** `BrowserProfile` · TypeScript `Promise<BrowserProfile>`
@@ -358,9 +430,11 @@ skyvern.deleteBrowserProfile(profileId: string): Promise<void>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `profile_id` | `profileId` | `str` | Yes | — | The ID of the browser profile to delete. browser_profile_id starts with `bp_` |
+<ParamField path={"profile_id"} type={"str"} required>
+The ID of the browser profile to delete. browser_profile_id starts with `bp_`
+
+TypeScript: `profileId`
+</ParamField>
**Returns** `None` · TypeScript `Promise<void>`
diff --git a/docs/sdk-reference/browser-sessions.mdx b/docs/sdk-reference/browser-sessions.mdx
index 9470883fb..996714212 100644
--- a/docs/sdk-reference/browser-sessions.mdx
+++ b/docs/sdk-reference/browser-sessions.mdx
@@ -41,16 +41,53 @@ skyvern.createBrowserSession(request?: CreateBrowserSessionRequest): Promise<Bro
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `url` | `url` | `str \| None` | No | — | Optional URL to open when the standalone browser session starts. |
-| `timeout` | `timeout` | `int \| None` | No | — | Timeout in minutes for the session. Timeout is applied after the session is started. Must be between 5 and 240. Defaults to 60. |
-| `proxy_location` | `proxy_location` | `CreateBrowserSessionRequestProxyLocation \| None` | No | — | Geographic Proxy location to route the browser traffic through. This is only available in Skyvern Cloud. |
-| `proxy_session_id` | `proxy_session_id` | `str \| None` | No | — | Opaque Skyvern-managed proxy sticky-session id for pinned Residential ISP sessions. |
-| `extensions` | `extensions` | `Sequence[Extensions] \| None` | No | — | A list of extensions to install in the browser session. |
-| `browser_type` | `browser_type` | `PersistentBrowserType \| None` | No | — | The type of browser to use for the session. |
-| `browser_profile_id` | `browser_profile_id` | `str \| None` | No | — | ID of a browser profile to load into this session (restores cookies, localStorage, etc.). browser_profile_id starts with `bp_`. |
-| `generate_browser_profile` | `generate_browser_profile` | `bool \| None` | No | — | When true, the session's browser profile (cookies, localStorage, etc.) is saved to storage when the session ends so it can be turned into a reusable browser profile. Defaults to false to avoid storing profiles for sessions that never need them. Sessions started with a browser_profile_id always persist their profile regardless of this flag. |
+<ParamField path={"url"} type={"str | None"}>
+Optional URL to open when the standalone browser session starts.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"timeout"} type={"int | None"}>
+Timeout in minutes for the session. Timeout is applied after the session is started. Must be between 5 and 240. Defaults to 60.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"proxy_location"} type={"CreateBrowserSessionRequestProxyLocation | None"}>
+Geographic Proxy location to route the browser traffic through. This is only available in Skyvern Cloud.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"proxy_session_id"} type={"str | None"}>
+Opaque Skyvern-managed proxy sticky-session id for pinned Residential ISP sessions.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"extensions"} type={"Sequence[Extensions] | None"}>
+A list of extensions to install in the browser session.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"browser_type"} type={"PersistentBrowserType | None"}>
+The type of browser to use for the session.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"browser_profile_id"} type={"str | None"}>
+ID of a browser profile to load into this session (restores cookies, localStorage, etc.). browser_profile_id starts with `bp_`.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"generate_browser_profile"} type={"bool | None"}>
+When true, the session's browser profile (cookies, localStorage, etc.) is saved to storage when the session ends so it can be turned into a reusable browser profile. Defaults to false to avoid storing profiles for sessions that never need them. Sessions started with a browser_profile_id always persist their profile regardless of this flag.
+
+Sent only when you pass it
+</ParamField>
**Returns** `BrowserSessionResponse` · TypeScript `Promise<BrowserSessionResponse>`
@@ -127,9 +164,11 @@ skyvern.getBrowserSession(browserSessionId: string): Promise<BrowserSessionRespo
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `browser_session_id` | `browserSessionId` | `str` | Yes | — | The ID of the browser session. browser_session_id starts with `pbs_` |
+<ParamField path={"browser_session_id"} type={"str"} required>
+The ID of the browser session. browser_session_id starts with `pbs_`
+
+TypeScript: `browserSessionId`
+</ParamField>
**Returns** `BrowserSessionResponse` · TypeScript `Promise<BrowserSessionResponse>`
@@ -283,10 +322,15 @@ skyvern.updateBrowserSession(browserSessionId: string, request: UpdateBrowserSes
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `browser_session_id` | `browserSessionId` | `str` | Yes | — | The ID of the browser session. browser_session_id starts with `pbs_` |
-| `generate_browser_profile` | `generate_browser_profile` | `bool` | Yes | — | Enable or disable saving this session's browser profile when it ends. Can be toggled while the session is still alive; the value is read at session teardown. |
+<ParamField path={"browser_session_id"} type={"str"} required>
+The ID of the browser session. browser_session_id starts with `pbs_`
+
+TypeScript: `browserSessionId`
+</ParamField>
+
+<ParamField path={"generate_browser_profile"} type={"bool"} required>
+Enable or disable saving this session's browser profile when it ends. Can be toggled while the session is still alive; the value is read at session teardown.
+</ParamField>
**Returns** `BrowserSessionResponse` · TypeScript `Promise<BrowserSessionResponse>`
@@ -354,8 +398,6 @@ console.log(result);
Extend a live browser session by a number of minutes. Sessions are created with a timeout of at most 240 minutes and can be extended, one or more times, up to a total lifetime of 360 minutes (6 hours). The minutes are added to the session's current deadline. A request for more than the remaining headroom is granted the remainder, and the response carries a warning. The response's `timeout` is the session's new total budget in minutes, counted from when the session started.
-<Note>Python only: the TypeScript SDK has no equivalent.</Note>
-
<CodeGroup>
```python Python
await skyvern.extend_browser_session(
@@ -364,16 +406,25 @@ await skyvern.extend_browser_session(
additional_minutes: int,
) -> BrowserSessionResponse
```
+
+```typescript TypeScript
+skyvern.extendBrowserSession(browserSessionId: string, request: ExtendBrowserSessionRequest): Promise<BrowserSessionResponse>
+```
</CodeGroup>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `browser_session_id` | — | `str` | Yes | — | The ID of the browser session. browser_session_id starts with `pbs_` |
-| `additional_minutes` | — | `int` | Yes | — | Minutes to add to the session's current deadline. A session can be extended, one or more times, up to a total lifetime of 360 minutes (6 hours) counted from when it started; a request for more than the remaining headroom is granted the remainder and the response carries a warning. |
+<ParamField path={"browser_session_id"} type={"str"} required>
+The ID of the browser session. browser_session_id starts with `pbs_`
+
+TypeScript: `browserSessionId`
+</ParamField>
-**Returns** `BrowserSessionResponse`
+<ParamField path={"additional_minutes"} type={"int"} required>
+Minutes to add to the session's current deadline. A session can be extended, one or more times, up to a total lifetime of 360 minutes (6 hours) counted from when it started; a request for more than the remaining headroom is granted the remainder and the response carries a warning.
+</ParamField>
+
+**Returns** `BrowserSessionResponse` · TypeScript `Promise<BrowserSessionResponse>`
<Accordion title="BrowserSessionResponse fields">
@@ -423,6 +474,14 @@ async def main() -> None:
asyncio.run(main())
```
+
+```typescript TypeScript
+import { Skyvern } from "@skyvern/client";
+
+const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
+const result = await skyvern.extendBrowserSession("pbs_123", { additional_minutes: 60 });
+console.log(result);
+```
</CodeGroup>
---
@@ -443,11 +502,13 @@ skyvern.closeBrowserSession(browserSessionId: string): Promise<unknown>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `browser_session_id` | `browserSessionId` | `str` | Yes | — | The ID of the browser session to close. completed_at will be set when the browser session is closed. browser_session_id starts with `pbs_` |
+<ParamField path={"browser_session_id"} type={"str"} required>
+The ID of the browser session to close. completed_at will be set when the browser session is closed. browser_session_id starts with `pbs_`
+
+TypeScript: `browserSessionId`
+</ParamField>
-**Returns** `Any \| None` · TypeScript `Promise<unknown>`
+**Returns** `Any | None` · TypeScript `Promise<unknown>`
**Example**
diff --git a/docs/sdk-reference/credentials.mdx b/docs/sdk-reference/credentials.mdx
index c349a5b6e..c9d80c6c3 100644
--- a/docs/sdk-reference/credentials.mdx
+++ b/docs/sdk-reference/credentials.mdx
@@ -26,7 +26,7 @@ Creates a new credential for the current organization
await skyvern.create_credential(
*,
name: str,
- credential_type: SkyvernForgeSdkSchemasCredentialsCredentialType,
+ credential_type: "password" | "credit_card" | "secret",
credential: CreateCredentialRequestCredential,
vault_type: CredentialVaultType | None = ...,
proxy_location: CreateCredentialRequestProxyLocation | None = ...,
@@ -43,16 +43,47 @@ skyvern.createCredential(request: CreateCredentialRequest): Promise<CredentialRe
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `name` | `name` | `str` | Yes | — | Name of the credential |
-| `credential_type` | `credential_type` | `SkyvernForgeSdkSchemasCredentialsCredentialType` | Yes | — | Type of credential to create |
-| `credential` | `credential` | `CreateCredentialRequestCredential` | Yes | — | The credential data to store |
-| `vault_type` | `vault_type` | `CredentialVaultType \| None` | No | — | Which vault to store this credential in. If omitted, uses the instance default. Use this to mix Skyvern-hosted and custom credentials within the same organization. |
-| `proxy_location` | `proxy_location` | `CreateCredentialRequestProxyLocation \| None` | No | — | Optional proxy location for this credential's pinned proxy identity. |
-| `proxy_session_id` | `proxy_session_id` | `str \| None` | No | — | Optional advanced reuse key for this credential's pinned proxy identity. |
-| `rotate_proxy_session_id` | `rotate_proxy_session_id` | `bool \| None` | No | — | Rotate the Skyvern-managed proxy sticky-session id when updating this credential. |
-| `tested_url` | — | `str \| None` | No | — | Login page URL used during the credential test |
+<ParamField path={"name"} type={"str"} required>
+Name of the credential
+</ParamField>
+
+<ParamField path={"credential_type"} type={"\"password\" | \"credit_card\" | \"secret\""} required>
+Type of credential to create
+</ParamField>
+
+<ParamField path={"credential"} type={"CreateCredentialRequestCredential"} required>
+The credential data to store
+</ParamField>
+
+<ParamField path={"vault_type"} type={"CredentialVaultType | None"}>
+Which vault to store this credential in. If omitted, uses the instance default. Use this to mix Skyvern-hosted and custom credentials within the same organization.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"proxy_location"} type={"CreateCredentialRequestProxyLocation | None"}>
+Optional proxy location for this credential's pinned proxy identity.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"proxy_session_id"} type={"str | None"}>
+Optional advanced reuse key for this credential's pinned proxy identity.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"rotate_proxy_session_id"} type={"bool | None"}>
+Rotate the Skyvern-managed proxy sticky-session id when updating this credential.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"tested_url"} type={"str | None"}>
+Login page URL used during the credential test
+
+Sent only when you pass it
+</ParamField>
**Returns** `CredentialResponse` · TypeScript `Promise<CredentialResponse>`
@@ -128,9 +159,11 @@ skyvern.getCredential(credentialId: string): Promise<CredentialResponse>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `credential_id` | `credentialId` | `str` | Yes | — | The unique identifier of the credential |
+<ParamField path={"credential_id"} type={"str"} required>
+The unique identifier of the credential
+
+TypeScript: `credentialId`
+</ParamField>
**Returns** `CredentialResponse` · TypeScript `Promise<CredentialResponse>`
@@ -193,7 +226,7 @@ await skyvern.get_credentials(
page: int | None = None,
page_size: int | None = None,
vault_type: CredentialVaultType | None = None,
- credential_type: SkyvernForgeSdkSchemasCredentialsCredentialType | None = None,
+ credential_type: "password" | "credit_card" | "secret" | None = None,
search: str | None = None,
) -> list[CredentialResponse]
```
@@ -205,13 +238,35 @@ skyvern.getCredentials(request?: GetCredentialsRequest): Promise<CredentialRespo
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `page` | `page` | `int \| None` | No | `None` | Page number for pagination |
-| `page_size` | `page_size` | `int \| None` | No | `None` | Number of items per page |
-| `vault_type` | `vault_type` | `CredentialVaultType \| None` | No | `None` | Filter credentials by vault type (e.g. 'skyvern', 'custom', 'bitwarden', 'azure_vault') |
-| `credential_type` | `credential_type` | `SkyvernForgeSdkSchemasCredentialsCredentialType \| None` | No | `None` | Filter credentials by type (e.g. 'password', 'credit_card', 'secret') |
-| `search` | `search` | `str \| None` | No | `None` | Case-insensitive search across credential name, username, secret label, and card details |
+<ParamField path={"page"} type={"int | None"}>
+Page number for pagination
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"page_size"} type={"int | None"}>
+Number of items per page
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"vault_type"} type={"CredentialVaultType | None"}>
+Filter credentials by vault type (e.g. 'skyvern', 'custom', 'bitwarden', 'azure_vault')
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"credential_type"} type={"\"password\" | \"credit_card\" | \"secret\" | None"}>
+Filter credentials by type (e.g. 'password', 'credit_card', 'secret')
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"search"} type={"str | None"}>
+Case-insensitive search across credential name, username, secret label, and card details
+
+Default: `None`
+</ParamField>
**Returns** `list[CredentialResponse]` · TypeScript `Promise<CredentialResponse[]>`
@@ -273,7 +328,7 @@ await skyvern.update_credential(
credential_id: str,
*,
name: str,
- credential_type: SkyvernForgeSdkSchemasCredentialsCredentialType,
+ credential_type: "password" | "credit_card" | "secret",
credential: CreateCredentialRequestCredential,
vault_type: CredentialVaultType | None = ...,
proxy_location: CreateCredentialRequestProxyLocation | None = ...,
@@ -290,17 +345,53 @@ skyvern.updateCredential(credentialId: string, request: CreateCredentialRequest)
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `credential_id` | `credentialId` | `str` | Yes | — | The unique identifier of the credential to update |
-| `name` | `name` | `str` | Yes | — | Name of the credential |
-| `credential_type` | `credential_type` | `SkyvernForgeSdkSchemasCredentialsCredentialType` | Yes | — | Type of credential to create |
-| `credential` | `credential` | `CreateCredentialRequestCredential` | Yes | — | The credential data to store |
-| `vault_type` | `vault_type` | `CredentialVaultType \| None` | No | — | Which vault to store this credential in. If omitted, uses the instance default. Use this to mix Skyvern-hosted and custom credentials within the same organization. |
-| `proxy_location` | `proxy_location` | `CreateCredentialRequestProxyLocation \| None` | No | — | Optional proxy location for this credential's pinned proxy identity. |
-| `proxy_session_id` | `proxy_session_id` | `str \| None` | No | — | Optional advanced reuse key for this credential's pinned proxy identity. |
-| `rotate_proxy_session_id` | `rotate_proxy_session_id` | `bool \| None` | No | — | Rotate the Skyvern-managed proxy sticky-session id when updating this credential. |
-| `tested_url` | — | `str \| None` | No | — | Login page URL used during the credential test |
+<ParamField path={"credential_id"} type={"str"} required>
+The unique identifier of the credential to update
+
+TypeScript: `credentialId`
+</ParamField>
+
+<ParamField path={"name"} type={"str"} required>
+Name of the credential
+</ParamField>
+
+<ParamField path={"credential_type"} type={"\"password\" | \"credit_card\" | \"secret\""} required>
+Type of credential to create
+</ParamField>
+
+<ParamField path={"credential"} type={"CreateCredentialRequestCredential"} required>
+The credential data to store
+</ParamField>
+
+<ParamField path={"vault_type"} type={"CredentialVaultType | None"}>
+Which vault to store this credential in. If omitted, uses the instance default. Use this to mix Skyvern-hosted and custom credentials within the same organization.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"proxy_location"} type={"CreateCredentialRequestProxyLocation | None"}>
+Optional proxy location for this credential's pinned proxy identity.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"proxy_session_id"} type={"str | None"}>
+Optional advanced reuse key for this credential's pinned proxy identity.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"rotate_proxy_session_id"} type={"bool | None"}>
+Rotate the Skyvern-managed proxy sticky-session id when updating this credential.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"tested_url"} type={"str | None"}>
+Login page URL used during the credential test
+
+Sent only when you pass it
+</ParamField>
**Returns** `CredentialResponse` · TypeScript `Promise<CredentialResponse>`
@@ -377,9 +468,11 @@ skyvern.deleteCredential(credentialId: string): Promise<void>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `credential_id` | `credentialId` | `str` | Yes | — | The unique identifier of the credential to delete |
+<ParamField path={"credential_id"} type={"str"} required>
+The unique identifier of the credential to delete
+
+TypeScript: `credentialId`
+</ParamField>
**Returns** `None` · TypeScript `Promise<void>`
@@ -436,16 +529,49 @@ skyvern.sendTotpCode(request: TotpCodeCreate): Promise<TotpCode>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `totp_identifier` | `totp_identifier` | `str` | Yes | — | The identifier of the TOTP code. It can be the email address, phone number, or the identifier of the user. |
-| `content` | `content` | `str` | Yes | — | The content of the TOTP code. It can be the email content that contains the TOTP code, or the sms message that contains the TOTP code. Skyvern will automatically extract the TOTP code from the content. |
-| `task_id` | `task_id` | `str \| None` | No | — | The task_id the totp code is for. It can be the task_id of the task that the TOTP code is for. |
-| `workflow_id` | `workflow_id` | `str \| None` | No | — | The workflow ID the TOTP code is for. It can be the workflow ID of the workflow that the TOTP code is for. |
-| `workflow_run_id` | `workflow_run_id` | `str \| None` | No | — | The workflow run id that the TOTP code is for. It can be the workflow run id of the workflow run that the TOTP code is for. |
-| `source` | `source` | `str \| None` | No | — | An optional field. The source of the TOTP code. e.g. email, sms, etc. |
-| `expired_at` | `expired_at` | `datetime \| None` | No | — | The timestamp when the TOTP code expires |
-| `type` | `type` | `OtpType \| None` | No | — | Deprecated compatibility field. Skyvern auto-detects the OTP type from content, so this value does not constrain extraction. |
+<ParamField path={"totp_identifier"} type={"str"} required>
+The identifier of the TOTP code. It can be the email address, phone number, or the identifier of the user.
+</ParamField>
+
+<ParamField path={"content"} type={"str"} required>
+The content of the TOTP code. It can be the email content that contains the TOTP code, or the sms message that contains the TOTP code. Skyvern will automatically extract the TOTP code from the content.
+</ParamField>
+
+<ParamField path={"task_id"} type={"str | None"}>
+The task_id the totp code is for. It can be the task_id of the task that the TOTP code is for.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"workflow_id"} type={"str | None"}>
+The workflow ID the TOTP code is for. It can be the workflow ID of the workflow that the TOTP code is for.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"workflow_run_id"} type={"str | None"}>
+The workflow run id that the TOTP code is for. It can be the workflow run id of the workflow run that the TOTP code is for.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"source"} type={"str | None"}>
+An optional field. The source of the TOTP code. e.g. email, sms, etc.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"expired_at"} type={"datetime | None"}>
+The timestamp when the TOTP code expires
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"type"} type={"OtpType | None"}>
+Deprecated compatibility field. Skyvern auto-detects the OTP type from content, so this value does not constrain extraction.
+
+Sent only when you pass it
+</ParamField>
**Returns** `TotpCode` · TypeScript `Promise<TotpCode>`
diff --git a/docs/sdk-reference/files.mdx b/docs/sdk-reference/files.mdx
index bc132081b..0e5523180 100644
--- a/docs/sdk-reference/files.mdx
+++ b/docs/sdk-reference/files.mdx
@@ -55,9 +55,8 @@ skyvern.uploadFile(request: BodyUploadFileV1UploadFilePost): Promise<UploadFileR
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `file` | `file` | `str` | Yes | — | |
+<ParamField path={"file"} type={"str"} required>
+</ParamField>
**Returns** `UploadFileResponse` · TypeScript `Promise<UploadFileResponse>`
diff --git a/docs/sdk-reference/folders.mdx b/docs/sdk-reference/folders.mdx
index d6186f2e7..6c43612e7 100644
--- a/docs/sdk-reference/folders.mdx
+++ b/docs/sdk-reference/folders.mdx
@@ -30,10 +30,15 @@ skyvern.createFolder(request: FolderCreate): Promise<Folder>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `title` | `title` | `str` | Yes | — | Folder title |
-| `description` | `description` | `str \| None` | No | — | Folder description |
+<ParamField path={"title"} type={"str"} required>
+Folder title
+</ParamField>
+
+<ParamField path={"description"} type={"str | None"}>
+Folder description
+
+Sent only when you pass it
+</ParamField>
**Returns** `Folder` · TypeScript `Promise<Folder>`
@@ -96,9 +101,11 @@ skyvern.getFolder(folderId: string): Promise<Folder>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `folder_id` | `folderId` | `str` | Yes | — | Folder ID |
+<ParamField path={"folder_id"} type={"str"} required>
+Folder ID
+
+TypeScript: `folderId`
+</ParamField>
**Returns** `Folder` · TypeScript `Promise<Folder>`
@@ -166,11 +173,23 @@ skyvern.getFolders(request?: GetFoldersRequest): Promise<Folder[]>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `page` | `page` | `int \| None` | No | `None` | Page number |
-| `page_size` | `page_size` | `int \| None` | No | `None` | Number of folders per page |
-| `search` | `search` | `str \| None` | No | `None` | Search folders by title or description |
+<ParamField path={"page"} type={"int | None"}>
+Page number
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"page_size"} type={"int | None"}>
+Number of folders per page
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"search"} type={"str | None"}>
+Search folders by title or description
+
+Default: `None`
+</ParamField>
**Returns** `list[Folder]` · TypeScript `Promise<Folder[]>`
@@ -238,11 +257,23 @@ skyvern.updateFolder(folderId: string, request?: FolderUpdate): Promise<Folder>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `folder_id` | `folderId` | `str` | Yes | — | Folder ID |
-| `title` | `title` | `str \| None` | No | — | Folder title |
-| `description` | `description` | `str \| None` | No | — | Folder description |
+<ParamField path={"folder_id"} type={"str"} required>
+Folder ID
+
+TypeScript: `folderId`
+</ParamField>
+
+<ParamField path={"title"} type={"str | None"}>
+Folder title
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"description"} type={"str | None"}>
+Folder description
+
+Sent only when you pass it
+</ParamField>
**Returns** `Folder` · TypeScript `Promise<Folder>`
@@ -309,12 +340,19 @@ skyvern.deleteFolder(folderId: string, request?: DeleteFolderRequest): Promise<R
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `folder_id` | `folderId` | `str` | Yes | — | Folder ID |
-| `delete_workflows` | `delete_workflows` | `bool \| None` | No | `None` | If true, also delete all workflows in this folder |
+<ParamField path={"folder_id"} type={"str"} required>
+Folder ID
+
+TypeScript: `folderId`
+</ParamField>
+
+<ParamField path={"delete_workflows"} type={"bool | None"}>
+If true, also delete all workflows in this folder
-**Returns** `dict[str, Any \| None]` · TypeScript `Promise<Record<string, unknown>>`
+Default: `None`
+</ParamField>
+
+**Returns** `dict[str, Any | None]` · TypeScript `Promise<Record<string, unknown>>`
**Example**
@@ -365,10 +403,17 @@ skyvern.updateWorkflowFolder(workflowPermanentId: string, request?: UpdateWorkfl
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `workflow_permanent_id` | `workflowPermanentId` | `str` | Yes | — | Workflow permanent ID |
-| `folder_id` | `folder_id` | `str \| None` | No | — | Folder ID to assign workflow to. Set to null to remove from folder. |
+<ParamField path={"workflow_permanent_id"} type={"str"} required>
+Workflow permanent ID
+
+TypeScript: `workflowPermanentId`
+</ParamField>
+
+<ParamField path={"folder_id"} type={"str | None"}>
+Folder ID to assign workflow to. Set to null to remove from folder.
+
+Sent only when you pass it
+</ParamField>
**Returns** `Workflow` · TypeScript `Promise<Workflow>`
diff --git a/docs/sdk-reference/helpers.mdx b/docs/sdk-reference/helpers.mdx
index 1e0a4fb64..f6c40c7f9 100644
--- a/docs/sdk-reference/helpers.mdx
+++ b/docs/sdk-reference/helpers.mdx
@@ -55,32 +55,147 @@ skyvern.login(request: LoginOptions): Promise<WorkflowRunResponse>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `credential_type` | `credential_type` | `CredentialType` | Yes | — | Where to get the credential from |
-| `url` | `url` | `str \| None` | No | `None` | Website URL |
-| `credential_id` | `credential_id` | `str \| None` | No | `None` | ID of the Skyvern credential to use for login. |
-| `bitwarden_collection_id` | `bitwarden_collection_id` | `str \| None` | No | `None` | Bitwarden collection ID. You can find it in the Bitwarden collection URL. e.g. `https://vault.bitwarden.com/vaults/collection_id/items` |
-| `bitwarden_item_id` | `bitwarden_item_id` | `str \| None` | No | `None` | Bitwarden item ID |
-| `onepassword_vault_id` | `onepassword_vault_id` | `str \| None` | No | `None` | 1Password vault ID |
-| `onepassword_item_id` | `onepassword_item_id` | `str \| None` | No | `None` | 1Password item ID |
-| `prompt` | `prompt` | `str \| None` | No | `None` | Login instructions. Skyvern has default prompt/instruction for login if this field is not provided. |
-| `webhook_url` | `webhook_url` | `str \| None` | No | `None` | Webhook URL to send status updates |
-| `proxy_location` | `proxy_location` | `ProxyLocationInput` | No | `None` | Proxy location to use |
-| `totp_identifier` | `totp_identifier` | `str \| None` | No | `None` | Identifier for TOTP (Time-based One-Time Password) if required |
-| `totp_url` | `totp_url` | `str \| None` | No | `None` | TOTP URL to fetch one-time passwords |
-| `browser_session_id` | `browser_session_id` | `str \| None` | No | `None` | ID of the browser session to use, which is prefixed by `pbs_` e.g. `pbs_123456` |
-| `browser_address` | `browser_address` | `str \| None` | No | `None` | The CDP address for the task. |
-| `extra_http_headers` | `extra_http_headers` | `dict[str, str] \| None` | No | `None` | Additional HTTP headers to include in requests |
-| `max_screenshot_scrolling_times` | `max_screenshot_scrolling_times` | `int \| None` | No | `None` | Maximum number of times to scroll for screenshots |
-| `azure_vault_name` | `azure_vault_name` | `str \| None` | No | `None` | Azure Vault Name |
-| `azure_vault_username_key` | `azure_vault_username_key` | `str \| None` | No | `None` | Azure Vault username key |
-| `azure_vault_password_key` | `azure_vault_password_key` | `str \| None` | No | `None` | Azure Vault password key |
-| `azure_vault_totp_secret_key` | `azure_vault_totp_secret_key` | `str \| None` | No | `None` | Azure Vault TOTP secret key |
-| `wait_for_completion` | `waitForCompletion` | `bool` | No | `False` | Wait for the run to reach a final status before returning. |
-| `timeout` | `timeout` | `float` | No | `1800` | Maximum time to wait for completion, in seconds. |
-| — | `browser_profile_id` | `string` | No | — | ID of a browser profile to reuse for this run |
-| — | `cdp_connect_headers` | `Record<string, string \| undefined>` | No | — | HTTP headers attached ONLY to the CDP WebSocket handshake when connecting to a remote browser via browser_address. Never forwarded to target websites. |
+<ParamField path={"credential_type"} type={"CredentialType"} required>
+Where to get the credential from
+</ParamField>
+
+<ParamField path={"url"} type={"str | None"}>
+Website URL
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"credential_id"} type={"str | None"}>
+ID of the Skyvern credential to use for login.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"bitwarden_collection_id"} type={"str | None"}>
+Bitwarden collection ID. You can find it in the Bitwarden collection URL. e.g. `https://vault.bitwarden.com/vaults/collection_id/items`
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"bitwarden_item_id"} type={"str | None"}>
+Bitwarden item ID
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"onepassword_vault_id"} type={"str | None"}>
+1Password vault ID
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"onepassword_item_id"} type={"str | None"}>
+1Password item ID
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"prompt"} type={"str | None"}>
+Login instructions. Skyvern has default prompt/instruction for login if this field is not provided.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"webhook_url"} type={"str | None"}>
+Webhook URL to send status updates
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"proxy_location"} type={"ProxyLocationInput"}>
+Proxy location to use
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"totp_identifier"} type={"str | None"}>
+Identifier for TOTP (Time-based One-Time Password) if required
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"totp_url"} type={"str | None"}>
+TOTP URL to fetch one-time passwords
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"browser_session_id"} type={"str | None"}>
+ID of the browser session to use, which is prefixed by `pbs_` e.g. `pbs_123456`
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"browser_address"} type={"str | None"}>
+The CDP address for the task.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"extra_http_headers"} type={"dict[str, str] | None"}>
+Additional HTTP headers to include in requests
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"max_screenshot_scrolling_times"} type={"int | None"}>
+Maximum number of times to scroll for screenshots
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"azure_vault_name"} type={"str | None"}>
+Azure Vault Name
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"azure_vault_username_key"} type={"str | None"}>
+Azure Vault username key
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"azure_vault_password_key"} type={"str | None"}>
+Azure Vault password key
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"azure_vault_totp_secret_key"} type={"str | None"}>
+Azure Vault TOTP secret key
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"wait_for_completion"} type={"bool"}>
+Wait for the run to reach a final status before returning.
+
+Default: `False` · TypeScript: `waitForCompletion`
+</ParamField>
+
+<ParamField path={"timeout"} type={"float"}>
+Maximum time to wait for completion, in seconds.
+
+Default: `1800`
+</ParamField>
+
+<ParamField path={"browser_profile_id"} type={"string"}>
+ID of a browser profile to reuse for this run
+
+TypeScript only
+</ParamField>
+
+<ParamField path={"cdp_connect_headers"} type={"Record<string, string | undefined>"}>
+HTTP headers attached ONLY to the CDP WebSocket handshake when connecting to a remote browser via browser_address. Never forwarded to target websites.
+
+TypeScript only
+</ParamField>
**Returns** `WorkflowRunResponse` · TypeScript `Promise<WorkflowRunResponse>`
@@ -187,26 +302,107 @@ skyvern.downloadFiles(request: DownloadFilesOptions): Promise<WorkflowRunRespons
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `navigation_goal` | `navigation_goal` | `str` | Yes | — | Instructions for navigating to and downloading the file |
-| `user_agent` | `x-user-agent` | `str \| None` | No | `None` | User-Agent string the browser sends. |
-| `url` | `url` | `str \| None` | No | — | Website URL |
-| `webhook_url` | `webhook_url` | `str \| None` | No | — | Webhook URL to send status updates |
-| `proxy_location` | `proxy_location` | `ProxyLocation \| None` | No | — | Proxy location to use |
-| `totp_identifier` | `totp_identifier` | `str \| None` | No | — | Identifier for TOTP (Time-based One-Time Password) if required |
-| `totp_url` | `totp_url` | `str \| None` | No | — | TOTP URL to fetch one-time passwords |
-| `browser_session_id` | `browser_session_id` | `str \| None` | No | — | ID of the browser session to use, which is prefixed by `pbs_` e.g. `pbs_123456` |
-| `browser_profile_id` | `browser_profile_id` | `str \| None` | No | — | ID of a browser profile to reuse for this run |
-| `browser_address` | `browser_address` | `str \| None` | No | — | The CDP address for the task. |
-| `extra_http_headers` | `extra_http_headers` | `dict[str, str \| None] \| None` | No | — | Additional HTTP headers to include in requests |
-| `cdp_connect_headers` | `cdp_connect_headers` | `dict[str, str \| None] \| None` | No | — | HTTP headers attached ONLY to the CDP WebSocket handshake when connecting to a remote browser via browser_address. Never forwarded to target websites. |
-| `max_screenshot_scrolling_times` | `max_screenshot_scrolling_times` | `int \| None` | No | — | Maximum number of times to scroll for screenshots |
-| `download_suffix` | `download_suffix` | `str \| None` | No | — | Suffix or complete filename for the downloaded file |
-| `download_timeout` | `download_timeout` | `float \| None` | No | — | Timeout in seconds for the download operation |
-| `max_steps_per_run` | `max_steps_per_run` | `int \| None` | No | — | Maximum number of steps to execute |
-| — | `waitForCompletion` | `boolean` | No | — | TypeScript only. |
-| — | `timeout` | `number` | No | — | TypeScript only. |
+<ParamField path={"navigation_goal"} type={"str"} required>
+Instructions for navigating to and downloading the file
+</ParamField>
+
+<ParamField path={"user_agent"} type={"str | None"}>
+User-Agent string the browser sends.
+
+Default: `None` · TypeScript: `x-user-agent`
+</ParamField>
+
+<ParamField path={"url"} type={"str | None"}>
+Website URL
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"webhook_url"} type={"str | None"}>
+Webhook URL to send status updates
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"proxy_location"} type={"ProxyLocation | None"}>
+Proxy location to use
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"totp_identifier"} type={"str | None"}>
+Identifier for TOTP (Time-based One-Time Password) if required
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"totp_url"} type={"str | None"}>
+TOTP URL to fetch one-time passwords
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"browser_session_id"} type={"str | None"}>
+ID of the browser session to use, which is prefixed by `pbs_` e.g. `pbs_123456`
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"browser_profile_id"} type={"str | None"}>
+ID of a browser profile to reuse for this run
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"browser_address"} type={"str | None"}>
+The CDP address for the task.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"extra_http_headers"} type={"dict[str, str | None] | None"}>
+Additional HTTP headers to include in requests
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"cdp_connect_headers"} type={"dict[str, str | None] | None"}>
+HTTP headers attached ONLY to the CDP WebSocket handshake when connecting to a remote browser via browser_address. Never forwarded to target websites.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"max_screenshot_scrolling_times"} type={"int | None"}>
+Maximum number of times to scroll for screenshots
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"download_suffix"} type={"str | None"}>
+Suffix or complete filename for the downloaded file
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"download_timeout"} type={"float | None"}>
+Timeout in seconds for the download operation
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"max_steps_per_run"} type={"int | None"}>
+Maximum number of steps to execute
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"waitForCompletion"} type={"boolean"}>
+TypeScript only
+</ParamField>
+
+<ParamField path={"timeout"} type={"number"}>
+TypeScript only
+</ParamField>
**Returns** `WorkflowRunResponse` · TypeScript `Promise<WorkflowRunResponse>`
diff --git a/docs/sdk-reference/runs.mdx b/docs/sdk-reference/runs.mdx
index 050baeb6b..af8c2db1f 100644
--- a/docs/sdk-reference/runs.mdx
+++ b/docs/sdk-reference/runs.mdx
@@ -55,31 +55,141 @@ skyvern.runTask(request: RunTaskOptions): Promise<TaskRunResponse>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `prompt` | `prompt` | `str` | Yes | — | The goal or task description for Skyvern to accomplish |
-| `engine` | `engine` | `RunEngine` | No | `RunEngine.skyvern_v1` | The engine that runs the task. Defaults to `skyvern_v1` (`"skyvern-1.0"`), suited to simple, single-goal tasks. `skyvern_v3` (`"skyvern-3.0"`) is the newest engine; the REST API and the Python SDK accept it, but the published TypeScript client's type does not list it yet. `skyvern_v2` remains for existing 2.0 runs. `openai_cua` and `anthropic_cua` use OpenAI's and Anthropic's computer-use models; `ui_tars` and `yutori_navigator` are also accepted. |
-| `model` | `model` | `dict[str, Any] \| None` | No | `None` | Optional model configuration. |
-| `url` | `url` | `str \| None` | No | `None` | The starting URL for the task. If not provided, Skyvern will attempt to determine an appropriate URL |
-| `webhook_url` | `webhook_url` | `str \| None` | No | `None` | After a run is finished, send an update to this URL. Refer to https://www.skyvern.com/docs/running-tasks/webhooks-faq for more details. |
-| `totp_identifier` | `totp_identifier` | `str \| None` | No | `None` | Identifier for the TOTP/2FA/MFA code when the code is pushed to Skyvern. Refer to https://www.skyvern.com/docs/credentials/totp#option-3-push-code-to-skyvern for more details. |
-| `totp_url` | `totp_url` | `str \| None` | No | `None` | URL that serves TOTP/2FA/MFA codes for Skyvern to use during the workflow run. Refer to https://www.skyvern.com/docs/credentials/totp#option-2-get-code-from-your-endpoint for more details. |
-| `title` | `title` | `str \| None` | No | `None` | The title for the task |
-| `error_code_mapping` | `error_code_mapping` | `dict[str, str] \| None` | No | `None` | Custom mapping of error codes to error messages if Skyvern encounters an error. |
-| `data_extraction_schema` | `data_extraction_schema` | `dict[str, Any] \| str \| None` | No | `None` | The schema for data to be extracted from the webpage. If you're looking for consistent data schema being returned by the agent, it's highly recommended to use https://json-schema.org/. |
-| `proxy_location` | `proxy_location` | `ProxyLocationInput` | No | `None` | Geographic Proxy location to route the browser traffic through. This is only available in Skyvern Cloud. |
-| `max_steps` | `max_steps` | `int \| None` | No | `None` | Maximum number of steps the task can take. Task will fail if it exceeds this number. Cautions: you are charged per step so please set this number to a reasonable value. Contact [email protected] for custom pricing. |
-| `wait_for_completion` | `waitForCompletion` | `bool` | No | `False` | Wait for the run to reach a final status before returning. |
-| `timeout` | `timeout` | `float` | No | `1800` | Maximum time to wait for completion, in seconds. |
-| `browser_session_id` | `browser_session_id` | `str \| None` | No | `None` | Run the task or workflow in the specific Skyvern browser session. Having a browser session can persist the real-time state of the browser, so that the next run can continue from where the previous run left off. |
-| `user_agent` | `x-user-agent` | `str \| None` | No | `None` | User-Agent string the browser sends. |
-| `extra_http_headers` | `extra_http_headers` | `dict[str, str] \| None` | No | `None` | The extra HTTP headers for the requests in browser. |
-| `publish_workflow` | `publish_workflow` | `bool` | No | `False` | Deprecated. Whether to publish a `skyvern-2.0` task as a reusable workflow. For backwards compatibility, this routes the request through the legacy `skyvern-2.0` publish path. Prefer creating reusable workflows through the workflow APIs. |
-| `include_action_history_in_verification` | `include_action_history_in_verification` | `bool \| None` | No | `None` | Whether to include action history when verifying that the task is complete |
-| `max_screenshot_scrolls` | `max_screenshot_scrolls` | `int \| None` | No | `None` | The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot. |
-| `browser_address` | `browser_address` | `str \| None` | No | `None` | The CDP address for the task. |
-| — | `cdp_connect_headers` | `Record<string, string \| undefined>` | No | — | HTTP headers attached ONLY to the CDP WebSocket handshake when connecting to a remote browser via browser_address. Use this for browser-provider auth (e.g., x-api-key for Skyvern Cloud, Browserless, or similar). These headers are NEVER forwarded to target websites. |
-| — | `run_with` | `string` | No | — | Whether to run the task with agent or code. Null means use the default. |
+<ParamField path={"prompt"} type={"str"} required>
+The goal or task description for Skyvern to accomplish
+</ParamField>
+
+<ParamField path={"engine"} type={"RunEngine"}>
+The engine that runs the task. Defaults to `skyvern_v1` (`"skyvern-1.0"`), suited to simple, single-goal tasks. `skyvern_v3` (`"skyvern-3.0"`) is the newest engine; the REST API and the Python SDK accept it, but the published TypeScript client's type does not list it yet. `skyvern_v2` remains for existing 2.0 runs. `openai_cua` and `anthropic_cua` use OpenAI's and Anthropic's computer-use models; `ui_tars` and `yutori_navigator` are also accepted.
+
+Default: `RunEngine.skyvern_v1`
+</ParamField>
+
+<ParamField path={"model"} type={"dict[str, Any] | None"}>
+Optional model configuration.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"url"} type={"str | None"}>
+The starting URL for the task. If not provided, Skyvern will attempt to determine an appropriate URL
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"webhook_url"} type={"str | None"}>
+After a run is finished, send an update to this URL. Refer to https://www.skyvern.com/docs/running-tasks/webhooks-faq for more details.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"totp_identifier"} type={"str | None"}>
+Identifier for the TOTP/2FA/MFA code when the code is pushed to Skyvern. Refer to https://www.skyvern.com/docs/credentials/totp#option-3-push-code-to-skyvern for more details.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"totp_url"} type={"str | None"}>
+URL that serves TOTP/2FA/MFA codes for Skyvern to use during the workflow run. Refer to https://www.skyvern.com/docs/credentials/totp#option-2-get-code-from-your-endpoint for more details.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"title"} type={"str | None"}>
+The title for the task
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"error_code_mapping"} type={"dict[str, str] | None"}>
+Custom mapping of error codes to error messages if Skyvern encounters an error.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"data_extraction_schema"} type={"dict[str, Any] | str | None"}>
+The schema for data to be extracted from the webpage. If you're looking for consistent data schema being returned by the agent, it's highly recommended to use https://json-schema.org/.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"proxy_location"} type={"ProxyLocationInput"}>
+Geographic Proxy location to route the browser traffic through. This is only available in Skyvern Cloud.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"max_steps"} type={"int | None"}>
+Maximum number of steps the task can take. Task will fail if it exceeds this number. Cautions: you are charged per step so please set this number to a reasonable value. Contact [email protected] for custom pricing.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"wait_for_completion"} type={"bool"}>
+Wait for the run to reach a final status before returning.
+
+Default: `False` · TypeScript: `waitForCompletion`
+</ParamField>
+
+<ParamField path={"timeout"} type={"float"}>
+Maximum time to wait for completion, in seconds.
+
+Default: `1800`
+</ParamField>
+
+<ParamField path={"browser_session_id"} type={"str | None"}>
+Run the task or workflow in the specific Skyvern browser session. Having a browser session can persist the real-time state of the browser, so that the next run can continue from where the previous run left off.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"user_agent"} type={"str | None"}>
+User-Agent string the browser sends.
+
+Default: `None` · TypeScript: `x-user-agent`
+</ParamField>
+
+<ParamField path={"extra_http_headers"} type={"dict[str, str] | None"}>
+The extra HTTP headers for the requests in browser.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"publish_workflow"} type={"bool"}>
+Deprecated. Whether to publish a `skyvern-2.0` task as a reusable workflow. For backwards compatibility, this routes the request through the legacy `skyvern-2.0` publish path. Prefer creating reusable workflows through the workflow APIs.
+
+Default: `False`
+</ParamField>
+
+<ParamField path={"include_action_history_in_verification"} type={"bool | None"}>
+Whether to include action history when verifying that the task is complete
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"max_screenshot_scrolls"} type={"int | None"}>
+The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"browser_address"} type={"str | None"}>
+The CDP address for the task.
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"cdp_connect_headers"} type={"Record<string, string | undefined>"}>
+HTTP headers attached ONLY to the CDP WebSocket handshake when connecting to a remote browser via browser_address. Use this for browser-provider auth (e.g., x-api-key for Skyvern Cloud, Browserless, or similar). These headers are NEVER forwarded to target websites.
+
+TypeScript only
+</ParamField>
+
+<ParamField path={"run_with"} type={"string"}>
+Whether to run the task with agent or code. Null means use the default.
+
+TypeScript only
+</ParamField>
**Returns** `TaskRunResponse` · TypeScript `Promise<TaskRunResponse>`
@@ -158,9 +268,11 @@ skyvern.getRun(runId: string): Promise<GetRunResponse>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `run_id` | `runId` | `str` | Yes | — | The id of the task run or the workflow run. |
+<ParamField path={"run_id"} type={"str"} required>
+The id of the task run or the workflow run.
+
+TypeScript: `runId`
+</ParamField>
**Returns** `GetRunResponse` · TypeScript `Promise<GetRunResponse>`
@@ -216,13 +328,27 @@ skyvern.getRunsV2(request?: GetRunsV2Request): Promise<TaskRunListItem[]>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `page` | `page` | `int \| None` | No | `None` | |
-| `page_size` | `page_size` | `int \| None` | No | `None` | |
-| `status` | `status` | `RunStatus \| Sequence[RunStatus] \| None` | No | `None` | |
-| `search_key` | `search_key` | `str \| None` | No | `None` | Case-insensitive substring search (min 3 chars for trigram index). |
-| `run_type` | `run_type` | `RunType \| Sequence[RunType] \| None` | No | `None` | |
+<ParamField path={"page"} type={"int | None"}>
+Default: `None`
+</ParamField>
+
+<ParamField path={"page_size"} type={"int | None"}>
+Default: `None`
+</ParamField>
+
+<ParamField path={"status"} type={"RunStatus | Sequence[RunStatus] | None"}>
+Default: `None`
+</ParamField>
+
+<ParamField path={"search_key"} type={"str | None"}>
+Case-insensitive substring search (min 3 chars for trigram index).
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"run_type"} type={"RunType | Sequence[RunType] | None"}>
+Default: `None`
+</ParamField>
**Returns** `list[TaskRunListItem]` · TypeScript `Promise<TaskRunListItem[]>`
@@ -290,9 +416,11 @@ skyvern.getRunTimeline(runId: string): Promise<WorkflowRunTimeline[]>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `run_id` | `runId` | `str` | Yes | — | The id of the workflow run or task_v2 run. |
+<ParamField path={"run_id"} type={"str"} required>
+The id of the workflow run or task_v2 run.
+
+TypeScript: `runId`
+</ParamField>
**Returns** `list[WorkflowRunTimeline]` · TypeScript `Promise<WorkflowRunTimeline[]>`
@@ -354,11 +482,13 @@ skyvern.cancelRun(runId: string): Promise<unknown>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `run_id` | `runId` | `str` | Yes | — | The id of the task run or the workflow run to cancel. |
+<ParamField path={"run_id"} type={"str"} required>
+The id of the task run or the workflow run to cancel.
-**Returns** `Any \| None` · TypeScript `Promise<unknown>`
+TypeScript: `runId`
+</ParamField>
+
+**Returns** `Any | None` · TypeScript `Promise<unknown>`
**Example**
@@ -405,9 +535,9 @@ skyvern.bulkCancelRuns(request: BulkCancelRunsRequest): Promise<BulkCancelRunsRe
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `run_ids` | `run_ids` | `Sequence[str]` | Yes | — | List of run IDs to cancel |
+<ParamField path={"run_ids"} type={"Sequence[str]"} required>
+List of run IDs to cancel
+</ParamField>
**Returns** `BulkCancelRunsResponse` · TypeScript `Promise<BulkCancelRunsResponse>`
@@ -469,11 +599,15 @@ skyvern.retryRunWebhook(runId: string, request?: RetryRunWebhookRequest): Promis
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `run_id` | `runId` | `str` | Yes | — | The id of the task run or the workflow run. |
-| `request` | — | `RetryRunWebhookRequest \| None` | No | `None` | |
-| — | `webhook_url` | `string` | No | — | Optional webhook URL to send the payload to instead of the stored configuration |
+<ParamField path={"run_id"} type={"str"} required>
+The id of the task run or the workflow run.
+
+TypeScript: `runId`
+</ParamField>
+
+<ParamField path={"request"} type={"RetryRunWebhookRequest | None"}>
+Default: `None`
+</ParamField>
**Returns** `RunWebhookReplayResponse` · TypeScript `Promise<RunWebhookReplayResponse>`
diff --git a/docs/sdk-reference/schedules.mdx b/docs/sdk-reference/schedules.mdx
index a34862a09..9e683e0ab 100644
--- a/docs/sdk-reference/schedules.mdx
+++ b/docs/sdk-reference/schedules.mdx
@@ -37,12 +37,25 @@ skyvern.schedules.listAll(request?: SchedulesListAllRequest): Promise<Organizati
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `page` | `page` | `int \| None` | No | `None` | |
-| `page_size` | `page_size` | `int \| None` | No | `None` | |
-| `status` | `status` | `SchedulesListAllRequestStatus \| None` | No | `None` | Filter by status: 'active' or 'paused' |
-| `search` | `search` | `str \| None` | No | `None` | Search by workflow title or schedule name |
+<ParamField path={"page"} type={"int | None"}>
+Default: `None`
+</ParamField>
+
+<ParamField path={"page_size"} type={"int | None"}>
+Default: `None`
+</ParamField>
+
+<ParamField path={"status"} type={"SchedulesListAllRequestStatus | None"}>
+Filter by status: 'active' or 'paused'
+
+Default: `None`
+</ParamField>
+
+<ParamField path={"search"} type={"str | None"}>
+Search by workflow title or schedule name
+
+Default: `None`
+</ParamField>
**Returns** `OrganizationScheduleListResponse` · TypeScript `Promise<OrganizationScheduleListResponse>`
@@ -102,9 +115,11 @@ skyvern.schedules.list(workflowPermanentId: string): Promise<WorkflowScheduleLis
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `workflow_permanent_id` | `workflowPermanentId` | `str` | Yes | — | ID of the agent (`wpid_…`). |
+<ParamField path={"workflow_permanent_id"} type={"str"} required>
+ID of the agent (`wpid_…`).
+
+TypeScript: `workflowPermanentId`
+</ParamField>
**Returns** `WorkflowScheduleListResponse` · TypeScript `Promise<WorkflowScheduleListResponse>`
@@ -173,18 +188,52 @@ skyvern.schedules.create(workflowPermanentId: string, request: WorkflowScheduleU
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `workflow_permanent_id` | `workflowPermanentId` | `str` | Yes | — | ID of the agent (`wpid_…`). |
-| `timezone` | `timezone` | `str` | Yes | — | |
-| `cron_expression` | `cron_expression` | `str \| None` | No | — | |
-| `interval_seconds` | — | `int \| None` | No | — | Fixed elapsed interval between runs, in seconds. Mutually exclusive with cron_expression. |
-| `first_fire_at` | — | `datetime \| None` | No | — | First run of an interval schedule; later runs follow every interval_seconds from it. Must be in the future when changed. Defaults to one interval after creation. |
-| `run_at` | — | `datetime \| None` | No | — | Run the agent once at this instant, ISO 8601 with a UTC offset, at least 60 seconds in the future. Mutually exclusive with cron_expression and interval_seconds; the schedule can be edited or canceled only until it fires. |
-| `enabled` | `enabled` | `bool \| None` | No | — | |
-| `parameters` | `parameters` | `dict[str, Any \| None] \| None` | No | — | |
-| `name` | `name` | `str \| None` | No | — | |
-| `description` | `description` | `str \| None` | No | — | |
+<ParamField path={"workflow_permanent_id"} type={"str"} required>
+ID of the agent (`wpid_…`).
+
+TypeScript: `workflowPermanentId`
+</ParamField>
+
+<ParamField path={"timezone"} type={"str"} required>
+</ParamField>
+
+<ParamField path={"cron_expression"} type={"str | None"}>
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"interval_seconds"} type={"int | None"}>
+Fixed elapsed interval between runs, in seconds. Mutually exclusive with cron_expression.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"first_fire_at"} type={"datetime | None"}>
+First run of an interval schedule; later runs follow every interval_seconds from it. Must be in the future when changed. Defaults to one interval after creation.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"run_at"} type={"datetime | None"}>
+Run the agent once at this instant, ISO 8601 with a UTC offset, at least 60 seconds in the future. Mutually exclusive with cron_expression and interval_seconds; the schedule can be edited or canceled only until it fires.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"enabled"} type={"bool | None"}>
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"parameters"} type={"dict[str, Any | None] | None"}>
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"name"} type={"str | None"}>
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"description"} type={"str | None"}>
+Sent only when you pass it
+</ParamField>
**Returns** `WorkflowScheduleResponse` · TypeScript `Promise<WorkflowScheduleResponse>`
@@ -252,10 +301,17 @@ skyvern.schedules.get(workflowPermanentId: string, workflowScheduleId: string):
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `workflow_permanent_id` | `workflowPermanentId` | `str` | Yes | — | ID of the agent (`wpid_…`). |
-| `workflow_schedule_id` | `workflowScheduleId` | `str` | Yes | — | ID of the schedule. |
+<ParamField path={"workflow_permanent_id"} type={"str"} required>
+ID of the agent (`wpid_…`).
+
+TypeScript: `workflowPermanentId`
+</ParamField>
+
+<ParamField path={"workflow_schedule_id"} type={"str"} required>
+ID of the schedule.
+
+TypeScript: `workflowScheduleId`
+</ParamField>
**Returns** `WorkflowScheduleResponse` · TypeScript `Promise<WorkflowScheduleResponse>`
@@ -329,19 +385,58 @@ skyvern.schedules.update(workflowPermanentId: string, workflowScheduleId: string
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `workflow_permanent_id` | `workflowPermanentId` | `str` | Yes | — | ID of the agent (`wpid_…`). |
-| `workflow_schedule_id` | `workflowScheduleId` | `str` | Yes | — | ID of the schedule. |
-| `timezone` | `timezone` | `str` | Yes | — | |
-| `cron_expression` | `cron_expression` | `str \| None` | No | — | |
-| `interval_seconds` | — | `int \| None` | No | — | Fixed elapsed interval between runs, in seconds. Mutually exclusive with cron_expression. |
-| `first_fire_at` | — | `datetime \| None` | No | — | First run of an interval schedule; later runs follow every interval_seconds from it. Must be in the future when changed. Defaults to one interval after creation. |
-| `run_at` | — | `datetime \| None` | No | — | Run the agent once at this instant, ISO 8601 with a UTC offset, at least 60 seconds in the future. Mutually exclusive with cron_expression and interval_seconds; the schedule can be edited or canceled only until it fires. |
-| `enabled` | `enabled` | `bool \| None` | No | — | |
-| `parameters` | `parameters` | `dict[str, Any \| None] \| None` | No | — | |
-| `name` | `name` | `str \| None` | No | — | |
-| `description` | `description` | `str \| None` | No | — | |
+<ParamField path={"workflow_permanent_id"} type={"str"} required>
+ID of the agent (`wpid_…`).
+
+TypeScript: `workflowPermanentId`
+</ParamField>
+
+<ParamField path={"workflow_schedule_id"} type={"str"} required>
+ID of the schedule.
+
+TypeScript: `workflowScheduleId`
+</ParamField>
+
+<ParamField path={"timezone"} type={"str"} required>
+</ParamField>
+
+<ParamField path={"cron_expression"} type={"str | None"}>
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"interval_seconds"} type={"int | None"}>
+Fixed elapsed interval between runs, in seconds. Mutually exclusive with cron_expression.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"first_fire_at"} type={"datetime | None"}>
+First run of an interval schedule; later runs follow every interval_seconds from it. Must be in the future when changed. Defaults to one interval after creation.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"run_at"} type={"datetime | None"}>
+Run the agent once at this instant, ISO 8601 with a UTC offset, at least 60 seconds in the future. Mutually exclusive with cron_expression and interval_seconds; the schedule can be edited or canceled only until it fires.
+
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"enabled"} type={"bool | None"}>
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"parameters"} type={"dict[str, Any | None] | None"}>
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"name"} type={"str | None"}>
+Sent only when you pass it
+</ParamField>
+
+<ParamField path={"description"} type={"str | None"}>
+Sent only when you pass it
+</ParamField>
**Returns** `WorkflowScheduleResponse` · TypeScript `Promise<WorkflowScheduleResponse>`
@@ -410,10 +505,17 @@ skyvern.schedules.enable(workflowPermanentId: string, workflowScheduleId: string
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `workflow_permanent_id` | `workflowPermanentId` | `str` | Yes | — | ID of the agent (`wpid_…`). |
-| `workflow_schedule_id` | `workflowScheduleId` | `str` | Yes | — | ID of the schedule. |
+<ParamField path={"workflow_permanent_id"} type={"str"} required>
+ID of the agent (`wpid_…`).
+
+TypeScript: `workflowPermanentId`
+</ParamField>
+
+<ParamField path={"workflow_schedule_id"} type={"str"} required>
+ID of the schedule.
+
+TypeScript: `workflowScheduleId`
+</ParamField>
**Returns** `WorkflowScheduleResponse` · TypeScript `Promise<WorkflowScheduleResponse>`
@@ -477,10 +579,17 @@ skyvern.schedules.disable(workflowPermanentId: string, workflowScheduleId: strin
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `workflow_permanent_id` | `workflowPermanentId` | `str` | Yes | — | ID of the agent (`wpid_…`). |
-| `workflow_schedule_id` | `workflowScheduleId` | `str` | Yes | — | ID of the schedule. |
+<ParamField path={"workflow_permanent_id"} type={"str"} required>
+ID of the agent (`wpid_…`).
+
+TypeScript: `workflowPermanentId`
+</ParamField>
+
+<ParamField path={"workflow_schedule_id"} type={"str"} required>
+ID of the schedule.
+
+TypeScript: `workflowScheduleId`
+</ParamField>
**Returns** `WorkflowScheduleResponse` · TypeScript `Promise<WorkflowScheduleResponse>`
@@ -529,8 +638,6 @@ console.log(result);
Cancel a one-time schedule that has not fired yet. The schedule stays readable with dispatch_status canceled. Returns 409 once it has fired or was already canceled, and 422 for a recurring schedule.
-<Note>Python only: the TypeScript SDK has no equivalent.</Note>
-
<CodeGroup>
```python Python
await skyvern.schedules.cancel(
@@ -538,16 +645,27 @@ await skyvern.schedules.cancel(
workflow_schedule_id: str,
) -> WorkflowScheduleResponse
```
+
+```typescript TypeScript
+skyvern.schedules.cancel(workflowPermanentId: string, workflowScheduleId: string): Promise<WorkflowScheduleResponse>
+```
</CodeGroup>
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `workflow_permanent_id` | — | `str` | Yes | — | ID of the agent (`wpid_…`). |
-| `workflow_schedule_id` | — | `str` | Yes | — | ID of the schedule. |
+<ParamField path={"workflow_permanent_id"} type={"str"} required>
+ID of the agent (`wpid_…`).
+
+TypeScript: `workflowPermanentId`
+</ParamField>
+
+<ParamField path={"workflow_schedule_id"} type={"str"} required>
+ID of the schedule.
+
+TypeScript: `workflowScheduleId`
+</ParamField>
-**Returns** `WorkflowScheduleResponse`
+**Returns** `WorkflowScheduleResponse` · TypeScript `Promise<WorkflowScheduleResponse>`
<Accordion title="WorkflowScheduleResponse fields">
@@ -578,6 +696,14 @@ async def main() -> None:
asyncio.run(main())
```
+
+```typescript TypeScript
+import { Skyvern } from "@skyvern/client";
+
+const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
+const result = await skyvern.schedules.cancel("wpid_123", "wfs_123");
+console.log(result);
+```
</CodeGroup>
---
@@ -601,10 +727,17 @@ skyvern.schedules.delete(workflowPermanentId: string, workflowScheduleId: string
**Parameters**
-| Parameter | TypeScript | Type | Required | Default | Description |
-|---|---|---|---|---|---|
-| `workflow_permanent_id` | `workflowPermanentId` | `str` | Yes | — | ID of the agent (`wpid_…`). |
-| `workflow_schedule_id` | `workflowScheduleId` | `str` | Yes | — | ID of the schedule. |
+<ParamField path={"workflow_permanent_id"} type={"str"} required>
+ID of the agent (`wpid_…`).
+
+TypeScript: `workflowPermanentId`
+</ParamField>
+
+<ParamField path={"workflow_schedule_id"} type={"str"} required>
+ID of the schedule.
+
+TypeScript: `workflowScheduleId`
+</ParamField>
**Returns** `DeleteScheduleResponse` · TypeScript `Promise<DeleteScheduleResponse>`
diff --git a/skyvern-frontend/src/routes/workflows/studio/runview/RunSummaryStrip.test.tsx b/skyvern-frontend/src/routes/workflows/studio/runview/RunSummaryStrip.test.tsx
index 0358fe3f3..cf4ac436b 100644
--- a/skyvern-frontend/src/routes/workflows/studio/runview/RunSummaryStrip.test.tsx
+++ b/skyvern-frontend/src/routes/workflows/studio/runview/RunSummaryStrip.test.tsx
@@ -253,4 +253,46 @@ describe("RunSummaryStrip failure category", () => {
expect(screen.queryByRole("link")).toBeNull();
}
});
+
+ test("a saved run whose pinned browser session ended before its lease links to browser sessions", () => {
+ const leaseFailure = (reason_code: string) =>
+ makeRun({
+ status: Status.Failed,
+ failure_category: [
+ {
+ category:
+ reason_code === "browser_session_expired_before_run"
+ ? "BROWSER_SESSION_EXPIRED"
+ : "BROWSER_ERROR",
+ confidence_float: 1.0,
+ reasoning: "the session had already closed",
+ reason_code,
+ },
+ ],
+ });
+
+ renderStrip(leaseFailure("browser_session_expired_before_run"));
+ expect(
+ screen
+ .getByRole("link", { name: "Review browser sessions" })
+ .getAttribute("href"),
+ ).toBe("/browser-sessions");
+
+ for (const reasonCode of [
+ "browser_session_closed",
+ "browser_session_startup_timeout",
+ ]) {
+ cleanup();
+ renderStrip(leaseFailure(reasonCode));
+ expect(
+ screen
+ .getByRole("link", { name: "Review browser sessions" })
+ .getAttribute("href"),
+ ).toBe("/browser-sessions");
+ }
+
+ cleanup();
+ renderStrip(leaseFailure("unrelated_failure"));
+ expect(screen.queryByRole("link")).toBeNull();
+ });
});
diff --git a/skyvern-frontend/src/routes/workflows/studio/runview/RunSummaryStrip.tsx b/skyvern-frontend/src/routes/workflows/studio/runview/RunSummaryStrip.tsx
index 27e2d7f35..f49c67212 100644
--- a/skyvern-frontend/src/routes/workflows/studio/runview/RunSummaryStrip.tsx
+++ b/skyvern-frontend/src/routes/workflows/studio/runview/RunSummaryStrip.tsx
@@ -59,12 +59,21 @@ export function RunSummaryStrip({
: null,
].filter((chip): chip is string => Boolean(chip));
// failure_category is untyped JSON on the backend, so guard each entry at runtime.
- const signedOutProfileId = (Array.isArray(workflowRun.failure_category)
+ const failureEntries = Array.isArray(workflowRun.failure_category)
? workflowRun.failure_category
- : []
- ).some((entry) => entry?.reason_code === "saved_profile_signed_out")
+ : [];
+ const signedOutProfileId = failureEntries.some(
+ (entry) => entry?.reason_code === "saved_profile_signed_out",
+ )
? workflowRun.browser_profile_id
: null;
+ // Reasons lack session source, so use a general session-list link, not a create CTA.
+ const browserSessionEnded = failureEntries.some(
+ (entry) =>
+ entry?.reason_code === "browser_session_expired_before_run" ||
+ entry?.reason_code === "browser_session_closed" ||
+ entry?.reason_code === "browser_session_startup_timeout",
+ );
// A run keeps its profile id after the profile is deleted, and the Refresh
// dialog cannot open for a deleted profile. Cached data stays successful
// until a refetch fails, so only a settled lookup from this visit counts.
@@ -91,6 +100,14 @@ export function RunSummaryStrip({
failureCategory={workflowRun.failure_category}
/>
) : null}
+ {!statusUnavailable && browserSessionEnded ? (
+ <Link
+ to="/browser-sessions"
+ className="whitespace-nowrap text-blue-700 hover:underline dark:text-blue-400 dark:hover:text-blue-300"
+ >
+ Review browser sessions
+ </Link>
+ ) : null}
{!statusUnavailable &&
signedOutProfileId &&
signedOutProfile.isSuccess &&
@@ -98,7 +115,7 @@ export function RunSummaryStrip({
!signedOutProfile.isFetching ? (
<Link
to={`/browser-profiles/${signedOutProfileId}?refresh=1`}
- className="whitespace-nowrap text-blue-400 hover:text-blue-300"
+ className="whitespace-nowrap text-blue-700 hover:underline dark:text-blue-400 dark:hover:text-blue-300"
>
Sign in again to refresh
</Link>
diff --git a/skyvern/exceptions.py b/skyvern/exceptions.py
index 20e373744..6d217f107 100644
--- a/skyvern/exceptions.py
+++ b/skyvern/exceptions.py
@@ -138,8 +138,16 @@ class SkyvernClientException(SkyvernException):
class SkyvernHTTPException(SkyvernException):
- def __init__(self, message: str | None = None, status_code: int | HTTPStatus = HTTPStatus.BAD_REQUEST):
+ def __init__(
+ self,
+ message: str | None = None,
+ status_code: int | HTTPStatus = HTTPStatus.BAD_REQUEST,
+ error_code: str | None = None,
+ ):
self.status_code = int(status_code)
+ # Serialized alongside `detail` only when set, so a caller can branch on the cause without
+ # matching on prose. Treat a code as a published contract once a response carries it.
+ self.error_code = error_code
super().__init__(message)
@@ -1826,13 +1834,26 @@ REREGISTER_EXTERNAL_BROWSER = (
"(POST /v1/browser_sessions/external) and pass the new id."
)
+# HTTP error codes are separate from persisted failure_category reason codes, even where their values match.
+BROWSER_SESSION_EXPIRED_ERROR_CODE = "browser_session_expired"
+BROWSER_SESSION_CLOSED_ERROR_CODE = "browser_session_closed"
+BROWSER_SESSION_STARTUP_TIMEOUT_ERROR_CODE = "browser_session_startup_timeout"
+
class BrowserSessionClosed(SkyvernHTTPException):
- def __init__(self, browser_session_id: str, *, reason: str | None = None, registered: bool = False) -> None:
+ def __init__(
+ self,
+ browser_session_id: str,
+ *,
+ reason: str | None = None,
+ registered: bool = False,
+ error_code: str = BROWSER_SESSION_CLOSED_ERROR_CODE,
+ ) -> None:
remedy = REREGISTER_EXTERNAL_BROWSER if registered else "Create a new browser session and retry."
super().__init__(
f"Browser session {browser_session_id} {reason or 'is closed'}. {remedy}",
status_code=HTTPStatus.GONE,
+ error_code=error_code,
)
@@ -1865,11 +1886,17 @@ class BrowserSessionExpired(BrowserSessionClosed):
self.bound = bound
if refused_at_submission and not registered:
SkyvernHTTPException.__init__(
- self, self.expired_before_run_message(run_created=False), status_code=HTTPStatus.GONE
+ self,
+ self.expired_before_run_message(run_created=False),
+ status_code=HTTPStatus.GONE,
+ error_code=BROWSER_SESSION_EXPIRED_ERROR_CODE,
)
else:
super().__init__(
- browser_session_id, reason="expired after reaching its configured lifetime", registered=registered
+ browser_session_id,
+ reason="expired after reaching its configured lifetime",
+ registered=registered,
+ error_code=BROWSER_SESSION_EXPIRED_ERROR_CODE,
)
def expired_before_run_message(self, *, run_created: bool) -> str:
@@ -1940,8 +1967,10 @@ class BrowserSessionSwitchNotAllowed(SkyvernException):
class BrowserSessionStartupTimeout(SkyvernHTTPException):
def __init__(self, browser_session_id: str) -> None:
super().__init__(
- f"Browser session {browser_session_id} failed to start within the timeout period.",
+ f"Browser session {browser_session_id} failed to start within the timeout period. "
+ "Create a new browser session and retry with its id.",
status_code=HTTPStatus.GATEWAY_TIMEOUT,
+ error_code=BROWSER_SESSION_STARTUP_TIMEOUT_ERROR_CODE,
)
diff --git a/skyvern/forge/agent.py b/skyvern/forge/agent.py
index 7790fc0ce..239e192c1 100644
--- a/skyvern/forge/agent.py
+++ b/skyvern/forge/agent.py
@@ -2255,7 +2255,9 @@ class ForgeAgent:
)
if not browser_session:
raise BrowserSessionNotFound(browser_session_id=task_request.browser_session_id)
- unusable = unusable_browser_session_error(browser_session, refused_at_submission=True)
+ unusable = unusable_browser_session_error(
+ browser_session, refused_at_submission=True, submission_path="task_v1"
+ )
if unusable is not None:
raise unusable
diff --git a/skyvern/forge/api_app.py b/skyvern/forge/api_app.py
index 94d077bda..1c2313e92 100644
--- a/skyvern/forge/api_app.py
+++ b/skyvern/forge/api_app.py
@@ -83,7 +83,10 @@ SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
async def handle_skyvern_http_exception(request: Request, exc: SkyvernHTTPException) -> JSONResponse:
- return JSONResponse(status_code=exc.status_code, content={"detail": exc.message})
+ content: dict[str, str | None] = {"detail": exc.message}
+ if exc.error_code is not None:
+ content["error_code"] = exc.error_code
+ return JSONResponse(status_code=exc.status_code, content=content)
async def db_unavailable_handler(
diff --git a/skyvern/forge/failure_classifier.py b/skyvern/forge/failure_classifier.py
index 81b19bcc2..1c8febe19 100644
--- a/skyvern/forge/failure_classifier.py
+++ b/skyvern/forge/failure_classifier.py
@@ -8,7 +8,11 @@ from typing import Any
import structlog
from skyvern.constants import PROXY_TRANSPORT_NAV_ERRORS
-from skyvern.exceptions import NO_ADDRESS_RECORD_NAV_ERROR_MARKER, CaptchaSolveError, FailedToNavigateToUrl
+from skyvern.exceptions import (
+ NO_ADDRESS_RECORD_NAV_ERROR_MARKER,
+ CaptchaSolveError,
+ FailedToNavigateToUrl,
+)
LOG = structlog.get_logger(__name__)
@@ -603,9 +607,7 @@ _MIN_ATTRIBUTION_CONFIDENCE = 0.7
# Shared with typed run emitters; dynamic/user-defined categories remain excluded.
_FAILURE_CATEGORY_LITERALS = frozenset(category.value for category in FailureCategory)
-# Bounded reason codes emitted by out-of-module terminal producers. Defined here as the single
-# source of truth so a producer and this allowlist cannot drift: the browser-lease seam
-# (skyvern/forge/sdk/workflow/service.py::_browser_lease_failure_category) imports these.
+# Persisted failure_category reason codes are separate from HTTP error codes, even where their values match.
BROWSER_SESSION_CLOSED_REASON_CODE = "browser_session_closed"
BROWSER_SESSION_STARTUP_TIMEOUT_REASON_CODE = "browser_session_startup_timeout"
BROWSER_SESSION_EXPIRED_BEFORE_RUN_REASON_CODE = "browser_session_expired_before_run"
diff --git a/skyvern/forge/sdk/schemas/persistent_browser_sessions.py b/skyvern/forge/sdk/schemas/persistent_browser_sessions.py
index a9305dd7d..3fcb4ec6e 100644
--- a/skyvern/forge/sdk/schemas/persistent_browser_sessions.py
+++ b/skyvern/forge/sdk/schemas/persistent_browser_sessions.py
@@ -1,8 +1,9 @@
from datetime import datetime, timedelta, timezone
from decimal import Decimal
from enum import StrEnum
-from typing import TypeGuard
+from typing import Literal, TypeGuard
+import structlog
from pydantic import BaseModel, ConfigDict, Field, field_validator
from skyvern.exceptions import (
@@ -22,6 +23,8 @@ from skyvern.schemas.external_cdp import EXTERNAL_CDP_BROWSER_VENDOR
from skyvern.schemas.proxy_pinning import validate_proxy_session_id
from skyvern.schemas.runs import GeoTarget, ProxyLocation, ProxyLocationInput
+LOG = structlog.get_logger(__name__)
+
class PersistentBrowserSessionStatus(StrEnum):
created = "created"
@@ -218,7 +221,10 @@ def assert_runnable_owner(
def unusable_browser_session_error(
- session: PersistentBrowserSession, *, refused_at_submission: bool = False
+ session: PersistentBrowserSession,
+ *,
+ refused_at_submission: bool = False,
+ submission_path: Literal["workflow_run", "task_v1", "task_v2"] | None = None,
) -> SkyvernHTTPException | None:
"""The error a run sent to this session fails (or, at submission, is refused) with, or None while it is usable.
@@ -234,11 +240,12 @@ def unusable_browser_session_error(
return None
session_id = session.persistent_browser_session_id
timed_out = session.status == PersistentBrowserSessionStatus.timeout
+ error: SkyvernHTTPException
if timed_out and session.started_at is None:
- return BrowserSessionStartupTimeout(session_id)
+ error = BrowserSessionStartupTimeout(session_id)
# A session that reaches its lifetime ends with status timeout, or is closed as completed with close reason
# expired, a reason a retirement can also stamp before the lifetime is up.
- if (
+ elif (
timed_out
or expired_open_registration
or (
@@ -248,7 +255,7 @@ def unusable_browser_session_error(
)
)
):
- return BrowserSessionExpired(
+ error = BrowserSessionExpired(
session_id,
started_at=session.started_at,
ended_at=session.completed_at,
@@ -258,11 +265,20 @@ def unusable_browser_session_error(
refused_at_submission=refused_at_submission,
registered=is_external_cdp_session(session),
)
- return BrowserSessionClosed(
- session_id,
- reason=f"is no longer usable (status: {session.status})",
- registered=is_external_cdp_session(session),
- )
+ else:
+ error = BrowserSessionClosed(
+ session_id,
+ reason=f"is no longer usable (status: {session.status})",
+ registered=is_external_cdp_session(session),
+ )
+ if refused_at_submission:
+ LOG.warning(
+ "browser_session_run_refused",
+ error_code=error.error_code,
+ browser_session_id=session_id,
+ submission_path=submission_path,
+ )
+ return error
def lost_external_browser_error(session: PersistentBrowserSession | None) -> SkyvernHTTPException:
diff --git a/skyvern/forge/sdk/workflow/service.py b/skyvern/forge/sdk/workflow/service.py
index 3fac2a784..7a584cccb 100644
--- a/skyvern/forge/sdk/workflow/service.py
+++ b/skyvern/forge/sdk/workflow/service.py
@@ -11822,7 +11822,9 @@ class WorkflowService:
raise BrowserSessionNotFound(browser_session_id=workflow_request.browser_session_id)
# Nothing between here and the lease swaps or revives a caller's session, so a run sent to
# one that has already ended can only fail; refuse it before a run row exists.
- unusable = unusable_browser_session_error(browser_session, refused_at_submission=True)
+ unusable = unusable_browser_session_error(
+ browser_session, refused_at_submission=True, submission_path="workflow_run"
+ )
if unusable is not None:
raise unusable
# Auto-propagate profile from session when not explicitly provided
diff --git a/skyvern/services/task_v2_service.py b/skyvern/services/task_v2_service.py
index c1e22f8ab..2176eb840 100644
--- a/skyvern/services/task_v2_service.py
+++ b/skyvern/services/task_v2_service.py
@@ -371,7 +371,9 @@ async def initialize_task_v2(
)
if not browser_session:
raise BrowserSessionNotFound(browser_session_id=browser_session_id)
- unusable = unusable_browser_session_error(browser_session, refused_at_submission=True)
+ unusable = unusable_browser_session_error(
+ browser_session, refused_at_submission=True, submission_path="task_v2"
+ )
if unusable is not None:
raise unusable
diff --git a/tests/unit/test_browser_session_timeouts.py b/tests/unit/test_browser_session_timeouts.py
index b6f9f1d3a..33bd1d785 100644
--- a/tests/unit/test_browser_session_timeouts.py
+++ b/tests/unit/test_browser_session_timeouts.py
@@ -4,6 +4,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
import pytest
from pydantic import ValidationError
+from structlog.testing import capture_logs
from skyvern.exceptions import BrowserSessionClosed, BrowserSessionExpired, BrowserSessionStartupTimeout
from skyvern.forge.sdk.routes import browser_sessions as browser_sessions_routes
@@ -368,3 +369,17 @@ def test_unusable_browser_session_error_tells_expiry_from_an_early_close(
error = unusable_browser_session_error(_ended_session(**overrides))
assert type(error) is expected
+
+
+def test_submission_refusal_emits_a_structured_countable_event() -> None:
+ with capture_logs() as logs:
+ error = unusable_browser_session_error(
+ _ended_session(), refused_at_submission=True, submission_path="workflow_run"
+ )
+
+ assert isinstance(error, BrowserSessionExpired)
+ assert len(logs) == 1
+ assert logs[0]["event"] == "browser_session_run_refused"
+ assert logs[0]["error_code"] == "browser_session_expired"
+ assert logs[0]["browser_session_id"] == "pbs_x"
+ assert logs[0]["submission_path"] == "workflow_run"
diff --git a/tests/unit/test_exception_messages.py b/tests/unit/test_exception_messages.py
index 5fc6eecd1..084c78aad 100644
--- a/tests/unit/test_exception_messages.py
+++ b/tests/unit/test_exception_messages.py
@@ -1,9 +1,12 @@
+import json
+from datetime import UTC, datetime
from http import HTTPStatus
import pytest
from skyvern.exceptions import (
BrowserSessionClosed,
+ BrowserSessionExpired,
BrowserSessionStartupTimeout,
CaptchaNotSolvedInTime,
CaptchaSolveError,
@@ -18,6 +21,7 @@ from skyvern.exceptions import (
require_local_extra_modules,
require_server_extra_modules,
)
+from skyvern.forge.api_app import handle_skyvern_http_exception
class FakePatchrightTimeoutError(Exception):
@@ -190,7 +194,10 @@ def test_browser_session_timeout_exceptions_distinguish_startup_from_expiry() ->
assert startup_timeout.status_code == 504
assert expired.status_code == 410
- assert str(startup_timeout) == "Browser session pbs_test failed to start within the timeout period."
+ assert str(startup_timeout) == (
+ "Browser session pbs_test failed to start within the timeout period. "
+ "Create a new browser session and retry with its id."
+ )
assert str(expired) == (
"Browser session pbs_test expired after reaching its configured lifetime. "
"Create a new browser session and retry."
@@ -203,6 +210,40 @@ def test_browser_session_closed_states_the_remedy_without_an_explicit_reason() -
)
+async def test_refused_run_carries_a_stable_error_code_a_caller_can_branch_on() -> None:
+ """A dispatcher re-sending a dead session id must be able to tell expiry from any other 410
+ without matching on prose, so these codes are a published contract."""
+ expired = BrowserSessionExpired(
+ "pbs_test",
+ started_at=datetime(2026, 10, 13, 1, 0, tzinfo=UTC),
+ ended_at=datetime(2026, 10, 13, 2, 0, tzinfo=UTC),
+ timeout_minutes=60,
+ created_by="api",
+ refused_at_submission=True,
+ )
+
+ response = await handle_skyvern_http_exception(None, expired) # type: ignore[arg-type]
+ body = json.loads(response.body)
+
+ assert response.status_code == 410
+ assert body["error_code"] == "browser_session_expired"
+ assert "expired" in body["detail"]
+ # The subclass must not inherit the base code, or expiry becomes indistinguishable from a
+ # session the caller closed itself.
+ assert BrowserSessionClosed("pbs_test").error_code == "browser_session_closed"
+ assert BrowserSessionStartupTimeout("pbs_test").error_code == "browser_session_startup_timeout"
+
+
+async def test_error_code_is_absent_from_responses_that_do_not_set_one() -> None:
+ response = await handle_skyvern_http_exception( # type: ignore[arg-type]
+ None, SkyvernHTTPException("bad request", status_code=HTTPStatus.BAD_REQUEST)
+ )
+
+ assert json.loads(response.body) == {"detail": "bad request"}
+
+
def test_raise_server_extra_required_translates_when_server_extra_missing(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setattr(
"skyvern.exceptions.find_spec",