Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
Add new Proxy granular targeting to docs (#4177)
Marc Kelechava8a3d7694de7e
diff --git a/fern/docs.yml b/fern/docs.ymlindex 006bab32d..3922a6b79 100644--- a/fern/docs.yml+++ b/fern/docs.yml@@ -83,6 +83,8 @@ navigation:path: running-tasks/cancel-runs.mdx- page: Webhooks FAQpath: running-tasks/webhooks-faq.mdx+ - page: Proxy & Geo Targeting+ path: running-tasks/proxy-location.mdx- page: Advanced Settings for taskshidden: truepath: running-tasks/advanced-features.mdxdiff --git a/fern/running-tasks/proxy-location.mdx b/fern/running-tasks/proxy-location.mdxnew file mode 100644index 000000000..dc99b5b7e--- /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.mdxindex 1936aa79a..3598ac353 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 sParameter: `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.mdxindex de7dfcf52..859e26ca1 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