Browsers

The browser object

{
  "id": "2c4f6a9e-…",
  "status": "active",
  "cdpUrl": "wss://…",
  "liveUrl": "https://…",
  "timeoutAt": "2026-11-09T10:30:00.000Z",
  "startedAt": "2026-11-09T10:15:00.000Z",
  "finishedAt": null,
  "proxyUsedMb": "0",
  "proxyCost": "0",
  "browserCost": "0",
  "agentSessionId": null,
  "recordingUrl": null,
  "metadata": { "team": "checkout" },
  "extensions": [],
  "profileId": "8d1e…",
  "proxySticky": true,
  "finishReason": null
}

Field
`status`	`active` or `stopped`
`cdpUrl`	The Chrome DevTools Protocol address for Playwright’s `connect_over_cdp`, Puppeteer’s `connect` or any CDP client. `null` once stopped
`liveUrl`	The live view: watch the screen, or take control. `null` once stopped
`timeoutAt`	When it stops by itself
`browserCost`, `proxyCost`, `proxyUsedMb`	What it cost, set when it stops
`recordingUrl`, `recordingAvailable`	On `GET /browsers/{id}` only: see Files and recordings
`extensions`	`[{ id, runtimeId, version }]`, the extensions installed
`profileId`, `proxySticky`	BrowserReal’s own: the profile, and whether a managed exit keeps one address
`finishReason`	BrowserReal’s own: `stopped`, `timeout`, `balance` (the balance ran out), `failed`, `lost` (the machine went away) or `admin`
`error`	BrowserReal’s own: why the profile could not be saved, when it could not

Create a browser

POST /browsers → 201 the browser

Every field is optional; {} starts a clean browser, without a proxy, for an hour.

Field	Type
`timeout`	integer	Minutes until it stops by itself, 1–240. Default 60
`profileId`	uuid	A profile to start from and save back to. A profile in use joins its live browser
`metadata`	object	Up to 10 string pairs, for your own bookkeeping and for filtering lists and History
`proxyCountryCode`	string \| null	A residential exit in this country (`"de"`). Omitted or `null`: no proxy. See Proxies
`proxySticky`	boolean	BrowserReal’s own. `false`: a new residential address for every connection. Default `true`
`customProxy`	object	Your proxy: `{ host, port, username?, password?, protocol? }`
`networkPolicyId`	uuid	A network policy
`extensionIds`	uuid[]	Up to 3 extensions
`enableRecording`	boolean	Record the screen. Default `false`
`browserScreenWidth`, `browserScreenHeight`	integer	A fixed screen size, 320–6144 by 320–3456
`allowResizing`	boolean	Let clients resize the window. Default `false`
`solveCaptchas`	boolean	Click Cloudflare Turnstile’s checkbox. Default `true`
`pdfRendererEnabled`	boolean	Show PDFs in Chrome’s viewer rather than downloading them. Default `false`

curl -X POST https://api.datum.org/api/v4/browsers \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timeout": 30, "proxyCountryCode": "gb", "enableRecording": true, "metadata": {"team": "checkout"}}'

Refusals: 402 balance_exhausted, 404 for an unknown profile, policy or extension, 409 profile_in_use, 422 for a value not accepted, 429 too_many_sessions or no_capacity, 502 proxy_failed, 503 start_failed. See Errors.

List browsers

GET /browsers → a page of browsers, newest first

Query
`pageSize`, `pageNumber`	Pagination
`filterBy`	`active` or `stopped`
`metadata`	`key` or `key=value`; repeat it to require several

curl "https://api.datum.org/api/v4/browsers?filterBy=active&metadata=team=checkout" \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY"

Get a browser

GET /browsers/{id} → the browser, with recordingUrl and recordingAvailable

Stop a browser

PATCH /browsers/{id} → the browser

{ "action": "stop" }

The profile is saved, downloads and the recording are kept, the machine is deleted, and the minutes are charged. Stopping a stopped browser does nothing.

While another CDP client is still connected, the browser is not stopped: the answer is the browser, still active, with a stopRefused message. This keeps one agent from ending a browser another is using. Close your own connection first, or send "force": true to stop it for everyone. A browser a person has taken control of in the live view is not stopped by an agent, even with force.