Sessions

Create a session

Changed on

Creates a new session with the provided configuration.

post/v1/sessions

Request

  • Base URL
    https://api.steel.dev
  • URL
    https://api.steel.dev/v1/sessions
  • Auth
    • API key in header steel-api-key
    • or none

Request body

blockAdsboolean

Block ads in the browser session. Default is false.

caCertificatesstring[]

PEM-encoded root CA certificates to trust in this session. THIS IS CURRENTLY AN EXPERIMENTAL FEATURE.

concurrencyinteger

Number of sessions to create concurrently (check your plan limit)

experimentalFeaturesstring[]

Enable experimental features for the session.

extensionIdsstring[]

Array of extension IDs to install in the session. Use ['all_ext'] to install all uploaded extensions.

fullscreenboolean

Launch the browser in fullscreen mode, covering the full screen with no Chrome UI. Default is false.

headlessboolean

Enable headless browser mode (disable Headful mode)

inactivityTimeoutinteger

Inactivity timeout in milliseconds. When set, the session is released if no CDP command or remote input is received for this duration, even if timeout has not yet elapsed. Note that timeout remains the hard cap on session lifetime: if inactivityTimeout is greater than or equal to the effective timeout, it has no effect since timeout always elapses first. Omit to disable.

isSeleniumboolean

Enable Selenium mode for the browser session (default is false). Use this when you plan to connect to the browser session via Selenium.

namespacestring

The namespace the session should be created against. Defaults to "default".

persistProfileboolean

This flag will persist the user profile for the session.

profileIdstring uuid

This flag will set the profile for the session.

projectIdstring uuid

The project to create the session in. When provided, the session namespace is resolved from the project.

proxyUrlstring uri

Custom proxy URL for the browser session. Overrides useProxy, disabling Steel-provided proxies in favor of your specified proxy. Format: http(s)://username:password@hostname:port

recordingboolean

Record the headful session for playback after it ends. Default is true. Disabling recording does not affect live WHEP viewing.

regionunknown
sessionIdstring uuid

Optional custom UUID for the session

solveCaptchaboolean

Enable automatic captcha solving. Default is false.

timeoutinteger

Session timeout duration in milliseconds. Default is 300000 (5 minutes).

userAgentstring

Custom user agent string for the browser session

Response

Represents the data structure for a browser session, including its configuration and status.

browserMode'stealth' | 'standard' | 'unknown' required

Browser mode used for this session.

createdAtstring date-time required

Timestamp when the session started

creditsUsedinteger required

Amount of credits consumed by the session

debugUrlstring required

URL for debugging the session

durationinteger required

Duration of the session in milliseconds

eventCountinteger required

Number of events processed in the session

fullscreenboolean

Launch the browser in fullscreen mode, covering the full screen with no Chrome UI.

headlessboolean

Indicates if the session is headless or headful

idstring uuid required

Unique identifier for the session

inactivityTimeoutinteger

Inactivity timeout in milliseconds, if one was set when the session was created

isSeleniumboolean

Indicates if Selenium is used in the session

persistProfileboolean

This flag will persist the profile for the session.

profileIdstring uuid

The ID of the profile associated with the session

projectIdstring uuid nullable

The project associated with the session

proxyBytesUsedinteger required

Amount of data transmitted through the proxy

proxySource'steel' | 'external' nullable required

Source of the proxy used for the session

regionstring

The region where the session was created.

releaseReason'user_requested' | 'timeout' | 'inactivity_timeout' | 'creation_timeout' | 'startup_failed' | 'browser_closed' | 'browser_crashed' nullable

Why the session reached a terminal state. Null while the session is live, or when the reason is unknown (e.g. sessions created before this was tracked). One of: user_requested (released via the API/SDK), timeout (hard timeout elapsed), inactivity_timeout (no activity for the configured window), creation_timeout (never started in time), startup_failed (could not be dispatched), browser_closed (the browser or agent closed itself — not a crash), browser_crashed (the browser crashed or its machine became unresponsive).

sessionViewerUrlstring required

URL to view session details

solveCaptchaboolean

Indicates if captcha solving is enabled

status'live' | 'released' | 'failed' required

Status of the session

timeoutinteger required

Session timeout duration in milliseconds

userAgentstring

User agent string used in the session

websocketUrlstring required

URL for the session's WebSocket connection

Changes

  • 8f7e74e04bd3Revision changes
    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property

    • info

      removed the ap-northeast enum value from the response property for the response status

    • info

      removed the ap-southeast enum value from the response property for the response status

    • info

      removed the eu-central enum value from the response property for the response status

    • info

      removed the eu-west enum value from the response property for the response status

    • info

      removed the fra enum value from the response property for the response status

    • info

      removed the iad enum value from the response property for the response status

    • info

      removed the lax enum value from the response property for the response status

    • info

      removed the nrt enum value from the response property for the response status

    • info

      removed the ord enum value from the response property for the response status

    • info

      removed the sa-east enum value from the response property for the response status

    • info

      removed the scl enum value from the response property for the response status

    • info

      removed the us-central enum value from the response property for the response status

    • info

      removed the us-east enum value from the response property for the response status

    • info

      removed the us-west enum value from the response property for the response status

    • info

      added the required property to the response with the status

  • 2248d956188aRevision changes
    • info

      request body became optional