SPHYNX
esc
  • Loading
Open console

Guides

Proxies

Choose where a session's traffic leaves from, a residential address by country or your own proxy.

At the end you have a session whose traffic leaves from the country or the proxy you chose. You need an API key and, for your own proxy, its address and credentials.

Pick a type

The proxy object on session create has a type. Without it the session uses none.

TypeExitFields
noneDirect datacenter egress
residentialA residential address in one countrycountry, default us
externalYour own proxyserver (required), username, password

Use a residential exit

GET/v1/proxy/countries lists the countries you can ask for, as 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"] }

Create the session with one of them.

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"}}'

The session comes back with the proxy it is using.

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": 3600,
  "idle_timeout_seconds": 300,
  "created_at": "2026-11-21T10:00:00Z",
  "last_active_at": "2026-11-21T10:00:00Z",
  "expires_at": "2026-11-21T11:00:00Z",
  "ended_at": null,
  "usage": { "browser_seconds": 0, "proxy_bytes": 0 },
  "cdp_url": "wss://api.example/v1/sessions/sess_9f2c.../cdp?token=...",
  "live_view_url": "https://api.example/v1/sessions/sess_9f2c.../view?token=...",
  "token_expires_in_seconds": 1800
}

Bring your own proxy

Set type to external and give the proxy's server as host:port or http(s)://host:port. username and password are optional. This snippet builds the body with jq so the credentials come from the environment.

curl
curl -s -X POST "$SPHYNX_URL/v1/sessions" \
  -H "Authorization: Bearer $SPHYNX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg user "$PROXY_USERNAME" --arg pass "$PROXY_PASSWORD" '{
    proxy: {
      type: "external",
      server: "proxy.example.com:8000",
      username: $user,
      password: $pass
    }
  }')"

The proxy on a session object never includes credentials.

proxy, as returned
{ "type": "external", "server": "proxy.example.com:8000" }

What the exit IP changes

With a residential or external proxy the exit IP is fixed for the whole session: every request from that browser leaves from the same address. The browser's timezone, geolocation and WebRTC addresses are set from that exit IP, so you do not set them yourself.

Keep the device, keep the country

Pass the sphynx_id of an earlier session together with a proxy to come back as the same device from the same country. The device comes back, its state does not: cookies and storage are not kept between sessions.

curl
curl -s -X POST "$SPHYNX_URL/v1/sessions" \
  -H "Authorization: Bearer $SPHYNX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sphynx_id": "sx_ab12cd34", "proxy": {"type": "residential", "country": "us"}}'

One capture through a proxy

The stateless screenshot takes the same proxy object, for a single image of a page as seen from another country.

curl
curl -s -X POST "$SPHYNX_URL/v1/screenshot" \
  -H "Authorization: Bearer $SPHYNX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "proxy": {"type": "residential", "country": "gb"}
  }' \
  | jq -r .image_base64 | base64 -d > example.jpg

See how much went through

usage.proxy_bytes on a session counts the bytes through its proxy in both directions. It is 0 with none. GET/v1/usage gives the month's total for the key, split by proxy type.

200 · GET /v1/usage
{
  "period_start": "2026-11-01T00:00:00Z",
  "period_end": "2026-12-01T00:00:00Z",
  "sessions": 412,
  "browser_seconds": 98211,
  "proxy_bytes": { "residential": 5120334411, "external": 88213 },
  "concurrent_sessions": 3,
  "concurrency_limit": 5
}

What can go wrong

HTTPCodeWhen
422unsupported_countrycountry is not in GET /v1/proxy/countries
422proxy_invalidA bad proxy object, such as external without server
502proxy_unreachableCould not connect through the proxy
503residential_unavailableResidential proxy is not configured or not reachable

An empty list from GET /v1/proxy/countries means residential is not configured on this deployment.

Next

  • Sessions: every create field, including proxy.
  • Concepts: identities and how a session's exit and fingerprint fit together.
  • Screenshots: capture a page with or without a session.