Skip to main content
POST
/
v1
/
browser_sessions
Create a session
curl --request POST \
  --url https://api.skyvern.com/v1/browser_sessions \
  --header 'Content-Type: application/json' \
  --data '
{
  "timeout": 60,
  "generate_browser_profile": false
}
'
{
  "browser_session_id": "<string>",
  "organization_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "modified_at": "2023-11-07T05:31:56Z",
  "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",
  "extensions": [],
  "browser_profile_id": "<string>",
  "generate_browser_profile": false,
  "vnc_streaming_supported": false,
  "download_path": "<string>",
  "downloaded_files": [
    {
      "url": "<string>",
      "checksum": "<string>",
      "filename": "<string>",
      "file_size": 123,
      "modified_at": "2023-11-07T05:31:56Z",
      "artifact_id": "<string>"
    }
  ],
  "recordings": [
    {
      "url": "<string>",
      "checksum": "<string>",
      "filename": "<string>",
      "file_size": 123,
      "modified_at": "2023-11-07T05:31:56Z",
      "artifact_id": "<string>"
    }
  ],
  "started_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "deleted_at": "2023-11-07T05:31:56Z"
}

Headers

​
x-api-key
string | null

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

Body

application/json
​
timeout
integer | null
default:60

Timeout in minutes for the session. Timeout is applied after the session is started. Must be between 5 and 1440. Defaults to 60.

Required range: 5 <= x <= 1440
​
proxy_location

Geographic Proxy location to route the browser traffic through. This is only available in Skyvern Cloud.

Available geotargeting options:

  • RESIDENTIAL: the default value. Skyvern Cloud uses a random US residential proxy.
  • RESIDENTIAL_ES: Spain
  • RESIDENTIAL_IE: Ireland
  • RESIDENTIAL_GB: United Kingdom
  • RESIDENTIAL_IN: India
  • RESIDENTIAL_JP: Japan
  • RESIDENTIAL_FR: France
  • RESIDENTIAL_DE: Germany
  • RESIDENTIAL_NZ: New Zealand
  • RESIDENTIAL_PH: Philippines
  • RESIDENTIAL_KR: South Korea
  • RESIDENTIAL_SA: Saudi Arabia
  • RESIDENTIAL_ZA: South Africa
  • RESIDENTIAL_AR: Argentina
  • RESIDENTIAL_AU: Australia
  • RESIDENTIAL_BR: Brazil
  • RESIDENTIAL_TR: Turkey
  • RESIDENTIAL_CA: Canada
  • RESIDENTIAL_MX: Mexico
  • RESIDENTIAL_IT: Italy
  • RESIDENTIAL_NL: Netherlands
  • RESIDENTIAL_ISP: ISP proxy
  • US-CA: California (deprecated, routes through RESIDENTIAL_ISP)
  • US-NY: New York (deprecated, routes through RESIDENTIAL_ISP)
  • US-TX: Texas (deprecated, routes through RESIDENTIAL_ISP)
  • US-FL: Florida (deprecated, routes through RESIDENTIAL_ISP)
  • US-WA: Washington (deprecated, routes through RESIDENTIAL_ISP)
  • NONE: No proxy

For self-hosted deployments, you can pass a custom proxy URL as a dict: {"url": "http://user:password@proxy.example.com:8080"} [blocked]. This routes the browser through your own proxy server and takes precedence over any globally configured proxy pool. Can also be a GeoTarget object for granular city/state targeting: {"country": "US", "subdivision": "CA", "city": "San Francisco"}, or a custom proxy URL dict for self-hosted deployments: {"url": "http://user:password@proxy.example.com:8080"} [blocked]

Available options:
RESIDENTIAL,
US-CA,
US-NY,
US-TX,
US-FL,
US-WA,
RESIDENTIAL_ES,
RESIDENTIAL_IE,
RESIDENTIAL_GB,
RESIDENTIAL_IN,
RESIDENTIAL_JP,
RESIDENTIAL_FR,
RESIDENTIAL_DE,
RESIDENTIAL_NZ,
RESIDENTIAL_ZA,
RESIDENTIAL_AR,
RESIDENTIAL_AU,
RESIDENTIAL_BR,
RESIDENTIAL_TR,
RESIDENTIAL_CA,
RESIDENTIAL_MX,
RESIDENTIAL_IT,
RESIDENTIAL_NL,
RESIDENTIAL_PH,
RESIDENTIAL_KR,
RESIDENTIAL_SA,
RESIDENTIAL_ISP,
NONE
​
proxy_session_id
string | null

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

​
extensions
enum<string>[] | null

A list of extensions to install in the browser session.

Available options:
ad-blocker,
captcha-solver
​
browser_type
enum<string> | null

The type of browser to use for the session.

Available options:
msedge,
chrome,
stealth-chromium
​
browser_profile_id
string | null

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

Pattern: ^bp_
​
generate_browser_profile
boolean
default:false

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.

Response

Successfully created browser session

Response model for browser session information.

​
browser_session_id
string
required

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

Example:

"pbs_123456"

​
organization_id
string
required

ID of the organization that owns this session

​
created_at
string<date-time>
required

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

​
modified_at
string<date-time>
required

Timestamp when the session was last modified

​
status
string | null

Current status of the browser session

Example:

"created"

​
runnable_type
string | null

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

Example:

"task"

​
runnable_id
string | null

ID of the current runnable

Example:

"tsk_123456"

​
timeout
integer | null

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

Example:

60

​
browser_address
string | null

Url for connecting to the browser

Example:

"http://localhost:9222"

​
app_url
string | null

Url for the browser session page

Example:

"https://app.skyvern.com/browser-session/pbs_123456"

​
extensions
enum<string>[] | null

A list of extensions installed in the browser session.

Available options:
ad-blocker,
captcha-solver
​
browser_type
enum<string> | null

The type of browser used for the session.

Available options:
msedge,
chrome,
stealth-chromium
​
browser_profile_id
string | null

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

​
generate_browser_profile
boolean
default:false

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

​
vnc_streaming_supported
boolean
default:false

Whether the browser session supports VNC streaming

​
download_path
string | null

The path where the browser session downloads files

​
downloaded_files
FileInfo · object[] | null

The list of files downloaded by the browser session

​
recordings
FileInfo · object[] | null

The list of video recordings from the browser session

​
started_at
string<date-time> | null

Timestamp when the session was started

​
completed_at
string<date-time> | null

Timestamp when the session was completed

​
deleted_at
string<date-time> | null

Timestamp when the session was deleted, if applicable