activityTtl seconds with no call (default 300, from 10) or ttl seconds after it opens (default 600, from 30), whichever comes first. Both go up to 21,600. It bills for the time it is open, so close it when you finish.
id: every other call on the session uses it. cdpUrl carries a token, so keep it private. liveViewUrl lets you watch the session and interactiveLiveViewUrl lets you control it. timeoutAt moves forward with each call, and expiresAt is ttl after opening.
To recover a session after a dropped answer, send the same Idempotency-Key header, key and body within 24 hours. A different body or an ended session returns 409. On 503 with Retry-After, retry with the same key.
Drive it
- Over CDP:
chromium.connectOverCDP(cdpUrl)in Playwright, orpuppeteer.connect({ browserWSEndpoint: cdpUrl }). Use the page that is already open. CDP activity counts as a call foractivityTtl, and disconnecting does not close the session. - Over HTTP: run code or a prompt in it.
Close, read and list
DELETE /v1/browser/{session_id} closes the session and bills it. The answer has costUsd, sessionDurationMs, proxyBytes split by network in exitBytes (see Network) and recordingStatus. Closing it again charges nothing and returns the bill as sessionCostUsd.
GET /v1/browser/{session_id} is free. A running session lists its downloads and uploads. A closed one has status: "destroyed", finishedAt, and browserCostUsd, proxyCostUsd and proxyUsedMb to tell time from traffic.
GET /v1/browser is free and lists sessions, newest first. Run ?status=active before you stop work to confirm none is open. Filter with status (active or destroyed) and metadata (key or key=value, repeat to narrow). Page with limit (50, up to 100) and cursor, set to nextCursor while hasMore is true.
Options
Every field ofPOST /v1/browser is optional.
Recordings and replay
Both are free. A recording is a video of every tab. A replay lists the pages the session visited and the steps run on each, kept 24 hours after the session closes, and needs norecording.
Open the session with "recording": true. recordingStatus is recording while the session runs and processing while the video is made after it closes, then ready or failed (never made). none means not recorded, or deleted.
GET /v1/browser/{session_id}/recordingreturns the status and, whenready,recordingUrl: an MP4 that needs no key for 15 minutes. Read it again for a new link. The video is kept 7 days.recordingTruncated: truemeans it ends early.DELETE /v1/browser/{session_id}/recordingremoves the video at once. The replay stays.GET /v1/browser/{session_id}/replayreturnspages, each withpageId,url,title,at(milliseconds since 1970) andsteps(the calls your code made).GET /v1/browser/{session_id}/replay/{page_id}addsscreenshot, a Base64 JPEG.maxTextLengthcuts text values.
Errors
Other codes are on Errors.