How to configure a custom proxy for an Apify Actor

A custom route can be supplied in an Apify Actor input or through an SDK ProxyConfiguration with proxy_urls. The Actor schema determines whether Console exposes the proxy field. The proxy changes the network path; the Actor still owns parsing, retries and record validation.

Check the Actor before changing its route

The Apify proxy guide and own-proxy guide make two boundaries explicit. In Console, custom proxy URLs are available only when the Actor's input schema exposes the Proxy and browser configuration section. In the SDK, proxy_urls or new_url_function supplies custom URLs to ProxyConfiguration. Check the Actor schema before designing a migration around an input field.

This example suits Python developers maintaining an Actor or its caller with an authorized proxy URL. It requires Python 3.12 or a compatible interpreter, apify 4.0.2, httpx 0.28.1, and a proxy endpoint allowed for the intended target. The test ran on Python 3.12.0, macOS 26.5.2, arm64.

It uses HTTPX, not a browser, and does not need an Apify cloud token or start a cloud Actor run. For a local SDK check, Apify's Actor.create_proxy_configuration() accepts proxy_urls in an Actor context. The returned configuration is the same object used by an Actor.

Warning: Exposed proxy credentials allow unauthorized traffic and charges. The live check sends one IP-echo request through the configured proxy and may incur supplier traffic charges. Use a disposable, low-volume route and an authorized echo endpoint.

Inject the proxy URL through a temporary secret-manager binding rather than shell history or a committed file. Revoke temporary credentials after the check. The script closes its HTTP client and local Actor context on exit.

Install the pinned versions from PyPI: apify 4.0.2 and PyPI: httpx 0.28.1:

python3.12 -m pip install "apify==4.0.2" "httpx[socks]==0.28.1"

Use http://<USERNAME>:<PASSWORD>@<HOST>:<PORT> for an authenticated HTTP proxy: <HOST> and <PORT> identify the provider endpoint; <USERNAME> and <PASSWORD> are its credentials. Percent-encode reserved characters in both credential values. The scheme describes the proxy connection, even when the target uses HTTPS.

Set PROXY_URL through a runtime secret manager or process supervisor. Optionally set ROUTE_CHECK_URL to an IP-echo service and EXPECTED_EXIT_IP to an independently known exit; omit the latter when unknown. Save the script as route-check.py and inject the secret through runtime configuration:

import asyncio
import os
import sys
from ipaddress import ip_address

import httpx
from apify import Actor


PROXY_URL = os.getenv("PROXY_URL", "").strip()
ROUTE_CHECK_URL = os.getenv("ROUTE_CHECK_URL", "https://api.ipify.org").strip()
EXPECTED_EXIT_IP = os.getenv("EXPECTED_EXIT_IP", "").strip()
SESSION_ID = "catalog_route_check"
REQUEST_TIMEOUT_SECONDS = 20.0


async def main() -> None:
    if not PROXY_URL:
        raise SystemExit("PROXY_URL is required")

    async with Actor:
        try:
            configuration = await Actor.create_proxy_configuration(proxy_urls=[PROXY_URL])
            selected_url = await configuration.new_url(session_id=SESSION_ID)
            if not selected_url:
                raise ValueError("No proxy URL was selected")

            async with httpx.AsyncClient(proxy=selected_url, timeout=REQUEST_TIMEOUT_SECONDS) as client:
                response = await client.get(ROUTE_CHECK_URL)
            response.raise_for_status()
            exit_ip = ip_address(response.text.strip())
            if EXPECTED_EXIT_IP and exit_ip != ip_address(EXPECTED_EXIT_IP):
                raise ValueError("Observed exit did not match expected address")
            print({"route_status": response.status_code, "exit_ip_valid": True, "expected_exit_checked": bool(EXPECTED_EXIT_IP)})
        except Exception as error:
            print(f"Proxy check failed ({type(error).__name__}); verify the endpoint and echo response", file=sys.stderr)
            raise SystemExit(1) from None

if __name__ == "__main__":
    asyncio.run(main())

Run the script:

python3.12 route-check.py

By default the script checks ipify, whose endpoint returns a plain-text IP address. A run on 2026-10-02 through an authenticated residential HTTP proxy, without EXPECTED_EXIT_IP, printed this line after the Apify SDK log lines:

{'route_status': 200, 'exit_ip_valid': True, 'expected_exit_checked': False}

The response body is parsed as an IP address to reject an error page or malformed value. When EXPECTED_EXIT_IP is set, the observed address must match. The address itself is omitted from routine output. The example logs only status and validation flags. The except block sits inside async with Actor, so a failure prints only the exception class and exits with code 1; without it, the Actor context logs the full traceback and exits with code 91.

The same run also checked three failures: an unreachable proxy printed "Proxy check failed (ConnectError); verify the endpoint and echo response", a wrong EXPECTED_EXIT_IP printed the same message with ValueError, and a missing PROXY_URL stopped before any request. All three exited with code 1. This single request through the SDK-selected URL may incur supplier traffic charges. Use a low-volume disposable route and an authorized target; the run does not prove a cloud Actor run or target permission.

A missing PROXY_URL exits before any network request. An unreachable or invalid endpoint raises an HTTP transport error. Confirm the supplier endpoint and credentials without logging values.

HTTPX applies the configured 20-second timeout to network-operation inactivity phases; it is not a total job deadline. The example sends one request and does not retry authentication failures.

Keep the Actor result testable

Run one item before a batch and define the record contract first. For a product observation, that may be a product ID, price, currency and source timestamp. Store the Actor run ID, target URL, response phase and field validation result with the sample.

A run can be marked successful while its output is empty, a challenge page or the wrong record shape. A target denial can also leave the proxy configuration untouched. Record the failing phase before changing suppliers or retry policy.

Choose session behavior with the workload

Apify documents that the same session identifier can keep a proxy IP across connections, but session behavior depends on proxy type. Treat the provider's session lifetime as a variable to verify. A residential label alone does not establish session continuity.

Price valid records, then decide

Apify Proxy and an external pool sit in different billing boundaries. The Apify pricing page, checked on 2026-10-02, lists these rates:

An Actor using an external proxy avoids the residential line but may still record external data transfer for the traffic it sends out of the platform. The run's usage breakdown shows which lines applied. As an upper bound, 500 GB through a provider package at USD 2.75/GB plus USD 0.18/GB transfer costs USD 1,465 on Business, compared with USD 3,500 on Apify residential.

Compare valid records, not GB alone. Run the same target slice through both routes and record traffic, failed attempts, retries, and valid records. Actor compute units, storage, and any Apify Store price stay the same under both routes and do not change the network difference.

Apify's proxy documentation restricts connecting to Apify Proxy from an external client to paid plans. That is a different direction from an Actor connecting to a buyer-owned proxy, and the restriction does not apply to every custom-proxy setup. The browser agent proxy cost comparison shows the same calculation for browser platforms.

If the job needs a managed extractor, a raw proxy may leave too much application work in the Actor. Keep that choice separate from the question of whether a buyer-owned route is technically accepted. For browser-specific routing, use the Playwright proxy guide.

Check the target's terms, robots guidance where relevant, rate limits and personal-data obligations before running the Actor. An external proxy changes transport and supplier control; it does not authorize collection.

ProxyLaneTraffic never expires

Premium residential proxies
From $2/GB

Scale your workflows with the tools you already use. Rotating or sticky sessions up to 72 hours.

Try 350 MB for $1.95 View plans