Skip to main content
POST

Price

$0.06 per hour open, $0.84 per hour once a prompt has run, billed when it closes, one minute at least. Traffic adds $5 per GB through the managed network location, the default, and $0.20 per GB direct or through your own proxy. See Pricing.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
ttl
integer
default:600
Required range: 30 <= x <= 21600
activityTtl
integer
default:300
Required range: 10 <= x <= 21600
streamWebView
boolean
zeroDataRetention
boolean
blockAds
boolean
solveCaptchas
boolean
captureConsole
boolean
screen
object

Window size in pixels, width 500 to 6144 and height 320 to 3456, the sizes Chrome keeps. Sites still read a 1920x1080 display. Leave it out unless you need it.

allowResizing
boolean

false keeps the window at its size: setViewportSize and CDP resize commands are accepted and change nothing. Leave it out to allow resizing.

pdfRenderer
boolean

true shows PDFs in the browser's own viewer. Left out or false, a PDF is saved as a download.

recording
boolean

true records every tab the session shows as an MP4 video. Free. The video is made after the session stops and kept 7 days. Read recordingStatus on the session, then recordingUrl. Not with zeroDataRetention.

metadata
object

Up to 10 pairs of text, keys up to 100 characters and values up to 1000. Sent back with the session, and list can filter on them.

extensionIds
string<uuid>[]

Up to 3 ids of extensions you uploaded with POST /v1/browser/extensions. They load before the first page opens and cannot change while the session runs. Leave it out for a plain browser: loading an extension changes what sites can see.

Maximum array length: 3
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
allowedDomains
string[]
Maximum array length: 100
Pattern: ^(?:\*\.)?[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$
networkPolicyId
string

A saved network policy from POST /v1/browser/network-policies. Its rules apply to every request the session makes, and a change to the policy reaches the running session within seconds. Not with allowedDomains.

Required string length: 1 - 100
proxy

residential is the default network, and the only one location.country applies to. direct uses no proxy. Or send your own proxy URL.

Allowed value: "residential"
profile
object
location
object

Response

The session.

success
any
required
creditsUsed
integer
required
costUsd
number
required

What this call cost, in dollars.

requestId
string
required
id
string
status
enum<string>
Available options:
active,
destroyed
createdAt
string<date-time>
startedAt
string<date-time>

When the session opened.

finishedAt
string<date-time> | null

When the session ended. Null while it runs.

timeoutAt
string<date-time>

When the session stops by itself if nothing else happens: the earlier of expiresAt and the idle limit after the last call, which moves forward with each call. After the session ends it is finishedAt.

lastActivity
string<date-time>
expiresAt
string<date-time>
metadata
object

The pairs sent when the session opened.

networkPolicyId
string | null

The network policy the session was opened with. Null for none.

networkPolicyVersion
integer | null

The version of that policy the session enforces now. It goes up when a change to the policy reaches the session, so a session behind the policy's version has not received the change yet.

proxyUsedMb
number | null

Traffic through all networks, in MB. Null until the session closes.

browserCredits
integer | null

Older field: the browser time in $0.002 steps. Null until the session closes.

browserCostUsd
number | null

What the time the session was open cost, in dollars. Null until it closes.

proxyCredits
integer | null

Older field: the traffic in $0.002 steps. Null until the session closes.

proxyCostUsd
number | null

What the traffic cost, in dollars. Null until the session closes.

cdpUrl
string

Connect a CDP client such as Playwright here.

liveViewUrl
string

Watch the session. Sent with streamWebView.

interactiveLiveViewUrl
string

Watch and control the session. Sent with streamWebView.

streamWebView
boolean
extensions
object[]

The extensions loaded in the session, in the order of extensionIds.

recordingStatus
enum<string>

none: the session was not recorded, or its video was deleted. recording: the session is running. processing: the session stopped and the video is being made, usually within a few minutes, or the status could not be read yet, so read it again. ready: recordingUrl works. failed: the video was never made and cannot be any more. A ready video is kept 7 days.

Available options:
none,
recording,
processing,
ready,
failed
recordingAvailable
boolean

false when recordingStatus is none or failed, true while a video is or will be there.

recordingTruncated
boolean

true when the video ends early because the session showed more than a recording can hold.

recordingUrl
string

The MP4, with no key needed, for 15 minutes. It plays and seeks in a browser or player. Sent when recordingStatus is ready. Read the session again for a new link.

warning
string