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
Keepid: 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 tocdpUrl, and use the page that is already open.
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
SendDELETE as soon as you are done. This is when the time and traffic are billed.
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.
GET /v1/browser lists your sessions, newest first, and is free.
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 ofPOST /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
freetier and 10 on thepaidtier. AnotherPOST /v1/browserreturns429 rateLimitedand says how many are open. Close one to open another. See Rate limits. - A balance too low to cover the
ttlreturns402 insufficientCreditsand no session opens. - A call on a session that has ended returns
410 notFoundwithThis browser session has ended.Calls that need a running session, such as listing downloads, return409 invalidRequest. - An id that does not exist returns
404 notFoundwithNo browser session with that id. allowedDomainsandnetworkPolicyIdtogether,profilewithzeroDataRetention, andrecordingwithzeroDataRetentioneach return400 invalidRequestthat names the two fields.