Skip to navigation
API ReferenceBrowsers

Create and start a browser

View as Markdown

Create a reusable browser and durably request its first Run. Use wait to wait up to 60 seconds for startup; currentRun is null until a Run is admitted and connections appear after the browser starts.

Authentication

AuthorizationBearer

Use Bearer <api-key>.

Headers

BCTRL-VersionenumOptional
Dated API version. Defaults to the release pinned when the API key was created.
Allowed values:
BCTRL-SpacestringOptional
Select one authorized Space by its opaque ID or unique name. Omission uses the operation default.
BCTRL-Subaccount-IdstringOptional
Optional effective subaccount context for organization API keys. Subaccount API keys are already scoped and cannot use this header to act as another subaccount.
Idempotency-KeystringOptional1-200 characters

Optional retry key for this billable operation. Reusing the same key with the same request replays its stable outcome; credential-bearing results may be freshly issued for the same principal. Reusing it with a different request returns 409.

Query parameters

waitintegerOptional0-60Defaults to 0

Request

This endpoint expects an object.
auditobjectOptional

Machine audit detail (preview).

autoUpgradebooleanOptional
captchaobjectOptional
expireAfterIdleDaysintegerOptional1-365
extensionslist of stringsOptional
forceOpenShadowRootsbooleanOptional
fromBrowserstringOptional

Preview. Start from a copy of the last saved state of this browser (cookies, site storage, tabs, preferences); the source is not touched. Requires persona.

gpubooleanOptional
headlessbooleanOptional
location"auto" or enumOptional

Compute location, or auto to choose the allowed live location (currently us-east).

metadataobjectOptional
namestringOptional1-200 characters

Customer-facing resource name. 1–200 characters.

networkTrafficobjectOptional
personaenumOptional
Preview. Required with fromBrowser.
Allowed values:
proxystring or any or object or objectOptional
recordingbooleanOptional
spaceIdstring or "default"Optional
standbyAfterSecondsdoubleOptional

Standby is currently disabled; use 0.

stealthenumOptional
Allowed values:
timeoutSecondsintegerOptional<=3600
viewportobjectOptional
webRtcProxyOnlybooleanOptional

Response headers

BCTRL-Request-IdstringOptional
Current request identifier, also echoed in errors.
BCTRL-VersionstringOptional
Negotiated dated API version.
RateLimit-Limitinteger

Evaluated policy limit; zero when no finite policy was evaluated.

RateLimit-Remaininginteger

Remaining policy budget; zero when no finite policy was evaluated.

RateLimit-Resetinteger

Seconds until reset; zero when no finite policy was evaluated.

Response

Created
autoUpgradeboolean
createdAtdatetime
RFC 3339 timestamp with a UTC offset.
currentRunobject or null
expireAfterIdleDaysinteger1-365
extensionslist of strings
forceOpenShadowRootsboolean
gpuboolean
headlessboolean
idstring
Unique browser identifier generated by BCTRL.
lastUsedAtdatetime
RFC 3339 timestamp with a UTC offset.
location"auto" or enum

Compute location, or auto to choose the allowed live location (currently us-east).

metadataobject
namestring
object"browser"
recordingboolean
savedStateobject
spaceIdstring
Unique space identifier generated by BCTRL.
standbyAfterSecondsdouble

Standby is currently disabled; use 0.

statusenum
Allowed values:
stealthenum
Allowed values:
timeoutSecondsinteger<=3600
type"browser"
updatedAtdatetime
RFC 3339 timestamp with a UTC offset.
viewportobject
webRtcProxyOnlyboolean
auditobjectOptional

Machine audit detail (preview).

captchaobjectOptional
copiedFromobject or nullOptional

Preview. The browser this one was copied from (fromBrowser).

networkTrafficobjectOptional
proxynullable any or objectOptional
warningslist of objectsOptional

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error