Proxies

A saved Proxy is a reusable traffic configuration for browser Runtimes. Choose a custom endpoint, a managed rotating proxy, or a managed static lease. Attach a saved Proxy through Runtimes.

Choose a proxy type

Create a custom Proxy

1
const proxy = await bctrl.proxies.create({
2
  type: "custom",
3
  name: "acme-residential",
4
  protocol: "http",
5
  host: "proxy.acme.com",
6
  port: 8080,
7
  username: process.env.PROXY_USER,
8
  password: process.env.PROXY_PASS,
9
});

protocol is "http" or "socks5". You can also provide a proxy url instead of separate host and port fields. dnsResolution can be "local" or "proxy"; udpMode can be "disabled", "auto", or "required".

Create a managed rotating Proxy

Managed rotating Proxies use one of the provider pools. pool1 supports country, region, city, ISP, IP family, and preference targeting. pool2 supports country, state, city, and device targeting.

1
const rotating = await bctrl.proxies.create({
2
  type: "managed-rotating",
3
  name: "us-rotating",
4
  pool: "pool1",
5
  country: "us",
6
  preference: "balanced",
7
  rotation: "rotating",
8
});

Common rotating fields:

Browse managed proxy locations

Search the provider-backed geo catalog when you need an exact geoId for a managed rotating Proxy:

1
const geo = await bctrl.proxies.geo.list({
2
  country: "us",
3
  type: "city",
4
  q: "new york",
5
});
6
7
const geoId = geo.data[0]?.geoId;

Use the customer-facing locations catalog to browse the locations available for a managed pool:

1
const locations = await bctrl.proxies.locations.list({
2
  pool: "pool1",
3
  country: "us",
4
});
5
6
for (const location of locations.data) {
7
  console.log(location.name, location.geoId, location.pools);
8
}

Both catalog clients support list() and iter() with the same pagination filters: cursor, limit, q, country, region, type, and pool.

Discover static pools before creating a managed static Proxy:

1
const pools = await bctrl.proxies.pools.list({
2
  country: "us",
3
  available: true,
4
});
5
6
const pool = await bctrl.proxies.pools.get(pools.data[0].id);

Create a managed static Proxy

1
const leased = await bctrl.proxies.create({
2
  type: "managed-static",
3
  name: "us-residential",
4
  poolId: pool.id,
5
  autoRenew: true,
6
});

Managed static Proxies may be provisioning, active, provisioning_failed, expired, or renewal_failed. The assigned IP, location, pricing, and expiration fields become available when the lease is provisioned.

Attach a Proxy to a Runtime

Pass the saved Proxy ID in browser Runtime configuration:

1
const runtime = await bctrl.runtimes.create({
2
  config: {
3
    proxy: proxy.id,
4
  },
5
});

The Proxy is selected when the Runtime starts. Changes to a saved Proxy apply to future Runtime starts.

Inspect and test a Proxy

1
const current = await bctrl.proxies.get(proxy.id);
2
3
const result = await bctrl.proxies.test(proxy.id);
4
console.log(result.ok, result.exitIp, result.country);
5
6
await bctrl.proxies.update(proxy.id, {
7
  name: "acme-residential-eu",
8
  country: "de",
9
});
10
11
await bctrl.proxies.delete(proxy.id);

Proxy credentials are write-only. Responses expose hasPassword for custom Proxies rather than returning the password.

Proxy resource fields

All Proxy responses include:

The remaining fields depend on type. Custom Proxies expose connection details and hasPassword; managed rotating Proxies expose their pool and targeting configuration; managed static Proxies additionally expose lease status and assignment details.

Use bctrl.proxies.list() and iter() to enumerate saved Proxies. Use bctrl.proxies.pools.list(), iter(), and get() to browse managed pools.