Skip to main content
A browser session is a cloud browser that keeps its pages, tabs and login across your calls. For one page read without clicks, use Scrape.
The session closes after 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.
Keep 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, or puppeteer.connect({ browserWSEndpoint: cdpUrl }). Use the page that is already open. CDP activity counts as a call for activityTtl, 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 of POST /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 no recording. 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}/recording returns the status and, when ready, recordingUrl: an MP4 that needs no key for 15 minutes. Read it again for a new link. The video is kept 7 days. recordingTruncated: true means it ends early.
  • DELETE /v1/browser/{session_id}/recording removes the video at once. The replay stays.
  • GET /v1/browser/{session_id}/replay returns pages, each with pageId, url, title, at (milliseconds since 1970) and steps (the calls your code made). GET /v1/browser/{session_id}/replay/{page_id} adds screenshot, a Base64 JPEG. maxTextLength cuts text values.

Errors

Other codes are on Errors.

Next

  • Execute: run code or a prompt in the session.
  • Tasks: do a few steps on a public site with no session of yours.
  • Interact: open a session on a page you scraped.