residential.mdx

title	Residential Proxies

Residential proxies route traffic through real residential IP addresses. They support advanced targeting options including city, state, and operating system.

Configuration

Create a residential proxy with a target country:

import { Kernel } from '@onkernel/sdk';
const kernel = new Kernel();

const proxy = await kernel.proxies.create({
  type: 'residential',
  name: 'my-us-residential',
  config: {
    country: 'US'
  }
});

const browser = await kernel.browsers.create({
  proxy_id: proxy.id
});

import kernel
client = kernel.Kernel()

proxy = client.proxies.create(
    type='residential',
    name='my-us-residential',
    config={
        'country': 'US'
    }
)

browser = client.browsers.create(
    proxy_id=proxy.id
)

Configuration Parameters

• country - ISO 3166 country code. Must be provided when providing other targeting options.
• state - Two-letter state code. Only supported for US.
• city - City name (lowercase, no spaces, e.g., sanfrancisco, newyork).
• zip - US ZIP code (5 digits). Conflicts with city and state.
• asn - Autonomous System Number. Conflicts with city and state.

Advanced Targeting Examples

Kernel recommends using the least-specific targeting configuration that works for your use case. The more specific a configuration, the less available IPs there are, increasing the chance of a slow connection or no available connection (no_peer connection error).

Target by City

Route traffic through a specific city:

const proxy = await kernel.proxies.create({
  type: 'residential',
  name: 'la-residential',
  config: {
    country: 'US',
    state: 'CA',
    city: 'los_angeles'
  }
});

proxy = client.proxies.create(
    type='residential',
    name='la-residential',
    config={
        'country': 'US',
        'state': 'CA',
        'city': 'los_angeles'
    }
)

If the city name is not matched, the API will return the best 10 city names from the state to help you find the correct city identifier.

Target by State

Route traffic through a specific state:

const proxy = await kernel.proxies.create({
  type: 'residential',
  name: 'ny-residential',
  config: {
    country: 'US',
    state: 'NY'
  }
});

proxy = client.proxies.create(
    type='residential',
    name='ny-residential',
    config={
        'country': 'US',
        'state': 'NY'
    }
)

If the state name is not matched, the API will return the most-available 10 states.

Target by ASN

Route traffic through a specific Autonomous System Number (ISP):

const proxy = await kernel.proxies.create({
  type: 'residential',
  name: 'comcast-residential',
  config: {
    country: 'US',
    asn: 'AS7922'
  }
});

proxy = client.proxies.create(
    type='residential',
    name='comcast-residential',
    config={
        'country': 'US',
        'asn': 'AS7922'
    }
)

If the ASN is not matched, the API will return the most-available 10 examples.