Use a custom proxy in Apify in one of two ways: enter your provider’s proxy URLs in an Actor’s Input tab when that Actor exposes Proxy and browser configuration, or create a proxy configuration in the Apify SDK and supply your URLs through proxy_urls (Python) or proxyUrls (JavaScript). Do not mix custom proxy URLs with Apify Proxy options in the same configuration.
This guide shows both paths, explains authentication and rotation decisions, and covers the errors that most often prevent an Actor from connecting.
Choose the setup that matches your Actor
| Method | Best for | Requirement | What you configure |
|---|---|---|---|
| Apify Console | A one-off run or a non-developer workflow | The Actor input schema must expose Proxy and browser configuration | Proxy URLs in the Actor’s Input form |
| Apify SDK | Repeatable jobs, CI, scheduled runs and dynamic rotation | The SDK version installed in your project | A proxy configuration containing your custom endpoints |
Apify’s documentation describes both routes in Using your own proxies. A proxy URL must come from the provider you selected. Its scheme, host, port, credentials and rotation behavior are provider-specific; do not copy Apify Proxy connection values into a third-party URL.
Before you add a proxy
- Obtain one or more working endpoint URLs from your proxy provider. Confirm whether it expects HTTP, HTTPS or SOCKS, and whether credentials are embedded in the URL or supplied separately.
- Check whether the provider rotates automatically, assigns a sticky session, limits concurrent connections or requires IP allow-listing.
- Keep usernames, passwords and tokens out of public repositories, Actor input examples, screenshots and logs. Use environment variables or Apify secrets where your project supports them.
- Decide whether the Actor needs one stable identity for a session or a pool of endpoints. A list lets the SDK select among URLs; it does not change the provider’s own rotation policy.
Method 1: configure your custom proxy in Apify Console
This route works only when the Actor author included the relevant fields in the input schema.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →#1 Best Overall
- Open the Actor in Apify Console and select the Input tab.
- Look for the section named Proxy and browser configuration.
- Enter the custom proxy URL or URLs supplied by your provider. Preserve the exact scheme, hostname, port and credential format required by that provider.
- Review any session, rotation or browser settings exposed by the Actor, then start the run.
- Inspect the run log and target site to confirm that requests are leaving through the expected endpoint.
If the section is missing, the documented Console route is not exposed for that Actor. You cannot add the field yourself from the run form; use the SDK route, choose an Actor that supports the input, or ask the Actor author to add proxy configuration to its schema.
What not to enter
Do not fill an external URL into Apify Proxy group or country fields and assume it becomes a custom proxy. Those controls are for Apify’s managed proxy service. Custom endpoints belong in the custom proxy URL field or SDK configuration.
Method 2: use custom proxies through the Python SDK
The Python SDK sequence is: create a proxy configuration with proxy_urls, request a URL with new_url(), and pass that URL to your crawler or HTTP client. The official example is documented in the Python proxy-management guide and the ProxyConfiguration reference. API names can vary by installed SDK version, so check the version-specific reference before copying code into production.
from apify import Actor
async def main():
proxy_cfg = await Actor.create_proxy_configuration(
proxy_urls=[
"http://proxy-1.example:8080",
"http://proxy-2.example:8080",
],
)
proxy_url = await proxy_cfg.new_url()
print(proxy_url)
# Pass proxy_url to the crawler or HTTP client used by your Actor.
if __name__ == "__main__":
import asyncio
asyncio.run(main())The hostnames above are illustrative and will not work. Replace them with endpoints from your provider. If credentials are required, use the provider’s documented URL format and load the value from a secret rather than hard-coding it.
Free tools Windows power users keep installed
One-click scans. No signup required.
Attach the generated URL to your HTTP client
The proxy configuration only produces the URL. Your HTTP library still needs to receive it using that library’s proxy setting. For example, an HTTP client may require a proxy argument for both HTTP and HTTPS requests, while a browser crawler may require a browser-launch or request-handler setting. Follow the client’s own API and verify that the generated URL is actually used.
Generate URLs dynamically
When the endpoint must be selected or built at request time, the Python API also documents new_url_function. Use it for provider-specific session IDs, signed URLs or a rotation algorithm. Keep the function’s output valid for the proxy client and avoid logging the returned credential-bearing URL.
Rank #2
- Used Book in Good Condition
JavaScript SDK configuration
In JavaScript, custom endpoints are supplied as proxyUrls. The option names and callback are documented in the JavaScript ProxyConfigurationOptions reference. The reference pages returned for this API identify JavaScript SDK 3.7 and Python SDK 4.0; treat those names as version-sensitive and verify your installed package.
import { Actor } from 'apify';
await Actor.init();
const proxyConfiguration = await Actor.createProxyConfiguration({
proxyUrls: [
'http://proxy-1.example:8080',
'http://proxy-2.example:8080',
],
});
const proxyUrl = await proxyConfiguration.newUrl();
console.log(proxyUrl);
// Supply proxyUrl to your crawler or HTTP client.
await Actor.exit();Some releases expose the configuration class or factory slightly differently. If this snippet does not match your package, open the reference for your installed version and retain the same conceptual sequence: provide proxyUrls, obtain a URL, then attach it to the client that makes the request. JavaScript also documents newUrlFunction for dynamic URL generation.
Do not combine custom URLs with Apify Proxy options
Custom proxies and Apify Proxy are separate modes. The JavaScript options reference states that custom proxies cannot be combined with Apify Proxy configuration options in one configuration; doing so causes an initialization error. In practice, choose one of these patterns:
- Custom mode: provide
proxyUrls(or Python’sproxy_urls) and omit Apify Proxy groups, country settings and other managed-service options. - Apify Proxy mode: use Apify’s managed endpoint and its account, group and country controls, without supplying custom URLs.
Apify’s Proxy documentation describes the managed service. Its hostname, port and password instructions do not automatically apply to an external provider. The page also warns that use of the Apify Proxy password is charged to the account and that the password is sent unencrypted when used with the documented HTTP protocol. Treat those statements as Apify Proxy-specific, not as properties of every proxy.
Credentials, schemes and sessions
Credentials in a URL
A provider may issue a URL such as http://user:password@host:port, but the exact format is not universal. URL-encode reserved characters in credentials when the provider requires it. Never paste a live credential into a public Actor README or a support ticket.
HTTP versus HTTPS versus SOCKS
Use the scheme your provider documents. An HTTPS target does not necessarily mean you should change an HTTP proxy URL to HTTPS; proxy transport and destination transport are separate choices. If your client does not support the supplied scheme, select a compatible client or endpoint.
Sticky sessions and rotation
Use a sticky endpoint when the target site requires a consistent IP across a login or multi-request workflow. Use rotating endpoints for workloads where distribution is intentional. Neither Apify nor the SDK can guarantee a provider’s geographic location, success rate or rotation interval; those are provider-side properties.
Testing and verification checklist
- Run a minimal request through one endpoint before launching a large crawl.
- Check the response status, redirect chain and TLS or certificate errors.
- Verify the observed public IP with an endpoint you trust, without exposing credentials in the request log.
- Test the same Actor without the proxy only if your rules and target permit it; this separates proxy failures from Actor failures.
- Start with one URL and low concurrency, then increase load while watching provider limits and Actor memory.
A successful TCP connection does not prove that the target will accept the request. Bot checks, authentication, geofencing and rate limits can still reject a valid proxy connection.
Troubleshooting custom-proxy errors
The Console has no proxy section
Cause: the Actor input schema does not define Proxy and browser configuration.
Fix: use the SDK with custom URLs, or select an Actor whose schema exposes the control. Do not assume every Actor supports Console proxy input.
Initialization fails when the Actor starts
Cause: custom URLs were combined with Apify Proxy groups, country options or another managed-proxy setting.
Fix: remove all Apify Proxy options when using custom endpoints, or remove custom URLs and configure Apify Proxy alone.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Authentication fails at the proxy
Cause: wrong credentials, an unescaped reserved character, an expired token or an IP allow-list that excludes the Actor’s egress address.
Fix: regenerate or validate the provider credential, URL-encode it as required, and check the provider’s allow-list and authentication documentation.
Connection refused or timed out
Cause: incorrect scheme or port, a blocked outbound connection, an exhausted provider pool or a dead endpoint.
Fix: test the endpoint independently, confirm the provider’s transport requirements, try another URL from the supplied pool and reduce concurrency until the provider confirms its limits.
The request reaches the site but is blocked
Cause: the destination detected the proxy, challenged the browser, enforced a region rule or applied a rate limit.
Fix: respect the site’s terms and robots policy, slow the crawl, keep a consistent session when required, and consult the proxy provider about the endpoint type and location. A custom proxy does not bypass a destination’s access controls.
Rank #4
SDK method or option is undefined
Cause: the example targets a different SDK release than the one installed.
Fix: check the versioned Python or JavaScript reference, confirm whether your release uses proxy_urls or proxyUrls, and update the code to that release’s factory and method names.
Recommended Free Tools
Performance, reliability and cost considerations
Proxy overhead comes from the provider and network path, not from a guaranteed Apify improvement. Measure latency and error rates with your own endpoints and target. Keep the initial concurrency conservative: a large parallel burst can exhaust provider limits, trigger destination throttling or create misleading timeout errors.
- Use a small, health-checked list instead of repeatedly sending traffic to a known-dead endpoint.
- Set client timeouts that are long enough for the target but finite, so failed proxies are replaced instead of hanging the run.
- Record a redacted endpoint identifier, status and timing; never record full credential-bearing URLs.
- Separate proxy costs from Apify Actor and compute costs when estimating a run. The supplied documentation does not establish a universal proxy price, performance gain or success rate.
Or skip the browser setup
If your task is creating screenshots of pages rather than routing an Apify crawl, ScreenshotNeo provides a direct website screenshot API and MCP server. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets; each cleanup step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP tools—take_screenshot, get_page_info and capture_pdf—let Claude, Cursor and other MCP clients request captures.
One request returns PNG, JPEG, WebP or PDF. The API supports full-page and element captures, device presets, retina scale, dark mode, custom CSS and JavaScript, clicks, waits, blocking rules, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, TTL caching, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call and a usage API. Every feature is on every plan: 1,000 shots monthly free with no card; paid plans start at $5 for 3,000 shots. See the ScreenshotNeo documentation for parameters.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSign up for the free ScreenshotNeo plan to get 1,000 screenshots a month without a card.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsFAQ
Can I use a custom proxy without Apify Proxy?
Yes. Supply your own endpoint URLs through the Actor’s exposed Console field or through the SDK configuration, and leave Apify Proxy options unset.
Does Apify provide the external proxy URLs?
No. A custom configuration uses endpoints supplied by a provider you select. Apify Proxy is a separate managed service.
Best Value
Can one Actor use different proxies for different requests?
Yes, if your SDK code requests a new URL and your crawler or HTTP client applies it per request or session. The exact hook depends on that client.
Are custom proxy URLs automatically validated?
Do not assume so. Perform a small test request and inspect connection, authentication and target responses before scaling a run.
Frequently Asked Questions
Can I use a custom proxy without Apify Proxy?
Yes. Supply your own endpoint URLs through the Actor’s exposed Console field or through the SDK configuration, and leave Apify Proxy options unset.
Does Apify provide the external proxy URLs?
No. A custom configuration uses endpoints supplied by a provider you select. Apify Proxy is a separate managed service.
Can one Actor use different proxies for different requests?
Yes, if your SDK code requests a new URL and your crawler or HTTP client applies it per request or session. The exact hook depends on that client.
Are custom proxy URLs automatically validated?
Do not assume so. Perform a small test request and inspect connection, authentication and target responses before scaling a run.
The Bottom Line
Use the Console only when the Actor exposes Proxy and browser configuration; otherwise create a Python or JavaScript proxy configuration with your provider’s URLs. Keep that custom mode separate from Apify Proxy settings, protect credentials, and validate one endpoint before increasing crawl volume.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
