Skyvern: Browser sessions schemas

6 Skyvern schemas with complete fields and constraints.

← Browser sessions operations · All schemas

Create a session — request body — body

Field	Type	Presence	Description and constraints
`$`	object	Root
`browser_profile_id`	JSON	Optional	ID of a browser profile to load into this session (restores cookies, localStorage, etc.). browser_profile_id starts with `bp_`.
`browser_profile_id (anyOf 1)`	string	Alternative	Pattern: ^bp_
`browser_profile_id (anyOf 2)`	null	Alternative
`browser_settings`	JSON	Optional	Settings applied when the session's browser is created. A timezone_id here takes precedence over the timezone implied by proxy_location.
`browser_settings (anyOf 1)`	Model	Alternative	Expand Get a session — response body — browser settings timezone id
`browser_settings (anyOf 2)`	null	Alternative
`browser_type`	JSON	Optional	The type of browser to use for the session.
`browser_type (anyOf 1)`	string	Alternative	One of: msedge, chrome, stealth-chromium
`browser_type (anyOf 2)`	null	Alternative
`extensions`	JSON	Optional	A list of extensions to install in the browser session.
`extensions (anyOf 1)`	array	Alternative
`extensions (anyOf 1)[]`	string	Each item	One of: ad-blocker, captcha-solver
`extensions (anyOf 2)`	null	Alternative
`generate_browser_profile`	boolean	Optional	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
`needs_live_view`	boolean	Optional	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. Default: false
`proxy_location`	JSON	Optional	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: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:8080"}
`proxy_location (anyOf 1)`	string	Alternative	One of: 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_location (anyOf 2)`	Model	Alternative	Expand Update an agent — response body — proxy location city, country, is ISP, subdivision
`proxy_location (anyOf 3)`	object	Alternative	Additional keys: allowed
`proxy_location (anyOf 4)`	null	Alternative
`proxy_session_id`	JSON	Optional	Opaque Skyvern-managed proxy sticky-session id for pinned Residential ISP sessions.
`proxy_session_id (anyOf 1)`	string	Alternative
`proxy_session_id (anyOf 2)`	null	Alternative
`timeout`	JSON	Optional	Timeout in minutes for the session. Timeout is applied after the session is started. Must be between 5 and 240. Defaults to 60. Default: 60
`timeout (anyOf 1)`	integer	Alternative	Minimum: 5.0
`timeout (anyOf 2)`	null	Alternative
`url`	JSON	Optional	Optional URL to open when the standalone browser session starts.
`url (anyOf 1)`	string	Alternative
`url (anyOf 2)`	null	Alternative

Referenced models: Get a session — response body — browser settings timezone id, Update an agent — response body — proxy location city, country, is ISP, subdivision

Extend a session — request body — body

Field	Type	Presence	Description and constraints
`$`	object	Root
`additional_minutes`	integer	Required within parent	Minutes to add to the session's current deadline. A session can be extended, one or more times, up to a total lifetime of 360 minutes (6 hours) counted from when it started; a request for more than the remaining headroom is granted the remainder and the response carries a warning. Minimum: 1.0

Get a session — response body

Field	Type	Presence	Description and constraints
`$`	object	Root	Response model for browser session information.
`app_url`	JSON	Optional	Url for the browser session page
`app_url (anyOf 1)`	string	Alternative
`app_url (anyOf 2)`	null	Alternative
`browser_address`	JSON	Optional	Url for connecting to the browser
`browser_address (anyOf 1)`	string	Alternative
`browser_address (anyOf 2)`	null	Alternative
`browser_profile_id`	JSON	Optional	ID of the browser profile loaded into this session, if any. browser_profile_id starts with `bp_`.
`browser_profile_id (anyOf 1)`	string	Alternative
`browser_profile_id (anyOf 2)`	null	Alternative
`browser_session_id`	string	Required within parent	Unique identifier for the browser session. browser_session_id starts with `pbs_`.
`browser_settings`	JSON	Optional	Browser settings requested when the session was created.
`browser_settings (anyOf 1)`	Model	Alternative	Expand Get a session — response body — browser settings timezone id
`browser_settings (anyOf 2)`	null	Alternative
`browser_settings_receipt`	JSON	Optional	What the browser reported after launch for the requested settings. Null until it is measured, and always null when no settings were requested.
`browser_settings_receipt (anyOf 1)`	Model	Alternative	Expand Login Task — response body — browser_settings_receipt / source: workflow version, session request, existing session, status: verified, mismatch, unapplied, unknown
`browser_settings_receipt (anyOf 2)`	null	Alternative
`browser_type`	JSON	Optional	The type of browser used for the session.
`browser_type (anyOf 1)`	string	Alternative	Known values: msedge, chrome, stealth-chromium
`browser_type (anyOf 2)`	null	Alternative
`completed_at`	JSON	Optional	Timestamp when the session was completed
`completed_at (anyOf 1)`	string	Alternative	Format: date-time
`completed_at (anyOf 2)`	null	Alternative
`created_at`	string	Required within parent	Timestamp when the session was created (the timestamp for the initial request) Format: date-time
`created_by`	JSON	Optional	ID of the user who created the session
`created_by (anyOf 1)`	string	Alternative
`created_by (anyOf 2)`	null	Alternative
`deleted_at`	JSON	Optional	Timestamp when the session was deleted, if applicable
`deleted_at (anyOf 1)`	string	Alternative	Format: date-time
`deleted_at (anyOf 2)`	null	Alternative
`download_path`	JSON	Optional	The path where the browser session downloads files
`download_path (anyOf 1)`	string	Alternative
`download_path (anyOf 2)`	null	Alternative
`downloaded_files`	JSON	Optional	The list of files downloaded by the browser session
`downloaded_files (anyOf 1)`	array	Alternative
`downloaded_files (anyOf 1)[]`	Model	Each item	Expand Get a session — response body — recordings array item
`downloaded_files (anyOf 2)`	null	Alternative
`extensions`	JSON	Optional	A list of extensions installed in the browser session.
`extensions (anyOf 1)`	array	Alternative
`extensions (anyOf 1)[]`	string	Each item	Known values: ad-blocker, captcha-solver
`extensions (anyOf 2)`	null	Alternative
`generate_browser_profile`	boolean	Optional	Whether this session's browser profile will be saved when it ends so it can become a reusable browser profile. Default: false
`modified_at`	string	Required within parent	Timestamp when the session was last modified Format: date-time
`organization_id`	string	Required within parent	ID of the organization that owns this session
`recordings`	JSON	Optional	The list of video recordings from the browser session
`recordings (anyOf 1)`	array	Alternative
`recordings (anyOf 1)[]`	Model	Each item	Expand Get a session — response body — recordings array item
`recordings (anyOf 2)`	null	Alternative
`remaining_lifetime_seconds`	JSON	Optional	Seconds left before a registered external browser's fixed deadline. Null for managed sessions and once the session has ended.
`remaining_lifetime_seconds (anyOf 1)`	JSON	Alternative
`remaining_lifetime_seconds (anyOf 1) (anyOf 1)`	integer	Alternative
`remaining_lifetime_seconds (anyOf 1) (anyOf 2)`	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
`remaining_lifetime_seconds (anyOf 2)`	null	Alternative
`runnable_id`	JSON	Optional	ID of the current runnable
`runnable_id (anyOf 1)`	string	Alternative
`runnable_id (anyOf 2)`	null	Alternative
`runnable_type`	JSON	Optional	Type of the current runnable associated with this session (workflow, task etc)
`runnable_type (anyOf 1)`	string	Alternative
`runnable_type (anyOf 2)`	null	Alternative
`source`	string	Optional	"external" for a browser the caller registered and runs itself; "managed" for one Skyvern runs. Known values: managed, external Default: managed
`started_at`	JSON	Optional	Timestamp when the session was started
`started_at (anyOf 1)`	string	Alternative	Format: date-time
`started_at (anyOf 2)`	null	Alternative
`status`	JSON	Optional	Current status of the browser session
`status (anyOf 1)`	string	Alternative
`status (anyOf 2)`	null	Alternative
`stream_transport`	JSON	Optional	Live-view transport for this session: "vnc" or "cdp". Resolved on the single-session fetch only; null elsewhere.
`stream_transport (anyOf 1)`	string	Alternative
`stream_transport (anyOf 2)`	null	Alternative
`timeout`	JSON	Optional	Timeout in minutes for the session. Timeout is applied after the session is started. Defaults to 60 minutes.
`timeout (anyOf 1)`	JSON	Alternative
`timeout (anyOf 1) (anyOf 1)`	integer	Alternative
`timeout (anyOf 1) (anyOf 2)`	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
`timeout (anyOf 2)`	null	Alternative
`vnc_streaming_supported`	boolean	Optional	Whether the browser session supports VNC streaming Default: false
`warning`	JSON	Optional	Advisory message about how the request was adjusted, if it was. Set when a requested timeout above the maximum was capped at creation, when an extension was granted less than it asked for, or when an extension was accepted but not yet confirmed; null otherwise.
`warning (anyOf 1)`	string	Alternative
`warning (anyOf 2)`	null	Alternative

Referenced models: Get a session — response body — browser settings timezone id, Login Task — response body — browser_settings_receipt / source: workflow version, session request, existing session, status: verified, mismatch, unapplied, unknown, Get a session — response body — recordings array item

Get a session — response body — browser settings timezone id

Field	Type	Presence	Description and constraints
`$`	object	Root
`timezone_id`	JSON	Optional	IANA timezone the browser reports to pages, for example `America/New_York`. Applied when a browser is created and takes precedence over any timezone implied by the proxy location. Offsets such as `+03:00` are rejected. Omit or set to null to keep the default behavior.
`timezone_id (anyOf 1)`	string	Alternative
`timezone_id (anyOf 2)`	null	Alternative

Get a session — response body — recordings array item

Field	Type	Presence	Description and constraints
`$`	object	Root	Information about a downloaded file, including URL and checksum.
`artifact_id`	JSON	Optional	Artifact row id for refresh-on-read
`artifact_id (anyOf 1)`	string	Alternative
`artifact_id (anyOf 2)`	null	Alternative
`checksum`	JSON	Optional	SHA-256 checksum of the file
`checksum (anyOf 1)`	string	Alternative
`checksum (anyOf 2)`	null	Alternative
`file_size`	JSON	Optional	Size of the file in bytes
`file_size (anyOf 1)`	JSON	Alternative
`file_size (anyOf 1) (anyOf 1)`	integer	Alternative
`file_size (anyOf 1) (anyOf 2)`	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
`file_size (anyOf 2)`	null	Alternative
`filename`	JSON	Optional	Original filename
`filename (anyOf 1)`	string	Alternative
`filename (anyOf 2)`	null	Alternative
`modified_at`	JSON	Optional	Modified time of the file
`modified_at (anyOf 1)`	string	Alternative	Format: date-time
`modified_at (anyOf 2)`	null	Alternative
`url`	string	Required within parent	URL to access the file

Update a session — request body — body

Field	Type	Presence	Description and constraints
`$`	object	Root
`generate_browser_profile`	boolean	Required within parent	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.

Report an issue with this page