Proxies

Proxy support allows browser Session traffic to be routed through a specified proxy server. HTTP, HTTPS, and SOCKS5 proxies are supported, with optional authentication.

Create a Proxy

POST /v1/proxies
X-API-Key: <api_key>

{
  "name": "US Proxy",        // required, name
  "type": "http",            // required: "http" | "https" | "socks5"
  "host": "proxy.example.com",  // required
  "port": 8080,              // required
  "username": "user",        // optional, auth username
  "password": "pass",        // optional, auth password
  "country": "US"            // optional, country code (2 letters)
}

# Returns
{
  "id": "prx_xxxx",
  "name": "US Proxy",
  "type": "http",
  "host": "proxy.example.com",
  "port": 8080,
  "country": "US",
  "isHealthy": null,
  "lastCheckedAt": null,
  "createdAt": "2024-01-01T00:00:00Z"
}

List Proxies

GET /v1/proxies
X-API-Key: <api_key>

# Returns proxy list with health status

Delete a Proxy

DELETE /v1/proxies/:id
X-API-Key: <api_key>

# Returns 204 No Content

Test a Proxy

Test proxy connectivity, returns latency in milliseconds:

POST /v1/proxies/:id/test
X-API-Key: <api_key>

# Returns
{
  "healthy": true,
  "latencyMs": 253,
  "checkedAt": "2024-01-01T00:00:00Z"
}

# or on failure
{
  "healthy": false,
  "error": "Connection refused",
  "checkedAt": "2024-01-01T00:00:00Z"
}

Using a Proxy in a Session

const session = await client.sessions.create({
  proxyId: 'prx_xxxx',  // specify proxy
});

// All traffic for this Session will be routed through the proxy

Proxy Types