Add new Proxy granular targeting to docs (#4177)

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

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.

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.

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