109 lines
3.6 KiB
Plaintext
109 lines
3.6 KiB
Plaintext
---
|
||
title: Proxy & Geo Targeting
|
||
slug: running-tasks/proxy-location
|
||
---
|
||
|
||
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.
|
||
|
||
| Proxy value | Region |
|
||
| --- | --- |
|
||
| `RESIDENTIAL` | Random US residential IP (default) |
|
||
| `RESIDENTIAL_ISP` | United States ISP proxy pool (static IPs, useful for sites that distrust rotating pools) |
|
||
| `RESIDENTIAL_AR` | Argentina |
|
||
| `RESIDENTIAL_AU` | Australia |
|
||
| `RESIDENTIAL_BR` | Brazil |
|
||
| `RESIDENTIAL_CA` | Canada |
|
||
| `RESIDENTIAL_DE` | Germany |
|
||
| `RESIDENTIAL_ES` | Spain |
|
||
| `RESIDENTIAL_FR` | France |
|
||
| `RESIDENTIAL_GB` | United Kingdom |
|
||
| `RESIDENTIAL_IE` | Ireland |
|
||
| `RESIDENTIAL_IN` | India |
|
||
| `RESIDENTIAL_IT` | Italy |
|
||
| `RESIDENTIAL_JP` | Japan |
|
||
| `RESIDENTIAL_MX` | Mexico |
|
||
| `RESIDENTIAL_NL` | Netherlands |
|
||
| `RESIDENTIAL_NZ` | New Zealand |
|
||
| `RESIDENTIAL_TR` | Türkiye |
|
||
| `RESIDENTIAL_ZA` | South Africa |
|
||
| `NONE` | Disable proxy routing (traffic originates from Skyvern’s US datacenters) |
|
||
|
||
## 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.
|
||
|
||
```json
|
||
{
|
||
"country": "US",
|
||
"subdivision": "CA",
|
||
"city": "Los Angeles"
|
||
}
|
||
```
|
||
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```python
|
||
from skyvern import Skyvern
|
||
|
||
client = Skyvern(api_key="YOUR_API_KEY")
|
||
|
||
# Run with a GeoTarget (California)
|
||
client.run_workflow(
|
||
workflow_id="wpid_workflow_permanent_id",
|
||
proxy_location={"country": "US", "subdivision": "CA"},
|
||
)
|
||
|
||
# Run with the ISP pool
|
||
client.run_workflow(
|
||
workflow_id="wpid_workflow_permanent_id",
|
||
proxy_location="RESIDENTIAL_ISP",
|
||
)
|
||
```
|
||
|
||
## 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.
|