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.

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 between 5 and 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.

needs_live_viewboolean

Whether a person will watch this session's browser live. Defaults to false, which suits unattended automation; the Skyvern app sets it because a session opened in the UI is watched. It requests a capability, not a particular browser, and cannot be used to select where the session runs.

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

stream_transportstring nullable

Live-view transport for this session: "vnc" or "cdp". Resolved on the single-session fetch only; null elsewhere.

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

warningstring nullable

Advisory message about how the request was adjusted, if it was. Set when a requested timeout above the maximum was capped; null otherwise.

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",
  "stream_transport": "vnc"
}

Changes

Changed in 11 of the 86 revisions of this API.48126

Aug 20, 2026701729837d271See the full diff
- ○
  added the optional property to the response with the status
  response-optional-property-added
Aug 19, 2026938b4f1245501See the full diff
- ○
  added the non-success response with the status
  response-non-success-status-added
Aug 7, 20269585bc129aaf1See the full diff
- ○
  added the optional property to the response with the status
  response-optional-property-added
Aug 2, 2026f15b01f742d32See the full diff
- ○
  added the new optional request property
  new-optional-request-property
- ○
  the request body application/json default value changed from {"timeout":60,"generate_browser_profile":false} to {"timeout":60,"generate_browser_profile":false,"needs_live_view":false}
  request-body-default-value-changed
Aug 2, 20266d9eef3774fe1See the full diff
- ○
  added the new optional request property
  new-optional-request-property
Jul 30, 20264f040669f1511See the full diff
- ●
  removed the request property
  request-property-removed
Jul 29, 202641e65a8c4f591See the full diff
- ○
  added the new optional request property
  new-optional-request-property
Jun 26, 20269de266eb002a1See the full diff
- ○
  added the new optional request property
  new-optional-request-property
Jun 12, 20267ce5e3e9a5603See the full diff
- ○
  added the new optional request property
  new-optional-request-property
- ○
  the request body application/json default value changed from {"timeout":60} to {"timeout":60,"generate_browser_profile":false}
  request-body-default-value-changed
- ○
  added the optional property to the response with the status
  response-optional-property-added
Jun 8, 20263a3616091b664814See the full diff
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  removed the enum value NONE of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value RESIDENTIAL of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value RESIDENTIAL_AR of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value RESIDENTIAL_AU of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value RESIDENTIAL_BR of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value RESIDENTIAL_CA of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value RESIDENTIAL_DE of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value RESIDENTIAL_ES of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value RESIDENTIAL_FR of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value RESIDENTIAL_GB of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value RESIDENTIAL_IE of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value RESIDENTIAL_IN of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value RESIDENTIAL_ISP of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value RESIDENTIAL_IT of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value RESIDENTIAL_JP of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value RESIDENTIAL_MX of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value RESIDENTIAL_NL of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value RESIDENTIAL_NZ of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value RESIDENTIAL_PH of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value RESIDENTIAL_TR of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value RESIDENTIAL_ZA of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value US-CA of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value US-FL of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value US-NY of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value US-TX of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value US-WA of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value chrome of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value msedge of the request property
  request-property-enum-value-removed
- ▲
  the request property type changed from string to no type
  request-property-type-changed
- ▲
  the request property type changed from string to no type
  request-property-type-changed
- ▲
  response property app_url list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property browser_address list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property completed_at list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property deleted_at list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property download_path list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property downloaded_files list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property extensions list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property recordings list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property runnable_id list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property runnable_type list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property started_at list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property status list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property timeout list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  the response's property type changed from string to no type for status
  response-property-type-changed
- ○
  added the new optional request property
  new-optional-request-property
- ○
  header request parameter x-api-key list-of-types was widened by adding types null
  request-parameter-list-of-types-widened
- ○
  for the header request parameter x-api-key, the type was generalized from string to no type
  request-parameter-type-generalized
- ○
  added subschema #2 to the request property anyOf list
  request-property-any-of-added
- ○
  added subschema #3 subschema #4 to the request property anyOf list
  request-property-any-of-added
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  added the non-success response with the status
  response-non-success-status-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added subschema #2 to the response property anyOf list for the response status
  response-property-any-of-added
- ○
  removed the chrome enum value from the response property for the response status
  response-property-enum-value-removed
- ○
  removed the msedge enum value from the response property for the response status
  response-property-enum-value-removed
This revision also has 10 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history (11 revisions)