Skip to navigation
API ReferenceBrowsers

Update browser configuration for its next Run

View as Markdown

Update configuration used by the next Run. Changing stealth or viewport requires an idle browser without saved state or a queued start; stop with discardState first.

Authentication

AuthorizationBearer

Use Bearer <api-key>.

Path parameters

browserIdstringRequired

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

spaceIdstring or "default"Optional

Request

This endpoint expects an object.
auditobjectOptional

Machine audit detail (preview).

autoUpgradebooleanOptional
captchaobjectOptional
expireAfterIdleDaysintegerOptional1-365
extensionslist of stringsOptional
forceOpenShadowRootsbooleanOptional
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
proxystring or any or object or objectOptional
recordingbooleanOptional
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

OK
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

401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
429
Too Many Requests Error