How to use Residential Proxy?

Nimble Residential Proxy provides access to a global network of premium residential IPs through a single BackConnect gateway. Built for developers who need reliable, high-performance proxy infrastructure without managing IP lists.

Proxy service requires KYC verification and is not available for self-service accounts.Contact our team to request access.

When to use

Use the Residential Proxy when you need to:

Access geo-restricted content: View content as it appears in different countries
Avoid IP blocking: Rotate through residential IPs for reliable access
Monitor pricing: Check prices and availability across different regions
Collect SERP data: Gather search results from various locations
Test localization: Verify how content appears to users in different regions
Protect brand: Monitor web presence and detect unauthorized use

Residential Proxy uses real residential IPs from ISPs worldwide, providing the most reliable and undetectable proxy solution.

Connection format

http://account-{accountName}-pipeline-{pipelineName}:{pipelinePassword}@ip.nimbleway.com:7000

What are Pipelines?

A pipeline groups and directs requests through Nimble Proxy to a relevant proxy peer. Every request to Nimble Proxy flows through a pipeline, and every account comes with a default pipeline. Users can create multiple pipelines, depending on the size of their account. Pipelines serve two main functions:

Marking a business use case - reports and statistics can be filtered to a particular pipeline, making it easy to view how the total data transfer, requests, spending, and success rate for a particular use case. Some examples include:
- A business that collects E-commerce data may choose to make a dedicated pipeline for each data source, such as Amazon, Walmart, Home Depot, etc.
- An organization that gathers SERP data may choose to create a pipeline for different goals, such as competitor monitoring, search term tracking, paid and SEM monitoring, etc.
- A team that performs brand protection can create a pipeline for each client/brand they manage.
Setting defaults - Pipelines contain default settings that are inherited by the requests they oversee, and become especially useful when using Authenticated IPs, where parameters cannot be set manually in the request body and must be configured within the pipeline. Some of the parameters that can be set on the pipeline level include:
- IP rotation (rotating/fixed interval)
- Country, State, and City geotargeting
- Optimization engine profile

How do I configure a pipeline?

In the Dashboard, click on the “Pipelines” page in the left navigation menu.

To create a new pipeline, click “+Add Pipeline” on the right-hand button.
Pipelines can be disabled and/or archived by clicking the three-dot menu handle in the relevant pipeline’s row, and then “Disable Pipeline” or “Archive Pipeline”.
To modify a pipeline, click anywhere on the pipeline row to enter the pipeline details page. Then click on the “Settings” tab to view and edit the pipeline settings.

Core parameters

Required parameters

Parameter	Description	Example
`accountName`	Your company gateway name	mycompany
`pipelineName`	Pipeline to use (default: “residential”)	residential
`pipelinePassword`	Your pipeline authentication credential	your-password

Optional parameters

Add these to your connection string using hyphens:

Parameter	Description	Format
`country`	Target specific country	`country-{countryCode}`
`state`	Target US or CA states	`state-{stateCode}`
`city`	Target specific city	`city-{cityName}`
`session`	Maintain sticky session	`session-{sessionId}`
`geosession`	Geo-consistent session (advanced)	`geosession-{sessionId}`

Usage

Basic proxy request

Send requests through residential proxy:

curl -vvv -x http://account-accountName-pipeline-pipelineName:[email protected]:7000 \
  https://ipinfo.io/json

Country targeting

Route requests through specific countries:

use ISO Alpha-2 Country Codes i.e. US, DE, GB

import requests

# Target United States
proxies = {
    'http': 'http://account-accountName-pipeline-pipelineName-country-US:[email protected]:7000',
    'https': 'https://account-accountName-pipeline-pipelineName-country-US:[email protected]:7000'
}

response = requests.get('https://ipinfo.io/json', proxies=proxies)
print(f"Country: {response.json()['country']}")

State targeting (US & CA only)

Target specific US states:

use ISO Alpha-2 Country Codes i.e. NY, AZ, CA

import requests

# Target California
proxies = {
    'http': 'http://account-accountName-pipeline-pipelineName-country-US-state-CA:[email protected]:7000',
    'https': 'https://account-accountName-pipeline-pipelineName-country-US-state-CA:[email protected]:7000'
}

response = requests.get('https://ipinfo.io/json', proxies=proxies)
print(f"State: {response.json()['region']}")

City targeting

Target specific cities for precise location control:

import requests

# Target New York
proxies = {
    'http': 'http://account-accountName-pipeline-pipelineName-city-new_york:[email protected]:7000',
    'https': 'https://account-accountName-pipeline-pipelineName-city-new_york:[email protected]:7000'
}

response = requests.get('https://ipinfo.io/json', proxies=proxies)
print(f"City: {response.json()['city']}")

Replace spaces from city names with underscore (e.g,New York becomes new_york).

Sticky sessions

Maintain the same IP across multiple requests:

import requests

# Use session ID to maintain same IP
session_id = "mysession123"
proxies = {
    'http': f'http://account-accountName-pipeline-pipelineName-session-{session_id}:[email protected]:7000',
    'https': f'http://account-accountName-pipeline-pipelineName-session-{session_id}:[email protected]:7000'
}

# First request
response1 = requests.get('https://ipinfo.io/json', proxies=proxies)
ip1 = response1.json()['ip']

# Second request - uses same IP
response2 = requests.get('https://example.com', proxies=proxies)

print(f"Both requests used IP: {ip1}")

Session behavior:

Sessions remain active for 10 minutes after last request
Session IDs can be up to 32 alphanumeric characters
If IP goes offline, a new IP is automatically assigned

Combined targeting and sessions

Combine geotargeting with sticky sessions:

import requests

# Sticky session with US targeting
proxies = {
    'http': 'http://account-accountName-pipeline-pipelineName-country-US-state-NY-session-mysession:[email protected]:7000',
    'https': 'https://account-accountName-pipeline-pipelineName-country-US-state-NY-session-mysession:[email protected]:7000'
}

# Multiple requests maintain same New York IP
for i in range(3):
    response = requests.get('https://ipinfo.io/json', proxies=proxies)
    print(f"Request {i+1}: {response.json()['city']}, {response.json()['region']}")

Geo-sessions (advanced)

Maintain geographic proximity and ISP consistency across rotations:

import requests

# Geo-session requires 16-32 character session ID
proxies = {
    'http': 'http://account-accountName-pipeline-pipelineName-country-US-geosession-mysession12345678:[email protected]:7000',
    'https': 'https://account-accountName-pipeline-pipelineName-country-US-geosession-mysession12345678:[email protected]:7000'
}

response = requests.get('https://ipinfo.io/json', proxies=proxies)
print(response.text)

Geo-session features:

Max IP proximity stays 15km from of original location
Same ISP/ASN across rotations when possible
Session persists up to 10 days
World-wide, optimized performance in US
Requires session ID of 16-32 characters

Authentication methods

Username & password

Include credentials in every request (default method):

http://account-{accountName}-pipeline-{pipelineName}:{pipelinePassword}@ip.nimbleway.com:7000

IP allowlist

Authenticate by trusted IP addresses without credentials:

Add your IP to pipeline allowlist in Nimble dashboard
Configure custom port (9000-10000)
Send requests without username/password:

curl -vvv -x http://ip.nimbleway.com:9000 https://ipinfo.io/json

Learn More About Authentication

Detailed guide to authentication methods and configuration

Response format

Successful response

When requesting https://ipinfo.io/json:

{
  "ip": "203.0.113.45",
  "city": "Los Angeles",
  "region": "California",
  "country": "US",
  "loc": "34.0522,-118.2437",
  "org": "AS12345 Example ISP",
  "timezone": "America/Los_Angeles"
}

Error responses

Code	Meaning	Solution
407	Authentication failed	Verify account name, pipeline, and password
525	No IP available for location	Try different location or remove filtering
401	IP not in allowlist	Add your IP to pipeline allowlist
403	Pipeline disabled or quota reached	Check dashboard for pipeline status

Complete Response Codes

View all response codes and troubleshooting steps

Best practices

Choose appropriate rotation

Use rotating IPs (default) for:

Web scraping at scale
Rate limit distribution
Maximum IP diversity

Use sticky sessions for:

Multi-step workflows
Login flows
Shopping cart sessions

Configure timeouts

Set appropriate timeouts for proxy requests:

# Recommended timeout settings
response = requests.get(
    'https://example.com',
    proxies=proxies,
    timeout=45  # 45 seconds recommended
)

Handle IP rotation

Plan for IP changes in sticky sessions:

import requests
from requests.exceptions import ProxyError

def make_request_with_retry(url, proxies, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.get(url, proxies=proxies, timeout=45)
            return response
        except ProxyError:
            print(f"Attempt {attempt + 1} failed, retrying...")
            continue
    raise Exception("Max retries exceeded")

Monitor quota usage

Track your proxy usage to avoid hitting limits:

Check dashboard for real-time usage
Set up alerts for quota thresholds
Plan request volume within limits

Common use cases

E-commerce price monitoring

Monitor prices across different regions:

import requests

countries = ['US', 'GB', 'DE', 'FR']

for country in countries:
    proxies = {
        'http': f'http://account-accountName-pipeline-pipelineName-country-{country}:[email protected]:7000',
        'https': f'http://account-accountName-pipeline-pipelineName-country-{country}:[email protected]:7000'
    }

    response = requests.get('https://shop.example.com/product/123', proxies=proxies)
    print(f"{country} price: {extract_price(response.text)}")

SERP data collection

Collect search results from multiple locations:

import requests

locations = [
    {'country': 'US', 'state': 'CA'},
    {'country': 'US', 'state': 'NY'},
    {'country': 'GB'}
]

for loc in locations:
    if 'state' in loc:
        proxy_url = f"http://account-accountName-pipeline-pipelineName-country-{loc['country']}-state-{loc['state']}:[email protected]:7000"
    else:
        proxy_url = f"http://account-accountName-pipeline-pipelineName-country-{loc['country']}:[email protected]:7000"

    proxies = {'http': proxy_url, 'https': proxy_url}
    response = requests.get('https://www.google.com/search?q=example', proxies=proxies)
    # Process SERP data

Multi-step automation

Maintain session through login and workflow:

import requests

session_id = "workflow123"
proxies = {
    'http': f'http://account-accountName-pipeline-pipelineName-country-US-session-{session_id}:[email protected]:7000',
    'https': f'http://account-accountName-pipeline-pipelineName-country-US-session-{session_id}:[email protected]:7000'
}

# Step 1: Login
login_response = requests.post('https://example.com/login',
                               data={'user': 'test', 'pass': 'test'},
                               proxies=proxies)

# Step 2: Navigate (same IP)
page_response = requests.get('https://example.com/dashboard', proxies=proxies)

# Step 3: Action (same IP)
action_response = requests.post('https://example.com/action',
                                data={'action': 'submit'},
                                proxies=proxies)

Limitations

Geographic coverage

Global: Residential IPs available in 195+ countries
State targeting: US and CA only
City targeting: Major cities worldwide
Geo-sessions: World-wide, optimized performance in US

Session limits

Session duration: 10 minutes of inactivity
Geo-session duration: Up to 10 days
Session ID length: Maximum 32 characters
Geo-session ID length: 16-32 characters (minimum 16)

Request limits

Timeout: Recommended 40-45 seconds
Concurrent connections: Varies by plan
Quota: Based on your subscription plan

Next steps

Explore related Proxy features:

Authentication

Setup authentication methods

Geotargeting Guide

Advanced location targeting

Session Control

Manage IP rotation

Unlocker Proxy

Get started in minutes

Introduction

Web Tools

Agentic

How to use Residential Proxy?

When to use

Connection format

What are Pipelines?

How do I configure a pipeline?

Core parameters

Required parameters

Optional parameters

Usage

Authentication methods

Username & password

IP allowlist

Learn More About Authentication

Response format

Successful response

Error responses

Complete Response Codes

Best practices

Choose appropriate rotation

Configure timeouts

Handle IP rotation

Monitor quota usage

Common use cases

E-commerce price monitoring

SERP data collection

Multi-step automation

Limitations

Geographic coverage

Session limits

Request limits

Next steps

Authentication

Geotargeting Guide

Session Control

Unlocker Proxy

Introduction

Web Tools

Agentic

​When to use

​Connection format

​What are Pipelines?

​How do I configure a pipeline?

​Core parameters

​Required parameters

​Optional parameters

​Usage

​Authentication methods

​Username & password

​IP allowlist

Learn More About Authentication

​Response format

​Successful response

​Error responses

Complete Response Codes

​Best practices

​Choose appropriate rotation

​Configure timeouts

​Handle IP rotation

​Monitor quota usage

​Common use cases

​E-commerce price monitoring

​SERP data collection

​Multi-step automation

​Limitations

​Geographic coverage

​Session limits

​Request limits

​Next steps

Authentication

Geotargeting Guide

Session Control

Unlocker Proxy

When to use

Connection format

What are Pipelines?

How do I configure a pipeline?

Core parameters

Required parameters

Optional parameters

Usage

Authentication methods

Username & password

IP allowlist

Response format

Successful response

Error responses

Best practices

Choose appropriate rotation

Configure timeouts

Handle IP rotation

Monitor quota usage

Common use cases

E-commerce price monitoring

SERP data collection

Multi-step automation

Limitations

Geographic coverage

Session limits

Request limits

Next steps