String docs

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/wss

Authentication

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
ParameterDefaultDescription
proxypremiumProxy tier for the session's traffic: premium (residential) or standard (datacenter, billed at half the premium bandwidth rate; see Pricing).
countryCodeUSISO 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.
persisttrueWith 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.
solveCaptchafalsetrue solves a captcha or challenge page that a top-level GET navigation lands on, so the navigation resolves on the page behind it. Requires an API key allowed to solve captchas. See Captcha solving in browser sessions.

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

CodeMeaningNext step
1000Normal close.With persistence enabled, the profile is saved in the background.
1008Authentication, request, quota, or access refusal.Correct the request. For a busy profile, see Refused connections.
1011Connection failure or session limit reached.Retry with backoff.
4008Session 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 statusMeaning
101WebSocket upgrade accepted. Check for a subsequent close frame before assuming the session is ready.
404WebSocket 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.