Get a browser and its current Run

GET

/v1/browsers/:browserId

GET

/v1/browsers/:browserId

curl https://api.bctrl.ai/v1/browsers/browserId \
     -H "Authorization: Bearer <token>"

{
  "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"
      ]
    }
  ]
}

Read a browser and its current Run. Use wait to wait for an accepted start or stop. Saved state remains private to the browser and is restored on its next Run.

Authentication

AuthorizationBearer

Use Bearer <api-key>.

Path parameters

browserIdstringRequired

Query parameters

spaceIdstring or "default"Optional

waitintegerOptional0-60Defaults to 0

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

403

Forbidden Error

404

Not Found Error

Authentication

Path parameters

Headers

Query parameters

Response headers

Response

Errors