Skip to main content
A browser session is a real browser in the cloud that stays open between your calls. You pay for the time it is open, so close every session you open.

Make a request

Get an API key in the Quickstart. Browser sessions need an API key. This request opens a session that lives for at most 5 minutes and closes itself after 60 seconds with no calls.

Read the response

Keep id: every other call on the session uses it. This real response is cut to the fields you need first. The tokens in the links are cut.
cdpUrl is where Playwright or Puppeteer connects. liveViewUrl lets you watch the session, and interactiveLiveViewUrl lets you watch and control it. timeoutAt is when the session closes by itself if nothing happens. Opening a session costs nothing. The time and traffic are billed when it closes.

Connect over CDP

Any client that speaks the Chrome DevTools Protocol can drive the session. Connect to cdpUrl, and use the page that is already open.
The Playwright example printed Example Domain, then the closing bill. Disconnecting does not close the session: it keeps running, and billing, until you send DELETE or it times out. The link carries a token for this session, so keep it private. Activity on the CDP connection counts as a call for activityTtl. You do not need a CDP client to use a session. Run code or a prompt in it with one HTTP call.

Set how long it lives

The session closes at the earlier of expiresAt (ttl after it opened) and the idle limit. You are billed for the time it was open either way.

Close a session

Send DELETE as soon as you are done. This is when the time and traffic are billed.
This real session was open for 34 seconds.
sessionDurationMs is how long the session was open. proxyBytes is all its traffic, and exitBytes splits it by how the session reached the web, because each kind has its own price. See Network location. costUsd is the bill. creditsBilled and creditsUsed are the older fields for the same amount, in steps of $0.002. Closing a session that is already closed returns the same bill and charges nothing more.

Read and list sessions

GET /v1/browser/{session_id} returns one session, and is free. A running session also lists its downloads and uploads. After it closes, the same call shows what it cost: proxyUsedMb, browserCostUsd and proxyCostUsd.
This real closed session shows the bill split in two. The links are cut.
GET /v1/browser lists your sessions, newest first, and is free.
Each session in sessions has the fields above. hasMore is true while nextCursor holds a cursor for the next page. Run this before you stop work, to confirm no session is still open.

Options

These fields go in the body of POST /v1/browser. Every field is optional.

Price

Time is billed when the session closes, with one minute at least. Amounts are rounded up to $0.002. Opening a session sets aside the most it can cost for its full ttl, and what it does not use comes back when it closes. Opening, listing, reading and closing cost nothing by themselves. Calls that fail cost nothing. See Pricing.

Limits and errors

  • You can have 3 sessions open at once on the free tier and 10 on the paid tier. Another POST /v1/browser returns 429 rateLimited and says how many are open. Close one to open another. See Rate limits.
  • A balance too low to cover the ttl returns 402 insufficientCredits and no session opens.
  • A call on a session that has ended returns 410 notFound with This browser session has ended. Calls that need a running session, such as listing downloads, return 409 invalidRequest.
  • An id that does not exist returns 404 notFound with No browser session with that id.
  • allowedDomains and networkPolicyId together, profile with zeroDataRetention, and recording with zeroDataRetention each return 400 invalidRequest that names the two fields.

Choose another API

  • Execute runs code or a prompt in a session you opened.
  • Tasks does a few steps on a public site without you opening a session.
  • Interact opens a session on a page you already scraped.
  • Scrape reads one page and returns it, with no session to close.
  • Batches read a list of URLs in the background.