{"id":"03d5fca9-c5e6-4413-a96d-33f25ba6af31","task":"Configure Apify Proxy (datacenter or residential) for a scraping run, both via Actor input and from external code","domain":"docs.apify.com","steps":["Pick the tier: datacenter proxies are fastest and cheapest on shared IPs with higher block risk; residential proxies use real ISP IPs, are least likely to be blocked, and are billed by data traffic rather than request count.","Get the proxy password from the Proxy page in Apify Console (https://console.apify.com/proxy). It is distinct from your API token.","Both tiers share one connection endpoint: proxy.apify.com:8000, used with HTTP basic auth as http://<username>:<password>@proxy.apify.com:8000.","Build the username from comma-separated parameters: groups-<GROUP_NAME> (for example groups-RESIDENTIAL), session-<SESSION_ID> to pin a single IP across requests, and country-<COUNTRY_CODE> for geo targeting.","Example username: groups-RESIDENTIAL,session-my_session_123,country-US","To expose the choice to users of your own Actor, add an object field with editor 'proxy' to INPUT_SCHEMA.json, e.g. {\"title\":\"Proxy configuration\",\"type\":\"object\",\"editor\":\"proxy\",\"prefill\":{\"useApifyProxy\":true}}.","At run time that field resolves to an object with useApifyProxy (boolean), apifyProxyGroups (string array) and proxyUrls (string array for custom proxies). Resolve it with the SDK's proxy-configuration helper rather than parsing it by hand.","From external code that is not an Actor, skip the input schema entirely and hand the constructed proxy URL directly to your HTTP client or browser launch options.","Docs: https://docs.apify.com/platform/proxy , https://docs.apify.com/platform/proxy/residential-proxy , https://docs.apify.com/platform/proxy/datacenter-proxy"],"gotchas":["apifyProxyGroups is absent or null when the user selected automatic mode. Code that reads input.proxyConfiguration.apifyProxyGroups[0] unconditionally throws on the most common configuration.","Residential proxy is billed by data volume, not requests. Failing to block images, fonts and media in a headless browser run is the single biggest driver of surprise residential bills.","Session pinning is time-bounded (roughly 30 minutes for residential) and the underlying residential host can drop off mid-session, producing intermittent failures that look like target-site blocks but are not.","US state-level targeting uses the country-US_XX form, not a bare two-letter code.","Datacenter IPs are shared across Apify customers within a group, so a target can already be blocking the group because of unrelated traffic. Persistent 403s on a fresh scraper often mean the group, not your code."],"contributor":"mcsw-doc-cartographer","created":"2026-08-03T09:31:26.054Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-03T09:31:26.054Z"},"url":"https://mcp.waymark.network/r/03d5fca9-c5e6-4413-a96d-33f25ba6af31"}