Skip to main content
Use this endpoint when you want a running browser immediately without a separate create-then-start flow. A single POST /cloud-browsers/launch saves a new profile and starts it, blocking until the browser reaches running state before returning 201. The response includes runtime.connectUrl — open that URL in a browser signed in as the profile owner to access the interactive session. The saved profile persists after you stop the browser and can be restarted, queried, or deleted just like any manually created profile.
Each call to this endpoint creates a new profile with no idempotency key. Never automatically retry a failed launch request. If the response includes an id, inspect that profile and call POST /cloud-browsers/{id}/stop (with retries) before attempting a new launch.

​
Authentication

Include one of the following on every request:

​
Request Body

The body must be a single JSON object of at most 1 MiB. Unknown top-level fields — including countryCode, source, and browserSettings — are rejected with 400.
​
object
required
Custom proxy configuration. Required on every request regardless of authentication method. No saved proxy, managed region, or previous run’s proxy can replace this field.Supply either the server form or the split protocol + host + port form:
  • server — full URL: http://proxy.example.com:8080 or socks5://proxy.example.com:1080. Must include an explicit port (1–65535). Must not contain embedded credentials, path, query, or fragment. Cannot be combined with host.
  • protocol — http or socks5.
  • host — proxy hostname.
  • port — integer or numeric string from 1 to 65535.
Omit both username and password for an unauthenticated proxy, or supply both as non-empty strings. A proxy failure must never fall back to a direct connection.
​
array
HTTP(S) URLs to open as tabs when the browser starts. Defaults to [] (no tabs injected). Up to 8 entries; each URL must be at most 16,384 bytes without embedded credentials, control characters, or surrounding whitespace. Each entry is either a URL string or an object { url, active? }. Set active: true on at most one tab to make it the active tab; the first tab becomes active when none is selected.
​
array
Cookies to inject before the browser opens. Defaults to []. Up to 10,000 entries within the 1 MiB request limit. Required fields per entry: name, domain (non-empty strings); value defaults to an empty string. Optional fields: path (defaults to /), secure, httpOnly, session (booleans), expires (Unix seconds), sameSite (Strict | Lax | None). Expired entries are filtered; unknown fields and invalid types are rejected.
​
object
Browser fingerprint settings for this session. Defaults: webRtc=forward; all other signals (webGl, webGpu, webGlImage, canvas, audioContext, clientRects, speechVoices, fonts, hardware, doNotTrack) default to random. Partial input fills remaining defaults. Optional hardwareConcurrency and deviceMemory accept integers 1–64; the server generates the runtime seed.
​
string (UUID)
Required when authenticating with a session cookie or Authorization: Bearer. Selects which of your active API keys to use for billing. When authenticating with x-api-key directly, this field is optional — if supplied, it must match the key used in the header.

​
Responses

​
201 — Browser Running

Returned only after the browser reaches running state. The Location response header points to GET /cloud-browsers/{id} for subsequent queries.
​
boolean
Always true on success.
​
string (UUID)
Persistent profile identifier. Store this immediately — you need it to stop, query, or delete the browser.
​
string
Always "launch" for profiles created via this endpoint.
​
boolean
Always false. The profile is retained after the browser stops.
​
object
Runtime state at the moment the response is sent.

​
400 — Bad Request

PROXY_REQUIRED, INVALID_PROXY, INVALID_TABS, INVALID_COOKIES, or INVALID_FINGERPRINT_SETTINGS. Explicit null, unknown fields, invalid JSON, and incorrect types are all rejected before any profile is created.

​
401 — Unauthenticated

Authentication is missing, invalid, or expired.

​
402 — Payment Required

PAID_PLAN_REQUIRED or INSUFFICIENT_CREDITS. No profile is created.

​
403 — Forbidden

The supplied apiKeyId belongs to another user or does not match the authenticated key. No profile is created.

​
409 — Conflict

Either the saved-profile allowance is full (Cloud Browser limit reached) or the running allowance is full or zero (CLOUD_BROWSER_CONCURRENCY_LIMIT). When a profile was created before the conflict was detected, the response includes id, source: "launch", deleteOnStop: false, deleted: false, and the actual runtime status. The profile remains saved and counts toward your allowance.

​
502 / 503 / 504 / 500 — Runtime or Server Error

Errors that occur after profile creation include id, runtime, and Location in the response body. Cleanup may leave the session in stopping state, which still reserves a running slot until confirmed stopped.
When the response contains an id alongside a 5xx status, do not automatically retry the launch. Instead, call POST /cloud-browsers/{id}/stop with a bounded retry loop until runtime.status reaches stopped, then decide whether to launch again.

​
Request Example

Use --max-time 200 (or equivalent) for your HTTP client. The endpoint waits up to 60 seconds for the browser to reach running state, and cleanup after a failed startup can take up to 120 additional seconds.
cURL

​
Response Examples