---
title: "Create a session"
method: POST
path: "/v1/browser_sessions"
tags: ["Browser Sessions"]
---

# Create a session

`POST /v1/browser_sessions`

Create a browser session that persists across multiple runs

## Headers

- `x-api-key` string, nullable — Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.

## Request body

- CreateBrowserSessionRequest
  - `url` string, nullable — Optional URL to open when the standalone browser session starts.
  - `timeout` integer, 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_location` union — 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"}. 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"}
    - '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'
    - GeoTarget — Granular proxy geo-targeting request with country, optional subdivision, and optional city.
      - `country` string, required — ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'DE')
      - `subdivision` string, nullable — ISO 3166-2 subdivision code without country prefix (e.g., 'CA' for California, 'NY' for New York)
      - `city` string, nullable — City name in English from GeoNames (e.g., 'New York', 'Los Angeles', 'London')
    - object
  - `proxy_session_id` string, nullable — Opaque Skyvern-managed proxy sticky-session id for pinned Residential ISP sessions.
  - `extensions` Extensions[], nullable — A list of extensions to install in the browser session.
  - `browser_type` 'msedge' | 'chrome' | 'stealth-chromium'
  - `browser_profile_id` string, nullable — ID of a browser profile to load into this session (restores cookies, localStorage, etc.). browser_profile_id starts with `bp_`.
  - `generate_browser_profile` boolean — 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_view` boolean — 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.

## Response `200`

Successfully created browser session

- BrowserSessionResponse — Response model for browser session information.
  - `browser_session_id` string, required — Unique identifier for the browser session. browser_session_id starts with `pbs_`.
  - `organization_id` string, required — ID of the organization that owns this session
  - `status` string, nullable — Current status of the browser session
  - `runnable_type` string, nullable — Type of the current runnable associated with this session (workflow, task etc)
  - `runnable_id` string, nullable — ID of the current runnable
  - `timeout` integer, nullable — Timeout in minutes for the session. Timeout is applied after the session is started. Defaults to 60 minutes.
  - `browser_address` string, nullable — Url for connecting to the browser
  - `app_url` string, nullable — Url for the browser session page
  - `extensions` Extensions[], nullable — A list of extensions installed in the browser session.
  - `browser_type` 'msedge' | 'chrome' | 'stealth-chromium'
  - `browser_profile_id` string, nullable — ID of the browser profile loaded into this session, if any. browser_profile_id starts with `bp_`.
  - `generate_browser_profile` boolean — Whether this session's browser profile will be saved when it ends so it can become a reusable browser profile.
  - `vnc_streaming_supported` boolean — Whether the browser session supports VNC streaming
  - `stream_transport` string, nullable — Live-view transport for this session: "vnc" or "cdp". Resolved on the single-session fetch only; null elsewhere.
  - `download_path` string, nullable — The path where the browser session downloads files
  - `downloaded_files` FileInfo[], nullable — The list of files downloaded by the browser session
    - `url` string, required — URL to access the file
    - `checksum` string, nullable — SHA-256 checksum of the file
    - `filename` string, nullable — Original filename
    - `file_size` integer, nullable — Size of the file in bytes
    - `modified_at` string, date-time, nullable — Modified time of the file
    - `artifact_id` string, nullable — Artifact row id for refresh-on-read
  - `recordings` FileInfo[], nullable — The list of video recordings from the browser session
    - `url` string, required — URL to access the file
    - `checksum` string, nullable — SHA-256 checksum of the file
    - `filename` string, nullable — Original filename
    - `file_size` integer, nullable — Size of the file in bytes
    - `modified_at` string, date-time, nullable — Modified time of the file
    - `artifact_id` string, nullable — Artifact row id for refresh-on-read
  - `started_at` string, date-time, nullable — Timestamp when the session was started
  - `completed_at` string, date-time, nullable — Timestamp when the session was completed
  - `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
  - `deleted_at` string, date-time, nullable — Timestamp when the session was deleted, if applicable

## Other responses

- `403` — Unauthorized - Invalid or missing authentication
- `404` — Browser profile not found
- `422` — Validation Error

---

[API](https://skmtc.net/skyvern-ai/apis/skyvern-api-2.md) · [All operations](https://skmtc.net/skyvern-ai/apis/skyvern-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/skyvern-ai/skyvern-api-2/versions/5116249dfff3/schema)