Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
docs(SKY-10878): document opt-in browser profile generation for sessions (#6541)
Celal Zamanoğluc4d6ae37eee1
diff --git a/docs/api-reference/openapi.json b/docs/api-reference/openapi.jsonindex aea2cf7cd..c9259d8ca 100644--- a/docs/api-reference/openapi.json+++ b/docs/api-reference/openapi.json@@ -2731,7 +2731,8 @@"schema": {"$ref": "#/components/schemas/CreateBrowserSessionRequest","default": {- "timeout": 60+ "timeout": 60,+ "generate_browser_profile": false}}}@@ -2937,6 +2938,90 @@}},"/v1/browser_sessions/{browser_session_id}": {+ "patch": {+ "tags": [+ "Browser Sessions"+ ],+ "summary": "Update a session",+ "description": "Update a live browser session. Currently supports toggling generate_browser_profile, which is read when the session ends to decide whether to save its browser profile.",+ "operationId": "update_browser_session_v1_browser_sessions__browser_session_id__patch",+ "parameters": [+ {+ "name": "browser_session_id",+ "in": "path",+ "required": true,+ "schema": {+ "type": "string",+ "description": "The ID of the browser session. browser_session_id starts with `pbs_`",+ "examples": [+ "pbs_123456"+ ],+ "title": "Browser Session Id"+ },+ "description": "The ID of the browser session. browser_session_id starts with `pbs_`"+ },+ {+ "name": "x-api-key",+ "in": "header",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.",+ "title": "X-Api-Key"+ },+ "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings."+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/UpdateBrowserSessionRequest"+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully updated browser session",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/BrowserSessionResponse"+ }+ }+ }+ },+ "404": {+ "description": "Browser session not found"+ },+ "403": {+ "description": "Unauthorized - Invalid or missing authentication"+ },+ "409": {+ "description": "Conflict - browser session has already ended and can no longer be updated"+ },+ "422": {+ "description": "Validation Error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ }+ }+ },+ "x-fern-sdk-method-name": "update_browser_session"+ },"get": {"tags": ["Browser Sessions"@@ -7038,6 +7123,8 @@"complete","reload_page","close_page",+ "new_tab",+ "switch_tab","extract","verification_code","goto_url",@@ -7249,6 +7336,7 @@"type": "string","enum": ["recording",+ "audio","session_replay","browser_console_log","skyvern_log",@@ -8397,6 +8485,12 @@"title": "Browser Profile Id","description": "ID of the browser profile loaded into this session, if any. browser_profile_id starts with `bp_`."},+ "generate_browser_profile": {+ "type": "boolean",+ "title": "Generate Browser Profile",+ "description": "Whether this session's browser profile will be saved when it ends so it can become a reusable browser profile.",+ "default": false+ },"vnc_streaming_supported": {"type": "boolean","title": "Vnc Streaming Supported",@@ -9241,6 +9335,12 @@],"title": "Browser Profile Id","description": "ID of a browser profile to load into this session (restores cookies, localStorage, etc.). browser_profile_id starts with `bp_`."+ },+ "generate_browser_profile": {+ "type": "boolean",+ "title": "Generate Browser Profile",+ "description": "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.",+ "default": false}},"type": "object",@@ -9667,6 +9767,7 @@"enum": ["bitwarden","azure_vault",+ "gcp","custom"],"title": "CredentialVaultType"@@ -20196,6 +20297,20 @@"type": "object","title": "UpdateBrowserProfileRequest"},+ "UpdateBrowserSessionRequest": {+ "properties": {+ "generate_browser_profile": {+ "type": "boolean",+ "title": "Generate Browser Profile",+ "description": "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."+ }+ },+ "type": "object",+ "required": [+ "generate_browser_profile"+ ],+ "title": "UpdateBrowserSessionRequest"+ },"UpdateWorkflowFolderRequest": {"properties": {"folder_id": {diff --git a/docs/cloud/browser-management/browser-sessions.mdx b/docs/cloud/browser-management/browser-sessions.mdxindex 95bec6f99..5b72920e9 100644--- a/docs/cloud/browser-management/browser-sessions.mdx+++ b/docs/cloud/browser-management/browser-sessions.mdx@@ -128,7 +128,7 @@ From the session detail page, click **Stop**. A confirmation dialog appears. TheSessions also close automatically when their timeout expires, **even if a task is still running**. Set timeouts with enough margin for your longest expected task.<Warning>-Closed sessions cannot be reopened. If you need the same login state later, create a [browser profile](/cloud/browser-management/browser-profiles) before closing.+Closed sessions cannot be reopened, and a session only saves its browser state at close when profile generation is enabled for it. The **Save browser session** credential flow handles this automatically; for API-created sessions, see [Save a session's profile](/developers/optimization/browser-sessions#save-a-sessions-profile). If you need the same login state later, capture it as a [browser profile](/cloud/browser-management/browser-profiles) before closing.</Warning>---diff --git a/docs/developers/optimization/browser-profiles.mdx b/docs/developers/optimization/browser-profiles.mdxindex 9979c6f95..d30d7feb1 100644--- a/docs/developers/optimization/browser-profiles.mdx+++ b/docs/developers/optimization/browser-profiles.mdx@@ -26,6 +26,8 @@ Profiles are ideal when you:When an agent runs with `persist_browser_session=true`, Skyvern archives the browser state (cookies, storage, session files) after the run completes. This archiving happens asynchronously in the background. Once the archive is ready, you can create a profile from it, then pass that profile to future agent runs to restore the saved state.+For [browser sessions](/developers/optimization/browser-sessions), profile saving is opt-in: a session archives its state when it ends only if it has `generate_browser_profile` enabled or was started from a saved profile. See [Save a session's profile](/developers/optimization/browser-sessions#save-a-sessions-profile).+---## Create a Browser Profile@@ -224,12 +226,16 @@ done### From a browser session-You can also create a profile from a [Browser Session](/developers/optimization/browser-sessions) that was used inside an agent with `persist_browser_session=true`. After the agent run completes and the session is closed, pass the session ID instead of the workflow run ID.+You can also create a profile from a closed [Browser Session](/developers/optimization/browser-sessions) that was set to save its profile. Create the session with `generate_browser_profile` enabled (or [turn it on while the session is alive](/developers/optimization/browser-sessions#save-a-sessions-profile)), close the session, then pass the session ID instead of the workflow run ID.<Warning>-Only sessions that were part of an agent with `persist_browser_session=true` produce an archive. A session created with `create_browser_session()` alone does not archive its state. Archiving happens asynchronously after the session closes, so add retry logic.+Sessions do not save their profile by default. If the session did not have `generate_browser_profile` enabled and was not started from a saved profile, this call fails with a `400` error — retrying does not help. Update API scripts and integrations that create profiles from closed sessions; n8n users may need updated Skyvern nodes. Profiles created from workflow runs (`persist_browser_session=true`) are unaffected.</Warning>+<Note>+For opted-in sessions, the archive uploads asynchronously after the session closes, so keep brief retry logic for the transient "not persisted yet" window.+</Note>+<CodeGroup>```python Pythonimport asyncio@@ -238,7 +244,7 @@ from skyvern import Skyvernasync def main():client = Skyvern(api_key="YOUR_API_KEY")- # browser_session_id from a workflow run with persist_browser_session=true+ # browser_session_id from a closed session created with generate_browser_profile enabledsession_id = "pbs_your_session_id"# Create profile from the closed session (retry while archive uploads)@@ -266,7 +272,7 @@ import { Skyvern } from "@skyvern/client";async function main() {const client = new Skyvern({ apiKey: process.env.SKYVERN_API_KEY! });- // browser_session_id from a workflow run with persist_browser_session=true+ // browser_session_id from a closed session created with generate_browser_profile enabledconst sessionId = "pbs_your_session_id";// Create profile from the closed session (retry while archive uploads)@@ -295,8 +301,17 @@ main();``````bash cURL-# browser_session_id from a workflow run with persist_browser_session=true-SESSION_ID="pbs_your_session_id"+# Create a session that saves its profile when it ends+SESSION_ID=$(curl -s -X POST "https://api.skyvern.com/v1/browser_sessions" \+ -H "x-api-key: $SKYVERN_API_KEY" \+ -H "Content-Type: application/json" \+ -d '{"generate_browser_profile": true}' | jq -r '.browser_session_id')++# ... run your tasks against $SESSION_ID here ...++# Close the session so the profile uploads+curl -s -X POST "https://api.skyvern.com/v1/browser_sessions/$SESSION_ID/close" \+ -H "x-api-key: $SKYVERN_API_KEY"# Create profile (retry while session archives)for i in {1..10}; do@@ -322,7 +337,7 @@ done| Parameter | Type | Description ||-----------|------|-------------|| `name` | string | Required. Display name for the profile. Must be unique within your organization |-| `browser_session_id` | string | ID of the closed browser session (starts with `pbs_`). The session must have been part of an agent with `persist_browser_session=true` |+| `browser_session_id` | string | ID of the closed browser session (starts with `pbs_`). The session must have had `generate_browser_profile` enabled or been started from a saved profile || `description` | string | Optional description of the profile's purpose |---diff --git a/docs/developers/optimization/browser-sessions.mdx b/docs/developers/optimization/browser-sessions.mdxindex 4e0b6ac4b..19c8540f3 100644--- a/docs/developers/optimization/browser-sessions.mdx+++ b/docs/developers/optimization/browser-sessions.mdx@@ -86,6 +86,7 @@ curl -X POST "https://api.skyvern.com/v1/browser_sessions" \| `proxy_location` | string | Geographic proxy location (Cloud only). See [Proxy & Geolocation](/developers/going-to-production/proxy-geolocation) for available options || `browser_type` | string | Browser type: `chrome` or `msedge` || `extensions` | array | Extensions to install: `ad-blocker`, `captcha-solver` |+| `generate_browser_profile` | boolean | REST API only for now — not yet accepted by the SDK methods. Save the session's browser profile (cookies, localStorage, session files) when the session ends, so it can be turned into a reusable [browser profile](/developers/optimization/browser-profiles). Default: `false`. See [Save a session's profile](#save-a-sessions-profile) |**Example response:**@@ -367,6 +368,43 @@ You cannot use both `browser_session_id` and `browser_profile_id` in the same re---+## Save a session's profile++By default, a browser session does **not** save its browser profile when it ends. To capture the session's state (cookies, localStorage, session files) for reuse, opt in with `generate_browser_profile`. Python and TypeScript SDK support for this flag is rolling out; until your SDK version includes it, call the REST API directly (the Python SDK can also pass it via `request_options` with `additional_body_parameters={"generate_browser_profile": True}`).++```bash+curl -X POST "https://api.skyvern.com/v1/browser_sessions" \+ -H "x-api-key: $SKYVERN_API_KEY" \+ -H "Content-Type: application/json" \+ -d '{+ "timeout": 60,+ "generate_browser_profile": true+ }'+```++You can also toggle the flag on a live session. The value is read when the session ends, so the update takes effect as long as the session is still open. Updating a session that has already closed returns a `409` error.++```bash+curl -X PATCH "https://api.skyvern.com/v1/browser_sessions/pbs_abc123" \+ -H "x-api-key: $SKYVERN_API_KEY" \+ -H "Content-Type: application/json" \+ -d '{"generate_browser_profile": true}'+```++To confirm the setting on an existing session, fetch it with `GET /v1/browser_sessions/{browser_session_id}` — the response includes `generate_browser_profile`.++Once the session closes and its profile finishes uploading, turn it into a reusable profile with [`create_browser_profile`](/developers/optimization/browser-profiles#from-a-browser-session).++<Note>+Sessions started from a saved profile (`browser_profile_id`) always save their profile when they end, regardless of this flag. This does not update the original profile — to keep the refreshed login state, create a new profile from the closed session and use the new profile's ID in future runs.+</Note>++<Warning>+**Behavior change:** sessions previously saved their profile automatically. Creating a browser profile from a closed session now fails with a `400` error unless the session had `generate_browser_profile` enabled or was started from a profile — retrying does not help. Update API scripts and integrations that create profiles from closed sessions; n8n users may need updated Skyvern nodes. Creating profiles from workflow runs (`persist_browser_session`) is unaffected.+</Warning>++---+## Close a sessionClose a session to release resources and stop billing. The browser shuts down immediately.@@ -694,7 +732,7 @@ Skyvern also offers [Browser Profiles](/developers/optimization/browser-profiles| **Best for** | Back-to-back tasks, human-in-the-loop, real-time agents | Repeated logins, scheduled agents, shared auth state |<Tip>-You can create a [Browser Profile](/developers/optimization/browser-profiles) from a completed session to save its authenticated state for future reuse.+You can create a [Browser Profile](/developers/optimization/browser-profiles) from a completed session to save its authenticated state for future reuse. The session must have [`generate_browser_profile` enabled](#save-a-sessions-profile) or have been started from a profile.</Tip>---diff --git a/docs/sdk-reference/browser-profiles/create-browser-profile.mdx b/docs/sdk-reference/browser-profiles/create-browser-profile.mdxindex 01b686647..7409059ca 100644--- a/docs/sdk-reference/browser-profiles/create-browser-profile.mdx+++ b/docs/sdk-reference/browser-profiles/create-browser-profile.mdx@@ -19,7 +19,7 @@ profile = await client.create_browser_profile(name="production-login",workflow_run_id="wr_abc123",)-print(profile.browser_profile_id) # bpf_abc123+print(profile.browser_profile_id) # bp_abc123``````typescript TypeScript@@ -27,7 +27,7 @@ const profile = await skyvern.createBrowserProfile({name: "production-login",workflow_run_id: "wr_abc123",});-console.log(profile.browser_profile_id); // bpf_abc123+console.log(profile.browser_profile_id); // bp_abc123```</CodeGroup>@@ -38,7 +38,7 @@ console.log(profile.browser_profile_id); // bpf_abc123| `name` | `str` | Yes | Display name for the profile. || `description` | `str` | No | Optional description. || `workflow_run_id` | `str` | Conditional | The workflow run ID to snapshot. The run must have used `persist_browser_session=True`. Required if `browser_session_id` is not provided. |-| `browser_session_id` | `str` | Conditional | The browser session ID to snapshot. Required if `workflow_run_id` is not provided. |+| `browser_session_id` | `str` | Conditional | The browser session ID to snapshot. The session must have had `generate_browser_profile` enabled or been started from a saved profile. Required if `workflow_run_id` is not provided. || `request_options` | `RequestOptions` | No | Per-request configuration (see below). |You must provide either `workflow_run_id` or `browser_session_id`.@@ -47,7 +47,7 @@ You must provide either `workflow_run_id` or `browser_session_id`.| Field | Type | Description ||-------|------|-------------|-| `browser_profile_id` | `str` | Unique ID. Starts with `bpf_`. |+| `browser_profile_id` | `str` | Unique ID. Starts with `bp_`. || `name` | `str` | Profile name. || `description` | `str \| None` | Profile description. || `created_at` | `datetime` | When the profile was created. |@@ -105,7 +105,7 @@ const result = await skyvern.runWorkflow({</CodeGroup><Info>-Session archiving is asynchronous. If `create_browser_profile` fails immediately after a workflow completes, wait a few seconds and retry.+Session archiving is asynchronous. If `create_browser_profile` fails immediately after a run or session ends, wait a few seconds and retry. A `400` error saying the session was not configured to generate a browser profile is permanent — recreate the session with `generate_browser_profile` enabled. See [Save a session's profile](/developers/optimization/browser-sessions#save-a-sessions-profile).</Info>---diff --git a/docs/sdk-reference/browser-profiles/delete-browser-profile.mdx b/docs/sdk-reference/browser-profiles/delete-browser-profile.mdxindex e916f71ba..74a63836a 100644--- a/docs/sdk-reference/browser-profiles/delete-browser-profile.mdx+++ b/docs/sdk-reference/browser-profiles/delete-browser-profile.mdx@@ -7,11 +7,11 @@ Delete a browser profile.<CodeGroup>```python Python-await client.delete_browser_profile("bpf_abc123")+await client.delete_browser_profile("bp_abc123")``````typescript TypeScript-await skyvern.deleteBrowserProfile("bpf_abc123");+await skyvern.deleteBrowserProfile("bp_abc123");```</CodeGroup>diff --git a/docs/sdk-reference/browser-profiles/get-browser-profile.mdx b/docs/sdk-reference/browser-profiles/get-browser-profile.mdxindex 48abd3ac8..3f4f80427 100644--- a/docs/sdk-reference/browser-profiles/get-browser-profile.mdx+++ b/docs/sdk-reference/browser-profiles/get-browser-profile.mdx@@ -7,12 +7,12 @@ Get a single profile by ID.<CodeGroup>```python Python-profile = await client.get_browser_profile("bpf_abc123")+profile = await client.get_browser_profile("bp_abc123")print(profile.name)``````typescript TypeScript-const profile = await skyvern.getBrowserProfile("bpf_abc123");+const profile = await skyvern.getBrowserProfile("bp_abc123");console.log(profile.name);```</CodeGroup>diff --git a/docs/sdk-reference/browser-sessions/create-browser-session.mdx b/docs/sdk-reference/browser-sessions/create-browser-session.mdxindex eeafd5c73..0b53393a1 100644--- a/docs/sdk-reference/browser-sessions/create-browser-session.mdx+++ b/docs/sdk-reference/browser-sessions/create-browser-session.mdx@@ -33,9 +33,14 @@ console.log(session.browser_session_id); // pbs_abc123| `proxy_location` | `ProxyLocation` | No | `None` | Route browser traffic through a geographic proxy. || `extensions` | `list[Extensions]` | No | `None` | Browser extensions to install. Options: `"ad-blocker"`, `"captcha-solver"`. || `browser_type` | `PersistentBrowserType` | No | `None` | Browser type. Options: `"chrome"`, `"msedge"`. |-| `browser_profile_id` | `str` | No | `None` | Load a browser profile (cookies, localStorage) into this session. ID starts with `bpf_`. |+| `browser_profile_id` | `str` | No | `None` | Load a browser profile (cookies, localStorage) into this session. ID starts with `bp_`. |+| `generate_browser_profile` | `bool` | No | `False` | REST API only for now — not yet accepted by the SDK methods (see note below). Save the session's browser profile when it ends so it can be turned into a reusable [browser profile](/sdk-reference/browser-profiles/create-browser-profile). Sessions started with `browser_profile_id` always save theirs. || `request_options` | `RequestOptions` | No | | Per-request configuration (see below). |+<Note>+`generate_browser_profile` is not yet accepted as a keyword by the SDK methods (watch the [changelog](/changelog) for SDK availability). Until SDK support lands, pass it from Python via `request_options` with `additional_body_parameters={"generate_browser_profile": True}` (see [Request options](#request-options) below); from TypeScript, call the REST API directly. You can also toggle it on a live session via `PATCH /v1/browser_sessions/{browser_session_id}` — the value is read when the session ends. See [Save a session's profile](/developers/optimization/browser-sessions#save-a-sessions-profile).+</Note>+### Returns `BrowserSessionResponse`| Field | Type | Description |diff --git a/docs/sdk-reference/workflows/run-workflow.mdx b/docs/sdk-reference/workflows/run-workflow.mdxindex 989488f78..39aca780c 100644--- a/docs/sdk-reference/workflows/run-workflow.mdx+++ b/docs/sdk-reference/workflows/run-workflow.mdx@@ -121,7 +121,7 @@ result = await client.run_workflow(```python Pythonresult = await client.run_workflow(workflow_id="wpid_daily_report",- browser_profile_id="bpf_abc123",+ browser_profile_id="bp_abc123",wait_for_completion=True,)```@@ -130,7 +130,7 @@ result = await client.run_workflow(const result = await skyvern.runWorkflow({body: {workflow_id: "wpid_daily_report",- browser_profile_id: "bpf_abc123",+ browser_profile_id: "bp_abc123",},waitForCompletion: true,});diff --git a/skyvern/forge/sdk/routes/browser_sessions.py b/skyvern/forge/sdk/routes/browser_sessions.pyindex 2ebf14825..3229c6947 100644--- a/skyvern/forge/sdk/routes/browser_sessions.py+++ b/skyvern/forge/sdk/routes/browser_sessions.py@@ -173,6 +173,7 @@ async def close_browser_session(200: {"description": "Successfully updated browser session"},404: {"description": "Browser session not found"},403: {"description": "Unauthorized - Invalid or missing authentication"},+ 409: {"description": "Conflict - browser session has already ended and can no longer be updated"},},)@base_router.patch(