Skip to content

Automate browser based workflows with AI

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.json
index 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.mdx
index 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. The
Sessions also close automatically when their timeout expires, **even if a task is still running**. Set timeouts with enough margin for your longest expected task.
<Warning>
-Closed sessions cannot be reopened. If you need the same login state later, create a [browser profile](/cloud/browser-management/browser-profiles) before closing.
+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.mdx
index 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 Python
import asyncio
@@ -238,7 +244,7 @@ from skyvern import Skyvern
async def main():
client = Skyvern(api_key="YOUR_API_KEY")
- # browser_session_id from a workflow run with persist_browser_session=true
+ # browser_session_id from a closed session created with generate_browser_profile enabled
session_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 enabled
const 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.mdx
index 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 session
Close 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.mdx
index 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.mdx
index 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.mdx
index 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.mdx
index 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.mdx
index 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 Python
result = 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.py
index 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(