Sessions
Drive a long-lived browser session over a WebSocket.
A session is a long-lived browser controlled over a WebSocket. After opening the socket the client performs a handshake, then exchanges action frames with the server to navigate, interact with, and read from a live page.
These endpoints share the error conventions.
/v1/sessions/wsOpens a WebSocket that drives a long-lived browser session.
Reusable shapes
These shapes appear in the frames below.
Cookie
- name stringrequired
The cookie name.
- value stringrequired
The cookie value.
- domain string
The domain the cookie applies to.
- path string
The path the cookie applies to.
- expires string
When the cookie expires.
format: date-time- http_only boolean
Whether the cookie is restricted to HTTP requests.
- secure boolean
Whether the cookie is sent only over secure connections.
- same_site string
The cookie's same-site policy.
LaxStrictNone
Redirect
- url string
The URL that issued the redirect.
- location string
The URL the redirect points to.
- side string
Whether the redirect was issued by the server or the client.
serverclient- type string
Whether the redirect is permanent or temporary.
permanenttemporary
Handshake
Once the socket opens, the client sends an open frame, and the server replies with an open response carrying the session_id. After the handshake the client may send action frames.
- client objectdefault: standard
Selects the fetch client (
standardby default; other kinds enable browser-based fetching). See fetch clients.- middleware object[]default: []
An array of request and response middleware objects. See middleware.
- proxies string[]default: []
Proxy identifiers configured for the fetcher.
- timeout stringdefault: 30s
Request timeout as a duration, for example
30sor5m.- max_redirects numberdefault: 10
The maximum number of redirects to follow.
- max_retries numberdefault: 3
The maximum number of retries on failure.
- session_id string
The identifier of the opened session.
format: uuid
Action frames
After the handshake the client sends action request frames and receives matching response frames. Both are tagged unions on the action field.
Client actions
The client may send the following actions: goto, click, fill, content, evaluate, screenshot, and close. Each frame carries an action field identifying its variant.
- action string
Navigates the page to a URL.
goto- url stringrequired
The URL to navigate to.
- method stringdefault: GET
The HTTP method to use.
GETPOSTPUTDELETEHEADOPTIONSPATCHTRACECONNECT- referrer string
The referrer to send with the request.
- user_agent stringdefault: inndx
The user agent to send. Accepts the keywords
inndx,chrome,firefox,safari,random, or a custom user-agent string.- headers string[][]default: []
Header name and value pairs to send.
- cookies Cookie[]default: []
Cookies to send. See Cookie.
- body string
The base64-encoded request body.
- action string
Clicks an element.
click- selector stringrequired
A CSS selector for the element to click.
- action string
Fills an input element.
fill- selector stringrequired
A CSS selector for the element to fill.
- value stringrequired
The value to fill in.
- action string
Requests the current page content.
content- action string
Evaluates a script in the page.
evaluate- script stringrequired
The JavaScript to run in the page.
- action string
Captures a screenshot of the page.
screenshot- action string
Closes the session.
close
Server responses
The server replies to each action with a matching frame, tagged on the action field.
- action string
The result of a navigation.
goto- url string
The final URL that was navigated to.
- status_code number
The HTTP status code returned.
- headers string[][]
Header name and value pairs from the response.
- cookies Cookie[]
Cookies set by the response. See Cookie.
- body string
The base64-encoded response body, or null when there is no body.
- redirects Redirect[]
The redirects that were followed. See Redirect.
- content_type string
The MIME type of the response, or null when unknown.
- action string
Confirms a click completed.
clicked- action string
Confirms a fill completed.
filled- action string
Carries the requested page content.
content- content string
The base64-encoded page content.
- action string
Carries the result of an evaluated script.
evaluated- result any
The JSON value the script returned.
- action string
Carries a captured screenshot.
screenshot- screenshot string
A base64-encoded PNG screenshot, or null when none was captured.
- action string
Confirms the session was closed.
closed
Error frames
Out of band, the server may send an error frame at any time. A non-fatal error frame leaves the session usable, while a fatal frame is the last frame before the server closes the socket.
- type string
Whether the session remains usable (
error) or is being torn down (fatal).errorfatal- message string
A description of what went wrong.
- code number
A numeric error code, when available.
A fatal error frame is the last frame the server sends before it closes the
socket. Reopen a new session to continue.
wscat -c 'ws://localhost:8022/v1/sessions/ws' -H 'X-Tenant-Id: acme'
# Then send an open frame followed by a goto frame as JSON lines:
{ "proxies": [], "timeout": "30s" }
{ "action": "goto", "url": "https://example.com" }