SPHYNX
esc
  • Loading
Open console

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, closed or error.

  • close_reasonstring or null

    null while the session is active. Then released, timeout, idle_timeout, browser_closed, browser_crashed or launch_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, mac or linux.

  • proxyobject

    The proxy the session uses. It never includes credentials.

    • typestring

      none, residential or external.

    • countrystring

      The exit country of a residential proxy.

    • serverstring

      The address of an external proxy.

  • 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_seconds runs out.

  • ended_attimestamp or null

    When the session ended. null while 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. 0 with proxy.type none.

  • 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.

The session object
{
  "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/sessions

Returns 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

      none is direct datacenter egress.

    • countryISO 3166-1 alpha-2, lowercasedefaultus

      residential only. Codes come from List proxy countries.

    • serverstring

      external only, and required there. host:port or http(s)://host:port.

    • usernamestring

      external only.

    • passwordstring

      external only.

  • 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
  }'
Body · your own proxy
{
  "proxy": {
    "type": "external",
    "server": "proxy.example.com:8000",
    "username": "u",
    "password": "p"
  }
}
Body · come back as the same device
{
  "sphynx_id": "sx_ab12cd34",
  "proxy": { "type": "residential", "country": "us" }
}
201
{
  "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
curl -s "$SPHYNX_URL/v1/sessions/$SESSION" \
  -H "Authorization: Bearer $SPHYNX_API_KEY"
200 · an ended session
{
  "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/sessions

Returns 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_cursor of the previous page.

Response

  • datalist
  • next_cursorstring or null

    Pass it as cursor to get the next page. null on the last page.

curl
curl -s "$SPHYNX_URL/v1/sessions?status=active&limit=20" \
  -H "Authorization: Bearer $SPHYNX_API_KEY"
200
{
  "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
curl -s -X DELETE "$SPHYNX_URL/v1/sessions/$SESSION" \
  -H "Authorization: Bearer $SPHYNX_API_KEY"

List regions

GET/v1/regions

Returns 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
curl -s "$SPHYNX_URL/v1/regions" \
  -H "Authorization: Bearer $SPHYNX_API_KEY"
200
{
  "data": [
    {
      "code": "eu-west",
      "name": "Europe West",
      "country": "fr"
    }
  ]
}

List proxy countries

GET/v1/proxy/countries

Returns 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
curl -s "$SPHYNX_URL/v1/proxy/countries" \
  -H "Authorization: Bearer $SPHYNX_API_KEY"
200
{
  "data": ["us", "gb", "de"]
}

Errors

Creating a session can fail with any of these. The shape is the same as everywhere else: see Errors.

HTTPCodeWhen
400invalid_requestMalformed JSON, unknown field, bad value. details.field says where
401unauthorizedMissing or invalid API key
422unknown_regionregion is not in the region list
422sphynx_id_not_foundNo such sphynx_id
422unsupported_countryproxy.country is not in the proxy country list
422proxy_invalidBad proxy object
422unsafe_urlstart_url is not http/https, or is a private, loopback or link-local address
429concurrency_limitToo many live sessions for this key. Retry-After is set
500internalOur fault. Send us the request_id
502proxy_unreachableCould not connect through the proxy
502session_launch_failedThe browser failed to start
502navigation_failedstart_url could not be loaded: DNS failure, connection refused, TLS error
503capacity_unavailableThe host is full. Retry-After is set
503residential_unavailableResidential proxy is not configured or not reachable
504navigation_timeoutstart_url did not load in 30 s

The other calls on this page can fail with:

HTTPCodeWhen
400invalid_requestA bad status, limit or cursor when listing
401unauthorizedMissing or invalid API key
404session_not_foundNo such session for this key, on get and delete
500internalOur fault. Send us the request_id