GET /wss
Connect to a browser over CDP, optionally restoring a saved profile.
Opens a WebSocket connection to a remote Chrome DevTools Protocol (CDP) browser for automation libraries like Playwright and Puppeteer:
wss://request.usestring.ai/v1/wssAuthentication
Pass Authorization: Bearer YOUR_API_KEY when connecting. Authentication failures arrive as a
WebSocket close with code 1008; an HTTP 101 alone does not mean authentication succeeded.
Query parameters
All parameters are optional and are passed on the connect URL:
wss://request.usestring.ai/v1/wss?proxy=standard&countryCode=DE
wss://request.usestring.ai/v1/wss?contextId=d7a89cd7-c9f7-47fd-84df-77320f254cf8&persist=false| Parameter | Default | Description |
|---|---|---|
proxy | premium | Proxy tier for the session's traffic: premium (residential) or standard (datacenter, billed at half the premium bandwidth rate; see Browser pricing). |
countryCode | US | ISO 3166-1 alpha-2 country code the session's traffic exits from. Validated against the same country list as /fetch and normalized to uppercase. |
contextId | — | UUID of a browser context to restore into the session. Only one saving session can use a profile at a time. |
persist | true | With contextId, save the profile when the session closes. false restores it and discards changes; any number of read-only sessions can run at once. Requires contextId, and a profile that has never been saved cannot be used with persist=false. |
An invalid value, or an unrecognized parameter, rejects the connection after the upgrade with
WebSocket close code 1008 and the validation error as the close reason; no session is opened and
nothing is billed. Profiles do not remember countryCode or proxy, so send the same values on
every connection that uses a contextId.
Close codes
| Code | Meaning | Next step |
|---|---|---|
1000 | Normal close. | With persistence enabled, the profile is saved in the background. |
1008 | Authentication, request, quota, or access refusal. | Correct the request. For a busy profile, see Refused connections. |
1011 | Connection failure or session limit reached. | Retry with backoff. |
4008 | Session bandwidth limit reached. | Reconnect to continue. |
A profile is busy while another saving session is running or its save is still finishing; see Saving and read-only sessions. Read-only sessions are never refused as busy. Refused connections are not billed; sessions that end early are billed for their usage.
Status codes
| HTTP status | Meaning |
|---|---|
101 | WebSocket upgrade accepted. Check for a subsequent close frame before assuming the session is ready. |
404 | WebSocket upgrade attempted on a path other than /wss. |
Session limits
Sessions close after 30 minutes, or five minutes without traffic. A bandwidth cap also applies; see Session limits. With persistence enabled, reaching these limits also saves the profile.
Usage
See Connect with Puppeteer, Connect with Playwright, and Browser contexts for complete examples.