Session options are the fields of the create-session request, POST /v1/sessions. They set how the session's browser runs, such as its timeout, its proxy and the profile that it starts from. With a project key, every option is optional, and a request with no body creates a session with the defaults. With an organization key, the request must include projectId. The types and defaults come from the API specification. The response fields are on Sessions API.
The TypeScript SDK uses the names on this page. The Python SDK writes the same names in snake_case, in nested objects too. For example, useProxy is use_proxy, and stealthConfig.autoCaptchaSolving is stealth_config.auto_captcha_solving. Only timeout is different. It is api_timeout in Python, because timeout is the timeout of the HTTP request there. Pass the session timeout as api_timeout, not as timeout.
Sessions
Option
Type
Default
What it does
Page
blockAds
boolean
true
Blocks requests to known ad and tracking hosts. Set it to false to let them load.
The size of the browser window, in pixels, at most 1920 × 1080. In a headful desktop session, the page's viewport is 8 pixels narrower and 91 pixels shorter. See dimensions.
Turns on features by name. ["useStealthBrowser"] runs the session on Stealth Browser. The other names, which Steel does not publish, turn on Experimental features.
Releases the session after this many milliseconds without activity, such as a CDP command or a Commands request. Release idle sessions lists what counts as activity. The minimum is 1. It has no effect when it is equal to or greater than timeout.
The namespace to create the session in. Without it, Steel uses the project's namespace, which is "default" for a new project. It holds letters, digits, _, ., : and -, and it is not . or ...
The longest time that the session can run, in milliseconds. The minimum is 15000, and Steel raises a smaller value to 15000. The maximum is 15 minutes on Launch, 1 hour on Scale and up to 24 hours on Enterprise.
"mobile" gives the session a mobile user agent, viewport, touch input and fingerprint.
dimensions
Field
Type
Default
Description
height
integer
Required
The height in pixels.
width
integer
Required
The width in pixels.
A mobile session needs at least 508 × 1074 (width × height). A request with smaller dimensions fails with 400. A mobile session with no dimensions in the request or in its profile uses 508 × 1074.
metadata
metadata is a flat object of your own keys and values. Steel returns it on every session response. It follows these rules:
It holds at most 50 keys and 8192 bytes of UTF-8 JSON.
A key starts with a letter, holds only letters, digits, _, . and -, and has at most 64 characters.
Keys that start with steel_ are reserved.
A value is a string of at most 1024 characters, a finite number or a boolean. A string is valid Unicode with no NUL character.
Steel stores numbers and booleans as strings, so 3 and "3" are the same value.
optimizeBandwidth
Pass true to block images, media and stylesheets. Pass an object to choose what to block. The host and URL lists apply only in the object form.
Field
Type
Description
blockHosts
string array
Blocks requests to these hosts.
blockImages
boolean
Blocks images.
blockMedia
boolean
Blocks media.
blockStylesheets
boolean
Blocks stylesheets.
blockUrlPatterns
string array
Blocks requests whose URL matches one of these patterns.
Stealth
Option
Type
Default
What it does
Page
caCertificates
string array
None
Root CA certificates, in PEM format, that the session trusts. Experimental.
Steel proxies and CAPTCHA solving work on Scale and Enterprise, and on Launch after you verify your account.
stealthConfig
Field
Type
Default
Description
autoCaptchaSolving
boolean
true
With solveCaptcha, Steel solves a CAPTCHA as soon as it detects one. Set it to false to detect CAPTCHAs only, and start each solve yourself with the solve endpoints.
humanizeInteractions
boolean
false
Makes the mouse and key input that you send over CDP act more like a person. The mouse moves along a curved path, and each key event waits a random 10 to 150 milliseconds.
skipFingerprintInjection
boolean
false
Skips the fingerprint that Steel generates for the session. Set it only when your code controls the fingerprint.
useProxy
Value
What it does
Page
true
Routes the browser through a Steel residential proxy in the United States.
A two-letter country code (ISO 3166-1 alpha-2), from the list of countries.
state
string
None
A two-letter US state code, such as NY, from the list of states. Use it only with "country": "US".
Pass each value exactly as it appears in the Countries, States and Cities lists. Some city values hold a space, such as HO_CHI MINH CITY.
The list has no NEW_YORK, LOS_ANGELES or LONDON. Some large cities are listed by district instead, such as BROOKLYN, QUEENS and THE_BRONX in New York, and HACKNEY in London. For a city that is not in the list, pass only country. In the United States, you can also pass state.
Logins and state
Option
Type
Default
What it does
Page
credentials
object
None
Fills stored credentials into sign-in forms. With {}, the defaults below apply. Without the option, Steel fills no credentials. See credentials.
Saves the browser state to a profile after you release the session. With profileId, it updates that profile. Without profileId, Steel creates a new profile and returns its profileId. Do not use it with credentials, as Use credentials with a profile explains.
Blurs the username and password fields right after Steel fills them, and shows dots instead of their text, so that a vision model cannot read the values. Steel does not blur the one-time password field.
credentialProvider
string
"steel"
The provider that resolves credentials while the session runs. Only "steel" is supported.
exactOrigin
boolean
true
Ignored. Steel fills the same pages with either value. Credentials says which pages Steel fills.
origins
string array
None
An allowlist of credential origins to fill in this session.
The credentials must be in the same project and namespace as the session.
sessionContext
Field
Type
Description
cookies
object array
Cookies to set in the session. See the cookie fields below.
indexedDB
object
IndexedDB databases to set, keyed by domain. Each value is an array of databases.
localStorage
object
localStorage items to set, keyed by domain. Each value maps keys to string values.
sessionStorage
object
sessionStorage items to set, keyed by domain. Each value maps keys to string values.
Cookie fields
Field
Type
Required
Description
domain
string
No
The domain that the cookie is sent to, such as example.com.
expires
number
No
When the cookie expires, in seconds since the Unix epoch. Without it, the cookie is a session cookie.
httpOnly
boolean
No
true hides the cookie from the page's JavaScript.
name
string
Yes
The cookie's name.
partitionKey
object
No
The partition of a partitioned cookie: topLevelSite (string, required) and hasCrossSiteAncestor (boolean, required). Without it, the cookie is not partitioned.
path
string
No
The URL path that the cookie applies to, such as /.
priority
string
No
Low, Medium or High.
sameParty
boolean
No
Read from the browser. You do not need to set it.
sameSite
string
No
Strict, Lax or None.
secure
boolean
No
true sends the cookie over HTTPS only.
session
boolean
No
Read from the browser: true for a cookie with no expiry. Ignored when you set a cookie.
size
number
No
Read from the browser: the cookie's size. Ignored when you set a cookie.
sourcePort
number
No
The port of the origin that set the cookie, from 1 to 65535, or -1 for an unspecified port.
sourceScheme
string
No
The scheme of the origin that set the cookie: Unset, NonSecure or Secure.
url
string
No
The URL to set the cookie for. The browser takes the default domain, path and scheme from it.
value
string
Yes
The cookie's value.
IndexedDB fields
Each database in indexedDB has an id (number), a name (string) and data, an array of object stores. All three are required.
Object
Field
Type
Required
Object store
id
number
Yes
Object store
name
string
Yes
Object store
records
array of records
Yes
Record
key
any
Yes
Record
value
any
Yes
Record
blobFiles
array of blob files
No
Blob file
blobNumber
number
Yes
Blob file
mimeType
string
Yes
Blob file
size
number
Yes
Blob file
filename
string
No
Blob file
lastModified
string (date-time)
No
Blob file
path
string
No
Files and extensions
Option
Type
Default
What it does
Page
extensionIds
string array
None
The IDs of the extensions to install in the session. ["all_ext"] installs every extension that you uploaded.