Skip to main content
POST
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.
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.

Response

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.

Error status codes

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.