Skip to main content
Many websites serve different content based on your location—prices in local currency, region-locked inventory, or outright access blocks. Others detect and block datacenter IPs, treating them as bots. Skyvern’s residential proxy network routes your browser through real consumer IP addresses in 20 countries, so sites see a legitimate local visitor.
Proxy routing is only available in Skyvern Cloud. Self-hosted deployments require your own proxy infrastructure.

​
Set proxy_location

Pass proxy_location when creating or running tasks, workflows or browser sessions to route browser traffic through a specific region. For tasks: 
result = await client.run_task(
    prompt="Get the price of this product",
    url="https://shop.example.co.uk/product/123",
    proxy_location="RESIDENTIAL_GB",
)
For workflows, set a default proxy_location when creating the workflow, then you can also override it when starting the run: 
# Set default proxy on workflow
workflow = await client.create_workflow(
    json_definition={
        "title": "UK Price Monitor",
        "proxy_location": "RESIDENTIAL_GB",
        "workflow_definition": {...}
    }
)

# Override for a specific run (takes priority over workflow default)
run = await client.run_workflow(
    workflow_id="wpid_123456789",
    parameters={...},
    proxy_location="RESIDENTIAL_DE"  # This run uses Germany instead
)
For browser sessions, set proxy_location at creation. All tasks in that session use the same proxy IP, which matters for sites that track IP consistency across a login session—switching IPs mid-session often triggers security warnings or logouts.
Browser profiles don’t store proxy settings. Profiles save cookies, localStorage, and authentication state—but not the proxy used to create them. When reusing a profile, explicitly set proxy_location to match the original session, or sites may detect the IP mismatch and invalidate your session.
session = await client.create_browser_session(
    timeout=60,
    proxy_location="RESIDENTIAL_DE"
)

​
Proxy location options

Use these enum values for country-level targeting. Each routes through a residential proxy pool in that country.
ValueCountryTimezone
RESIDENTIALUnited StatesAmerica/New_York
RESIDENTIAL_ISPUnited StatesAmerica/New_York
US-CACalifornia, USAmerica/Los_Angeles
US-NYNew York, USAmerica/New_York
US-TXTexas, USAmerica/Chicago
US-FLFlorida, USAmerica/New_York
US-WAWashington, USAmerica/Los_Angeles
RESIDENTIAL_ARArgentinaAmerica/Argentina/Buenos_Aires
RESIDENTIAL_AUAustraliaAustralia/Sydney
RESIDENTIAL_BRBrazilAmerica/Sao_Paulo
RESIDENTIAL_CACanadaAmerica/Toronto
RESIDENTIAL_DEGermanyEurope/Berlin
RESIDENTIAL_ESSpainEurope/Madrid
RESIDENTIAL_FRFranceEurope/Paris
RESIDENTIAL_GBUnited KingdomEurope/London
RESIDENTIAL_IEIrelandEurope/Dublin
RESIDENTIAL_INIndiaAsia/Kolkata
RESIDENTIAL_ITItalyEurope/Rome
RESIDENTIAL_JPJapanAsia/Tokyo
RESIDENTIAL_MXMexicoAmerica/Mexico_City
RESIDENTIAL_NLNetherlandsEurope/Amsterdam
RESIDENTIAL_NZNew ZealandPacific/Auckland
RESIDENTIAL_PHPhilippinesAsia/Manila
RESIDENTIAL_KRSouth KoreaAsia/Seoul
RESIDENTIAL_TRTürkiyeEurope/Istanbul
RESIDENTIAL_ZASouth AfricaAfrica/Johannesburg
NONENo proxy—
  • RESIDENTIAL is the default. It routes traffic through a random US residential IP.
  • RESIDENTIAL_ISP uses static ISP IPs instead of rotating residential IPs. Useful for sites that distrust rotating pools or require consistent IP addresses across requests.
  • NONE disables proxy routing entirely—traffic originates from Skyvern’s US datacenters. Useful for testing or internal tools.
Default behavior: If you don’t specify proxy_location, Skyvern uses RESIDENTIAL which routes through a random US residential IP. Each request may get a different IP from the pool. For consistent IPs, use RESIDENTIAL_ISP or browser sessions.
Timezone is automatically set: When using proxy_location, the browser’s timezone is set to match the proxy’s region. Sites that compare your IP’s geolocation against browser timezone for bot detection will see consistent data.

​
Choosing the right proxy type

ScenarioRecommendedWhy
General scrapingRESIDENTIALLarge pool, good success rate
Login / authenticated sessionsRESIDENTIAL_ISPStatic IPs prevent session invalidation
Region-specific contentRESIDENTIAL_XXRoutes through that country
Sites that block rotating IPsRESIDENTIAL_ISPStatic IPs have better reputation
Internal tools / testingNONESkip proxy overhead
Multi-step checkout flowsRESIDENTIAL_ISP + browser sessionIP consistency required
Use RESIDENTIAL_ISP for authenticated sessions. Sites that track IP consistency across a login session may flag accounts when IPs rotate mid-session. ISP proxies provide static IPs that don’t change during your task.

​
State and city targeting

For granular targeting—a specific US state, a city, or a country not in the presets—pass a GeoTarget object instead of an enum. 
# US state (California)
result = await client.run_task(
    prompt="Get local pricing",
    url="https://example.com",
    proxy_location={"country": "US", "subdivision": "CA"},
)

# US city (New York City)
result = await client.run_task(
    prompt="Get local pricing",
    url="https://example.com",
    proxy_location={"country": "US", "subdivision": "NY", "city": "New York"},
)

# City without subdivision (London)
result = await client.run_task(
    prompt="Get local pricing",
    url="https://example.com",
    proxy_location={"country": "GB", "city": "London"},
)
FieldTypeDescription
countrystringRequired. ISO 3166-1 alpha-2 code (e.g., US, GB, DE).
subdivisionstringISO 3166-2 subdivision code without country prefix (e.g., CA for California, NY for New York).
citystringCity name in English (e.g., San Francisco, London).
Supported countries: US, AR, AU, BR, CA, DE, ES, FR, GB, IE, IN, IT, JP, MX, NL, NZ, PH, TR, ZA
City/state targeting has limited availability. Proxy pools for specific cities or US states are smaller and may return NoProxyAvailable during high-demand periods. If this happens, broaden your target (city → state → country) or retry later.

​
Troubleshooting

ErrorReasonHow to Fix
NoProxyAvailableRequested city/state is temporarily unavailable in the proxy poolBroaden target (city → state → country), use RESIDENTIAL_ISP, or retry later
Site still blocks requestsBot detection beyond IP geolocation (fingerprinting, behavioral analysis)Use RESIDENTIAL_ISP for static IPs, match proxy to site’s region, add wait blocks between actions
Need to debug proxy issuesIsolate whether proxy is causing failuresSet proxy_location: "NONE" to bypass proxy entirely
For sites with aggressive bot detection, combine residential proxies with the techniques in Captcha & Bot Detection. Need a location that’s not available? Get help in the Skyvern Discord community to request new proxy pools.

​
Next steps

Captcha & Bot Detection

Combine proxies with anti-detection techniques

Browser Sessions

Maintain IP consistency across multi-step tasks