Sign in

v60

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-0283227863.6 KB
Browser Sessions

Create a session

Create a browser session that persists across multiple runs

post/v1/browser_sessions

Headers

x-api-keystring nullable

Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.

Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.

Request body

urlstring nullable

Optional URL to open when the standalone browser session starts.

timeoutinteger nullable

Timeout in minutes for the session. Timeout is applied after the session is started. Must be at least 5; values above 240 are capped at 240. Defaults to 60.

proxy_session_idstring nullable

Opaque Skyvern-managed proxy sticky-session id for pinned Residential ISP sessions.

extensionsExtensions[] nullable

A list of extensions to install in the browser session.

browser_type'msedge' | 'chrome' | 'stealth-chromium'
browser_profile_idstring nullable

ID of a browser profile to load into this session (restores cookies, localStorage, etc.). browser_profile_id starts with bp_.

generate_browser_profileboolean

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.

Example request

{
  "proxy_location": {
    "country": "US",
    "subdivision": "CA",
    "city": "New York"
  }
}

Response

Successfully created browser session

browser_session_idstring required

Unique identifier for the browser session. browser_session_id starts with pbs_.

organization_idstring required

ID of the organization that owns this session

statusstring nullable

Current status of the browser session

runnable_typestring nullable

Type of the current runnable associated with this session (workflow, task etc)

runnable_idstring nullable

ID of the current runnable

timeoutinteger nullable

Timeout in minutes for the session. Timeout is applied after the session is started. Defaults to 60 minutes.

browser_addressstring nullable

Url for connecting to the browser

app_urlstring nullable

Url for the browser session page

extensionsExtensions[] nullable

A list of extensions installed in the browser session.

browser_type'msedge' | 'chrome' | 'stealth-chromium'
browser_profile_idstring nullable

ID of the browser profile loaded into this session, if any. browser_profile_id starts with bp_.

generate_browser_profileboolean

Whether this session's browser profile will be saved when it ends so it can become a reusable browser profile.

vnc_streaming_supportedboolean

Whether the browser session supports VNC streaming

download_pathstring nullable

The path where the browser session downloads files

started_atstring date-time nullable

Timestamp when the session was started

completed_atstring date-time nullable

Timestamp when the session was completed

created_atstring date-time required

Timestamp when the session was created (the timestamp for the initial request)

modified_atstring date-time required

Timestamp when the session was last modified

deleted_atstring date-time nullable

Timestamp when the session was deleted, if applicable

Example response

{
  "browser_session_id": "pbs_123456",
  "status": "created",
  "runnable_type": "task",
  "runnable_id": "tsk_123456",
  "timeout": 60,
  "browser_address": "http://localhost:9222",
  "app_url": "https://app.skyvern.com/browser-session/pbs_123456"
}