Proxy & Geo Targeting

Skyvern Cloud routes browser traffic through a global pool of residential proxies. By default, workflows and tasks run from a random US residential IP (RESIDENTIAL). Override that per run when you need localized content, geo-fenced features, or tighter fraud protections.

This feature is only available in Skyvern Cloud today.

Country presets

Pass any of the following enum values to proxy_location. Each value pins the run to a residential pool in that country.

GeoTarget format (states & cities)

For any location that is not listed above—such as a specific US state or city—send a GeoTarget object instead of an enum. This is the same structure used in the UI’s GeoTarget picker.

1
{
2
  "country": "US",
3
  "subdivision": "CA",
4
  "city": "Los Angeles"
5
}

Field meanings:

• country (required): ISO 3166-1 alpha-2 code (e.g., US, GB)
• subdivision (optional): ISO 3166-2 code for a state/province (e.g., CA, NY, BC)
• city (optional): Free-form city name

Examples:

• Any US state: {"country": "US", "subdivision": "IL"}
• US city: {"country": "US", "subdivision": "NY", "city": "New York City"}
• Country-only targeting: {"country": "DE"} (useful when the country is not available as a preset yet)

When a subdivision or city is not available in the proxy pool, the run fails with NoProxyAvailable. Choose a broader target (e.g., country-only) or retry later.

Per-run overrides

proxy_location can be stored on the workflow definition, but every run (UI or API) can override it. The override only applies to that run and does not mutate the workflow.

cURL

$
curl -X POST "https://api.skyvern.com/v1/run/workflows" \
>
  -H "x-api-key: $API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "workflow_id": "wpid_workflow_permanent_id",
>
    "proxy_location": {
>
      "country": "US",
>
      "subdivision": "CA"
>
    }
>
  }'

Python SDK

1
from skyvern import Skyvern
2
3
client = Skyvern(api_key="YOUR_API_KEY")
4
5
# Run with a GeoTarget (California)
6
client.run_workflow(
7
    workflow_id="wpid_workflow_permanent_id",
8
    proxy_location={"country": "US", "subdivision": "CA"},
9
)
10
11
# Run with the ISP pool
12
client.run_workflow(
13
    workflow_id="wpid_workflow_permanent_id",
14
    proxy_location="RESIDENTIAL_ISP",
15
)

Availability & troubleshooting

• Proxy availability depends on upstream partners. During spikes, certain cities may be temporarily unavailable.
• If you receive NoProxyAvailable, retry with a broader GeoTarget (city → state → country) or switch to RESIDENTIAL_ISP.
• proxy_location: "NONE" is useful for testing because it removes proxy routing entirely.

Need something that is not listed here? Reach out to support so we can prioritize new pools.