SPHYNX
esc
  • Loading
Open console

Get started

Concepts

Sessions, identities, proxies, locators and how calls on one session take turns.

Every endpoint builds on the ideas on this page. Each section links to the reference for the fields.

Sessions

A session is one running browser with its own identity and, if you ask for one, its own proxy. POST/v1/sessions starts it and returns once the browser is ready. You can then use it in three ways, separately or together:

  • connect Playwright or Puppeteer to its cdp_url,
  • drive it over HTTP with /navigate, /elements, /actions, /extract and /screenshot,
  • give it to an agent through the MCP server or an agent run.

The session keeps its pages, cookies and tabs for as long as it runs. Nothing of that is kept once it ends. Field by field: Sessions.

When a session ends

A session ends in one of four ways: you delete it, timeout_seconds passes, it is idle for idle_timeout_seconds, or the browser exits. Disconnecting a Playwright or Puppeteer client does not end it. A client that sends Browser.close does, as Puppeteer's browser.close() does.

status is active while the session runs. Afterwards close_reason says why it ended.

Close reasonStatusWhat happened
releasedclosedIt was deleted with DELETE /v1/sessions/{id}
timeoutclosedtimeout_seconds passed. Default 3600, from 60 to 21600
idle_timeoutclosedIdle for idle_timeout_seconds. Default 300, from 30 to 3600
browser_closedclosedThe browser exited, for example because a CDP client sent Browser.close
browser_crashederrorThe browser crashed
launch_failederrorThe browser failed to start, or start_url did not load

An ended session stays readable with GET /v1/sessions/{id}. Any call that needs the browser returns 410 session_closed.

The idle clock

The idle clock is reset by every drive call and by every frame on a CDP connection. Reading the session with GET and watching the live view do not reset it.

A session is not idle while a drive call is running on it, however long the call takes. An agent run resets the clock about every 10 s while it is running.

Both limits are set when the session is created. expires_at on the session is the moment timeout_seconds runs out.

curl
# 15 minutes at most, closed after 10 idle minutes
curl -s -X POST "$SPHYNX_URL/v1/sessions" \
  -H "Authorization: Bearer $SPHYNX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timeout_seconds": 900, "idle_timeout_seconds": 600}'

Identity: sphynx_id and os

Every session runs as one identity, a consistent device fingerprint. On the session object sphynx_id names that identity and os is the operating system it presents.

  • Pass os (windows, mac or linux) to get a new identity of that system. Leave it out for a random one.
  • Pass the sphynx_id of an earlier session to come back as the same device, with the same fingerprint.
  • The two cannot be combined: an identity already has an operating system.
  • An identity is the device, not its state. Cookies and storage are not kept between sessions: every session starts with none.
curl
# Come back as the same device
curl -s -X POST "$SPHYNX_URL/v1/sessions" \
  -H "Authorization: Bearer $SPHYNX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sphynx_id": "sx_ab12cd34"}'

An unknown sphynx_id fails with 422 sphynx_id_not_found.

Proxies

proxy.type decides where the session's traffic leaves from.

TypeExitFields
noneDirect datacenter egress. The default
residentialA residential address in the country you pickcountry, default us
externalYour own proxyserver (required), username, password

With a residential or external proxy the exit IP is fixed for the whole session, and the browser's timezone, geolocation and WebRTC addresses are set from that exit IP.

The proxy on a session object never includes credentials. usage.proxy_bytes counts the bytes through the proxy in both directions and is 0 with none. Setup and errors: Proxies.

Locators

Wherever a call targets an element it takes a locator: exactly one of three fields.

FieldMeaningExample
selectorCSS selectorform button[type=submit]
xpathXPath//table[@id='prices']//tr[2]/td[3]
textVisible text, case-insensitive substringSign in

The first match is used. Two locators on one target is 400 invalid_request. A click, fill, hover or element screenshot whose locator matches nothing fails with element_not_found.

One /actions body that uses each locator once:

Three steps, three locators
{
  "actions": [
    { "type": "fill", "selector": "#email", "value": "me@example.com" },
    { "type": "fill", "xpath": "//input[@name='password']", "value": "hunter2" },
    { "type": "click", "text": "Sign in" }
  ]
}

POST/v1/sessions/{id}/elements returns a unique selector and an absolute xpath for every element it lists, and either can be passed straight back. Action steps, /elements and the MCP tools accept all three fields. Selections in /extract and element screenshots take selector or xpath.

Tabs

A session starts with one tab and can open more. Calls without tab_id use the active tab: the most recently opened tab, or the first tab if none was opened through the API. A tab the page opens itself, with target="_blank" or window.open, does not become the active tab. Every drive call brings its tab to the front first. See Tabs.

One drive call at a time

/navigate, /elements, /actions, /extract and /screenshot are drive calls. On one session they run one at a time. A second call waits up to 3 s for the first to finish, then fails with 409 session_in_use. Retry it.

  • To run several steps with nothing in between, send them as one /actions call. It takes up to 50 steps.
  • An agent run takes its turn one step at a time, so your own calls on the same session interleave with it.
  • click and hover steps take about 1.5 to 4 s each, so a long /actions call holds the session for that long. Timings are under Actions.
  • Different sessions do not wait for each other.

Next