API reference
Sessions
Create, read, list and end browser sessions.
A session is one running browser. Create it once, then connect a client to it, drive it over HTTP or hand it to an agent. It runs until you delete it, one of its two timeouts passes or the browser exits.
The session object
Create, get and list return this object.
Fields
- idstring
The session ID.
- statusstring
active,closedorerror. - close_reasonstring or null
nullwhile the session is active. Thenreleased,timeout,idle_timeout,browser_closed,browser_crashedorlaunch_failed. - regionstring
The region the browser runs in.
- sphynx_idstring
The fingerprint identity the browser runs as. Pass it on a later create to come back as the same device. Cookies and storage are not kept between sessions.
- osstring
The operating system that identity presents:
windows,macorlinux. - proxyobject
The proxy the session uses. It never includes credentials.
- typestring
none,residentialorexternal. - countrystring
The exit country of a
residentialproxy. - serverstring
The address of an
externalproxy.
- timeout_secondsint
The absolute lifetime the session was created with.
- idle_timeout_secondsint
The idle timeout the session was created with.
- created_attimestamp
When the session was created.
- last_active_attimestamp
When the idle clock was last reset.
- expires_attimestamp
When
timeout_secondsruns out. - ended_attimestamp or null
When the session ended.
nullwhile it is active. - usageobject
What the session has used so far.
- browser_secondsint
Seconds since the browser started.
- proxy_bytesint
Bytes through the proxy, both directions.
0withproxy.typenone.
- cdp_urlstring
Only on create and on Create a connect token. The WebSocket address a CDP client connects to.
- live_view_urlstring
Only on create and on the token call. A page that shows the session live.
- token_expires_in_secondsint
Only on create and on the token call. How long the token in both URLs stays valid. The token is reusable until it expires.
{
"id": "sess_9f2c4b1e7a3d4c5f8e6b0a1d2c3e4f50",
"status": "active",
"close_reason": null,
"region": "eu-west",
"sphynx_id": "sx_ab12cd34",
"os": "mac",
"proxy": { "type": "residential", "country": "us" },
"timeout_seconds": 3600,
"idle_timeout_seconds": 300,
"created_at": "2026-11-21T10:00:00Z",
"last_active_at": "2026-11-21T10:00:04Z",
"expires_at": "2026-11-21T11:00:00Z",
"ended_at": null,
"usage": { "browser_seconds": 4, "proxy_bytes": 18233 }
}Create a session
POST/v1/sessionsReturns 201 with the session once the browser is ready. Every field is optional: an empty object works.
Body
- regionstringdefaultthe only region
Where the browser runs. Codes come from List regions.
- timeout_secondsint, 60–21600default3600
The absolute lifetime. The session ends this long after it was created.
- idle_timeout_secondsint, 30–3600default300
The session ends after this long with no CDP frame and no drive call.
- oswindows, mac or linuxdefaultrandom
Picks a fingerprint of that operating system.
- sphynx_idstring
Reuse the identity of an earlier session. Cannot be combined with
os. - proxyobject
How the browser reaches the internet.
- typenone, residential or externaldefaultnone
noneis direct datacenter egress. - countryISO 3166-1 alpha-2, lowercasedefaultus
residentialonly. Codes come from List proxy countries. - serverstring
externalonly, and required there.host:portorhttp(s)://host:port. - usernamestring
externalonly. - passwordstring
externalonly.
- start_urlstring, ≤2048
Loaded before the call returns. If it does not load, the call fails and no session is returned.
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 same sphynx_id comes back as the same device, with the same fingerprint. It starts with empty cookies and storage: those are not kept between sessions.
With start_url, a page that fails to load answers 502 navigation_failed and one that takes longer than 30 s answers 504 navigation_timeout. The session is ended, with status error and close_reason launch_failed.
The response is the session object, with cdp_url, live_view_url and token_expires_in_seconds.
curl -s -X POST "$SPHYNX_URL/v1/sessions" \
-H "Authorization: Bearer $SPHYNX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"os": "windows",
"proxy": {"type": "residential", "country": "de"},
"timeout_seconds": 900
}'const res = await fetch(`${process.env.SPHYNX_URL}/v1/sessions`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SPHYNX_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
os: "windows",
proxy: { type: "residential", country: "de" },
timeout_seconds: 900,
}),
});
const session = await res.json();import os
import requests
res = requests.post(
f"{os.environ['SPHYNX_URL']}/v1/sessions",
headers={"Authorization": f"Bearer {os.environ['SPHYNX_API_KEY']}"},
json={
"os": "windows",
"proxy": {"type": "residential", "country": "de"},
"timeout_seconds": 900,
},
timeout=60,
)
session = res.json(){
"proxy": {
"type": "external",
"server": "proxy.example.com:8000",
"username": "u",
"password": "p"
}
}{
"sphynx_id": "sx_ab12cd34",
"proxy": { "type": "residential", "country": "us" }
}{
"id": "sess_9f2c4b1e7a3d4c5f8e6b0a1d2c3e4f50",
"status": "active",
"close_reason": null,
"region": "eu-west",
"sphynx_id": "sx_ab12cd34",
"os": "windows",
"proxy": { "type": "residential", "country": "de" },
"timeout_seconds": 900,
"idle_timeout_seconds": 300,
"created_at": "2026-11-21T10:00:00Z",
"last_active_at": "2026-11-21T10:00:00Z",
"expires_at": "2026-11-21T10:15:00Z",
"ended_at": null,
"usage": { "browser_seconds": 0, "proxy_bytes": 0 },
"cdp_url": "wss://api.example/.../cdp?token=...",
"live_view_url": "https://api.example/.../view?token=...",
"token_expires_in_seconds": 1800
}Get a session
GET/v1/sessions/{id}Returns the session. Ended sessions stay readable. Reading a session does not reset its idle clock.
Path
- idstringrequired
The session ID.
The response is the session object, without cdp_url, live_view_url and token_expires_in_seconds.
curl -s "$SPHYNX_URL/v1/sessions/$SESSION" \
-H "Authorization: Bearer $SPHYNX_API_KEY"{
"id": "sess_9f2c4b1e7a3d4c5f8e6b0a1d2c3e4f50",
"status": "closed",
"close_reason": "idle_timeout",
"region": "eu-west",
"sphynx_id": "sx_ab12cd34",
"os": "mac",
"proxy": { "type": "none" },
"timeout_seconds": 3600,
"idle_timeout_seconds": 300,
"created_at": "2026-11-21T10:00:00Z",
"last_active_at": "2026-11-21T10:02:10Z",
"expires_at": "2026-11-21T11:00:00Z",
"ended_at": "2026-11-21T10:07:10Z",
"usage": { "browser_seconds": 430, "proxy_bytes": 0 }
}List sessions
GET/v1/sessionsReturns your sessions, newest first, ended ones included.
Query
- statusactive, closed or error
Only sessions with this status.
- limitint, 1–100default20
How many sessions to return.
- cursorstring
The
next_cursorof the previous page.
Response
- datalist
- next_cursorstring or null
Pass it as
cursorto get the next page.nullon the last page.
curl -s "$SPHYNX_URL/v1/sessions?status=active&limit=20" \
-H "Authorization: Bearer $SPHYNX_API_KEY"{
"data": [
{
"id": "sess_9f2c4b1e7a3d4c5f8e6b0a1d2c3e4f50",
"status": "active",
"close_reason": null,
"region": "eu-west",
"sphynx_id": "sx_ab12cd34",
"os": "mac",
"proxy": { "type": "residential", "country": "us" },
"timeout_seconds": 3600,
"idle_timeout_seconds": 300,
"created_at": "2026-11-21T10:00:00Z",
"last_active_at": "2026-11-21T10:00:04Z",
"expires_at": "2026-11-21T11:00:00Z",
"ended_at": null,
"usage": {
"browser_seconds": 4,
"proxy_bytes": 18233
}
}
],
"next_cursor": null
}Delete a session
DELETE/v1/sessions/{id}Ends the session and closes its browser. Returns 204 with no body. Safe to repeat: deleting a session that has already ended is not an error.
Path
- idstringrequired
The session ID.
curl -s -X DELETE "$SPHYNX_URL/v1/sessions/$SESSION" \
-H "Authorization: Bearer $SPHYNX_API_KEY"List regions
GET/v1/regionsReturns the regions a session can run in. Pass a code as region when you create a session.
Response
- datalist
One entry per region.
- codestring
The value to pass as
region. - namestring
The name of the region.
- countrystring
The country the region is in.
curl -s "$SPHYNX_URL/v1/regions" \
-H "Authorization: Bearer $SPHYNX_API_KEY"{
"data": [
{
"code": "eu-west",
"name": "Europe West",
"country": "fr"
}
]
}List proxy countries
GET/v1/proxy/countriesReturns the country codes a residential proxy accepts. The list is empty when residential proxy is not configured.
Response
- datalist of strings
Lowercase ISO 3166-1 alpha-2 codes.
curl -s "$SPHYNX_URL/v1/proxy/countries" \
-H "Authorization: Bearer $SPHYNX_API_KEY"{
"data": ["us", "gb", "de"]
}Errors
Creating a session can fail with any of these. The shape is the same as everywhere else: see Errors.
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_request | Malformed JSON, unknown field, bad value. details.field says where |
| 401 | unauthorized | Missing or invalid API key |
| 422 | unknown_region | region is not in the region list |
| 422 | sphynx_id_not_found | No such sphynx_id |
| 422 | unsupported_country | proxy.country is not in the proxy country list |
| 422 | proxy_invalid | Bad proxy object |
| 422 | unsafe_url | start_url is not http/https, or is a private, loopback or link-local address |
| 429 | concurrency_limit | Too many live sessions for this key. Retry-After is set |
| 500 | internal | Our fault. Send us the request_id |
| 502 | proxy_unreachable | Could not connect through the proxy |
| 502 | session_launch_failed | The browser failed to start |
| 502 | navigation_failed | start_url could not be loaded: DNS failure, connection refused, TLS error |
| 503 | capacity_unavailable | The host is full. Retry-After is set |
| 503 | residential_unavailable | Residential proxy is not configured or not reachable |
| 504 | navigation_timeout | start_url did not load in 30 s |
The other calls on this page can fail with:
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_request | A bad status, limit or cursor when listing |
| 401 | unauthorized | Missing or invalid API key |
| 404 | session_not_found | No such session for this key, on get and delete |
| 500 | internal | Our fault. Send us the request_id |