Start a browser with its saved state

POST

/v1/browsers/:browserId/start

POST

/v1/browsers/:browserId/start

curl -X POST https://api.bctrl.ai/v1/browsers/browserId/start \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'

{
  "autoUpgrade": true,
  "createdAt": "2026-07-26T12:00:00Z",
  "currentRun": {
    "connections": {
      "cdpUrl": "string",
      "expiresAt": "2026-07-26T12:00:00Z",
      "liveViewReadOnlyUrl": "string",
      "liveViewUrl": "string",
      "webdriverUrl": "string"
    },
    "control": {
      "holder": "agent",
      "since": "2026-07-26T12:00:00Z"
    },
    "createdAt": "2026-07-26T12:00:00Z",
    "endedAt": "2026-07-26T12:00:00Z",
    "endReason": "string",
    "id": "run_uAAAAAAAAAAAAAAAAAAAAAA",
    "location": "us-east",
    "object": "string",
    "recording": {
      "enabled": true
    },
    "resourceId": "br_uAAAAAAAAAAAAAAAAAAAAAA",
    "resourceType": "string",
    "spaceId": "sp_uAAAAAAAAAAAAAAAAAAAAAA",
    "startedAt": "2026-07-26T12:00:00Z",
    "status": "starting",
    "taskId": "task_uAAAAAAAAAAAAAAAAAAAAAA",
    "traceId": "string",
    "updatedAt": "2026-07-26T12:00:00Z",
    "machineAccess": {
      "count": 1,
      "firstAt": "2026-07-26T12:00:00Z",
      "inheritedFrom": "run_uAAAAAAAAAAAAAAAAAAAAAA",
      "used": true
    },
    "usage": {
      "aiTokensTotal": 1,
      "billingStatus": "pending",
      "captchaSolves": 1,
      "computedAt": "2026-07-26T12:00:00Z",
      "cpuSeconds": 1.1,
      "creditsUsed": 1.1,
      "filesBytes": 1,
      "memoryGbSeconds": 1.1,
      "proxyBytes": 1,
      "runtimeSeconds": 1.1
    },
    "warnings": [
      {
        "message": "string",
        "type": "string",
        "browserIds": [
          "br_uAAAAAAAAAAAAAAAAAAAAAA"
        ]
      }
    ]
  },
  "expireAfterIdleDays": 1,
  "extensions": [
    "string"
  ],
  "forceOpenShadowRoots": true,
  "gpu": true,
  "headless": true,
  "id": "br_uAAAAAAAAAAAAAAAAAAAAAA",
  "lastUsedAt": "2026-07-26T12:00:00Z",
  "location": "auto",
  "metadata": {},
  "name": "string",
  "object": "string",
  "recording": true,
  "savedState": {
    "sizeBytes": 1,
    "status": "none"
  },
  "spaceId": "sp_uAAAAAAAAAAAAAAAAAAAAAA",
  "standbyAfterSeconds": 1.1,
  "status": "idle",
  "stealth": "normal",
  "timeoutSeconds": 1,
  "type": "string",
  "updatedAt": "2026-07-26T12:00:00Z",
  "viewport": {
    "height": 1,
    "width": 1
  },
  "webRtcProxyOnly": true,
  "audit": {
    "files": "summary"
  },
  "captcha": {
    "autoSolve": true
  },
  "copiedFrom": {
    "browserId": "br_uAAAAAAAAAAAAAAAAAAAAAA",
    "persona": "same",
    "savedStateAt": "2026-07-26T12:00:00Z"
  },
  "networkTraffic": {
    "blockAds": true,
    "blockResourceTypes": [
      "media"
    ],
    "blockTrackers": true,
    "saver": "none",
    "urlAllowlist": [
      "string"
    ],
    "urlBlocklist": [
      "string"
    ]
  },
  "proxy": {
    "id": "string",
    "name": "string",
    "type": "custom"
  },
  "warnings": [
    {
      "message": "string",
      "type": "string",
      "browserIds": [
        "br_uAAAAAAAAAAAAAAAAAAAAAA"
      ]
    }
  ]
}

Durably request a new Run of this browser, restoring its saved state. If a previous Run is stopping or saving, startup waits for it. An existing current Run is returned without starting another browser.

Authentication

AuthorizationBearer

Use Bearer <api-key>.

Path parameters

browserIdstringRequired

Headers

Query parameters

spaceIdstring or "default"Optional

waitintegerOptional0-60Defaults to 0

Request

This endpoint expects an object.

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

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

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