From 8a3d7694de7ecfb7f9c560d9655f57f99bba2326 Mon Sep 17 00:00:00 2001 From: Marc Kelechava Date: Wed, 3 Dec 2025 09:06:25 -0800 Subject: [PATCH] Add new Proxy granular targeting to docs (#4177) --- fern/docs.yml | 2 + fern/running-tasks/proxy-location.mdx | 108 ++++++++++++++++++++++++++ fern/running-tasks/run-tasks.mdx | 7 +- fern/workflows/run-workflows.mdx | 10 +++ 4 files changed, 126 insertions(+), 1 deletion(-) create mode 100644 fern/running-tasks/proxy-location.mdx diff --git a/fern/docs.yml b/fern/docs.yml index 006bab32..3922a6b7 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -83,6 +83,8 @@ navigation: path: running-tasks/cancel-runs.mdx - page: Webhooks FAQ path: running-tasks/webhooks-faq.mdx + - page: Proxy & Geo Targeting + path: running-tasks/proxy-location.mdx - page: Advanced Settings for tasks hidden: true path: running-tasks/advanced-features.mdx diff --git a/fern/running-tasks/proxy-location.mdx b/fern/running-tasks/proxy-location.mdx new file mode 100644 index 00000000..dc99b5b7 --- /dev/null +++ b/fern/running-tasks/proxy-location.mdx @@ -0,0 +1,108 @@ +--- +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. diff --git a/fern/running-tasks/run-tasks.mdx b/fern/running-tasks/run-tasks.mdx index 1936aa79..3598ac35 100644 --- a/fern/running-tasks/run-tasks.mdx +++ b/fern/running-tasks/run-tasks.mdx @@ -64,7 +64,12 @@ With this mapping, if Skyvern encounters a login failure, the task output will s Parameter: `proxy_location` -Some websites block requests from certain countries. You can set a proxy location to route the browser traffic through. +Some websites lock content behind geo-fences. Override this parameter to route the browser through a residential proxy in a specific country, state, or city. + +- Use enum values such as `RESIDENTIAL_GB`, `RESIDENTIAL_DE`, or `RESIDENTIAL_ISP` for country-level pools. +- Send a GeoTarget object (e.g., `{"country": "US", "subdivision": "CA"}`) for granular U.S. states or cities. + +See [Proxy & Geo Targeting](/running-tasks/proxy-location) for the full list of options and sample API calls. ### 2FA Support (TOTP) - [totp_identifier](/api-reference/api-reference/agent/run-task#request.body.totp_identifier): Skyvern can receive the TOTP code and use this identifier to identify the code for authentication. diff --git a/fern/workflows/run-workflows.mdx b/fern/workflows/run-workflows.mdx index de7dfcf5..859e26ca 100644 --- a/fern/workflows/run-workflows.mdx +++ b/fern/workflows/run-workflows.mdx @@ -14,4 +14,14 @@ Find the API doc [here](/api-reference/api-reference/workflows/run-workflow) ### Parameters +#### proxy_location + +`proxy_location` works the same way it does for Task runs: + +- Defaults to `RESIDENTIAL` (random US residential proxy) +- Accepts any country preset like `RESIDENTIAL_GB` or the ISP pool `RESIDENTIAL_ISP` +- Accepts a GeoTarget object for granular state/city runs (e.g., `{"country": "US", "subdivision": "NY", "city": "Brooklyn"}`) + +Each run can override whatever is saved on the workflow definition. See [Proxy & Geo Targeting](/running-tasks/proxy-location) for the full option list and sample payloads. + ### Webhook