Proxies

Route browser traffic through platform-managed residential proxies (`useProxy`) or bring-your-own proxies (`proxy` / `proxyId`). Managed bandwidth is billed in Credits; BYOP has no platform proxy bandwidth charge.

Managed residential proxy

Pass `useProxy: true` on Session / Scrape create — no Proxies resource required. Optional `proxyGeolocation`. Requires Credits balance > 0.

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

{
  "useProxy": true,
  "proxyGeolocation": { "country": "US", "city": "newyork" }
}

# Response includes proxyProvider / proxyGeolocation; credentials are never returned

Create a Proxy (BYOP)

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

// Managed
const managed = await client.sessions.create({
  useProxy: true,
  proxyGeolocation: { country: 'US' },
});

// BYOP by id
const byop = await client.sessions.create({
  proxyId: 'prx_xxxx',
});

Proxy Types (BYOP)