Proxy & Geolocation

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, agents 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",
)

const result = await client.runTask({
  body: {
    prompt: "Get the price of this product",
    url: "https://shop.example.co.uk/product/123",
    proxy_location: "RESIDENTIAL_GB",
  },
});

curl -X POST "https://api.skyvern.com/v1/run/tasks" \
  -H "x-api-key: $SKYVERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Get the price of this product",
    "url": "https://shop.example.co.uk/product/123",
    "proxy_location": "RESIDENTIAL_GB"
  }'

For agents, set a default proxy_location when creating the agent, 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
)

// Set default proxy on workflow
const workflow = await client.createWorkflow({
  body: {
    json_definition: {
      title: "UK Price Monitor",
      proxy_location: "RESIDENTIAL_GB",
      workflow_definition: {...},
    },
  },
});

// Override for a specific run (takes priority over workflow default)
const run = await client.runWorkflow({
  body: {
    workflow_id: "wpid_123456789",
    parameters: {...},
    proxy_location: "RESIDENTIAL_DE",  // This run uses Germany instead
  },
});

# Set default proxy on workflow
curl -X POST "https://api.skyvern.com/v1/workflows" \
  -H "x-api-key: $SKYVERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "json_definition": {
      "title": "UK Price Monitor",
      "proxy_location": "RESIDENTIAL_GB",
      "workflow_definition": {...}
    }
  }'

# Override for a specific run (takes priority over workflow default)
curl -X POST "https://api.skyvern.com/v1/run/workflows" \
  -H "x-api-key: $SKYVERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wpid_123456789",
    "parameters": {...},
    "proxy_location": "RESIDENTIAL_DE"
  }'

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"
)

const session = await client.createBrowserSession({
  body: {
    timeout: 60,
    proxy_location: "RESIDENTIAL_DE",
  },
});

curl -X POST "https://api.skyvern.com/v1/browser_sessions" \
  -H "x-api-key: $SKYVERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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.

Value	Country	Timezone
`RESIDENTIAL`	United States	America/New_York
`RESIDENTIAL_ISP`	United States	America/New_York
`US-CA`	California, US	America/Los_Angeles
`US-NY`	New York, US	America/New_York
`US-TX`	Texas, US	America/Chicago
`US-FL`	Florida, US	America/New_York
`US-WA`	Washington, US	America/Los_Angeles
`RESIDENTIAL_AR`	Argentina	America/Argentina/Buenos_Aires
`RESIDENTIAL_AU`	Australia	Australia/Sydney
`RESIDENTIAL_BR`	Brazil	America/Sao_Paulo
`RESIDENTIAL_CA`	Canada	America/Toronto
`RESIDENTIAL_DE`	Germany	Europe/Berlin
`RESIDENTIAL_ES`	Spain	Europe/Madrid
`RESIDENTIAL_FR`	France	Europe/Paris
`RESIDENTIAL_GB`	United Kingdom	Europe/London
`RESIDENTIAL_IE`	Ireland	Europe/Dublin
`RESIDENTIAL_IN`	India	Asia/Kolkata
`RESIDENTIAL_IT`	Italy	Europe/Rome
`RESIDENTIAL_JP`	Japan	Asia/Tokyo
`RESIDENTIAL_MX`	Mexico	America/Mexico_City
`RESIDENTIAL_NL`	Netherlands	Europe/Amsterdam
`RESIDENTIAL_NZ`	New Zealand	Pacific/Auckland
`RESIDENTIAL_PH`	Philippines	Asia/Manila
`RESIDENTIAL_KR`	South Korea	Asia/Seoul
`RESIDENTIAL_SA`	Saudi Arabia	Asia/Riyadh
`RESIDENTIAL_TR`	Türkiye	Europe/Istanbul
`RESIDENTIAL_ZA`	South Africa	Africa/Johannesburg
`NONE`	No proxy	N/A

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

Scenario	Recommended	Why
General scraping	`RESIDENTIAL`	Large pool, good success rate
Login / authenticated sessions	`RESIDENTIAL_ISP`	Static IPs prevent session invalidation
Region-specific content	`RESIDENTIAL_XX`	Routes through that country
Sites that block rotating IPs	`RESIDENTIAL_ISP`	Static IPs have better reputation
Internal tools / testing	`NONE`	Skip proxy overhead
Multi-step checkout flows	`RESIDENTIAL_ISP` + browser session	IP 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"},
)

// US state (California)
const result = await client.runTask({
  body: {
    prompt: "Get local pricing",
    url: "https://example.com",
    proxy_location: { country: "US", subdivision: "CA" },
  },
});

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

// City without subdivision (London)
const result = await client.runTask({
  body: {
    prompt: "Get local pricing",
    url: "https://example.com",
    proxy_location: { country: "GB", city: "London" },
  },
});

curl -X POST "https://api.skyvern.com/v1/run/tasks" \
  -H "x-api-key: $SKYVERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Get local pricing",
    "url": "https://example.com",
    "proxy_location": {
      "country": "US",
      "subdivision": "CA",
      "city": "San Francisco"
    }
  }'

Field	Type	Description
`country`	string	Required. ISO 3166-1 alpha-2 code (e.g., `US`, `GB`, `DE`).
`subdivision`	string	ISO 3166-2 subdivision code without country prefix (e.g., `CA` for California, `NY` for New York).
`city`	string	City 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

Error	Reason	How to Fix
`NoProxyAvailable`	Requested city/state is temporarily unavailable in the proxy pool	Broaden target (city → state → country), use `RESIDENTIAL_ISP`, or retry later
Site still blocks requests	Bot 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 issues	Isolate whether proxy is causing failures	Set `proxy_location: "NONE"` to bypass proxy entirely

For sites with aggressive bot detection, combine residential proxies with the techniques in CAPTCHA & Bot Bypass. Need a location that’s not available? Get help in the Skyvern Discord community to request new proxy pools.

Getting Started

Core Features

Browser Automation

Agent Blocks

Handling Authentication

Optimization

Going to Production

Debugging

Self-Hosted Deployment

Proxy & Geolocation

Set `proxy_location`

Proxy location options

Choosing the right proxy type

State and city targeting

Troubleshooting

Next steps

Captcha & Bot Detection

Browser Sessions

​Set proxy_location

​Proxy location options

​Choosing the right proxy type

​State and city targeting

​Troubleshooting

​Next steps

Captcha & Bot Detection

Browser Sessions

Set `proxy_location`

Proxy location options

Choosing the right proxy type

State and city targeting

Troubleshooting

Next steps