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.
| Type | Exit | Fields |
|---|---|---|
none | Direct datacenter egress | |
residential | A residential address in one country | country, default us |
external | Your own proxy | server (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 -s "$SPHYNX_URL/v1/proxy/countries" \
-H "Authorization: Bearer $SPHYNX_API_KEY"{ "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"}}'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" },
}),
});
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=60,
)
session = res.json()The session comes back with the proxy it is using.
{
"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 -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.
{ "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 -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 -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.jpgSee 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.
{
"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
| HTTP | Code | When |
|---|---|---|
| 422 | unsupported_country | country is not in GET /v1/proxy/countries |
| 422 | proxy_invalid | A bad proxy object, such as external without server |
| 502 | proxy_unreachable | Could not connect through the proxy |
| 503 | residential_unavailable | Residential 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.