How to route cloudscraper through a proxy

Route cloudscraper through a Requests-style proxy map on the session, then use that same session for an IP echo and an authorized target. Validate both responses before accepting a record. The IP check observes one request's exit; it does not prove that later connections keep the same IP or that a target accepts the request.

Prerequisites

• A maintained Python 3.12 interpreter. Python 3.12.14 is the current security release; its official release page notes that it is source-only. The local execution evidence records Python 3.12.0 as its test baseline only.
• An HTTP proxy endpoint with permission to use it
• A target URL that permits the requested test

This example was run with cloudscraper 1.2.71, the version published on PyPI when checked on 2026-09-29. Install that tested version in a virtual environment:

python -m pip install 'cloudscraper==1.2.71'

Route and validate a request

Store the proxy URL in a runtime secret binding named PROXY_URL. The value has the form http://<PROXY_USER>:<PROXY_PASSWORD>@<PROXY_HOST>:<PROXY_PORT>; percent-encode reserved characters in credentials. Do not place it in source control, a shell command, or debug logs. Set EXIT_CHECK_URL and TARGET_URL to override the public defaults during a permitted test. If you change TARGET_URL, also replace the hard-coded "Example Domain" marker in the target validation with text expected from that page.

Warning: Proxy credentials can expose account access if they reach logs or source control, and requests can consume metered traffic. Use a secret binding and an authorized test target. Rotate credentials if exposed, then remove the logged or committed copy.

An HTTP proxy's Basic credentials are not encrypted between the client and proxy. HTTPS on the target protects the target connection after the proxy tunnel; it does not protect the earlier proxy-authentication hop. Send credentials only over a trusted network path, or use a TLS-protected proxy endpoint supported by the deployment. cloudscraper may make extra requests while processing a challenge, so the two explicit checks below do not guarantee a total network-request count.

Save the following as cloudscraper-probe.py:

import ipaddress
import json
import os
from urllib.parse import urlsplit

import cloudscraper

PROXY_URL = os.environ["PROXY_URL"]
EXIT_CHECK_URL = os.environ.get("EXIT_CHECK_URL", "https://api.ipify.org?format=json")
TARGET_URL = os.environ.get("TARGET_URL", "https://example.com/")
TIMEOUT_SECONDS = 10
MAX_RESPONSE_BYTES = 65_536
PROXIES = {"http": PROXY_URL, "https": PROXY_URL}


def validate_proxy_url(proxy_url):
    parsed = urlsplit(proxy_url)
    if parsed.scheme != "http" or not parsed.hostname or not parsed.port:
        raise ValueError("PROXY_URL must be an HTTP proxy URL with a host and port")


class ProbeFailure(Exception):
    pass


def read_response(response, phase):
    if not 200 <= response.status_code < 300:
        raise ProbeFailure(f"{phase} returned HTTP {response.status_code}")

    chunks = []
    size = 0
    for chunk in response.iter_content(chunk_size=8192):
        if not chunk:
            continue
        size += len(chunk)
        if size > MAX_RESPONSE_BYTES:
            raise ProbeFailure(f"{phase} response exceeded the byte limit")
        chunks.append(chunk)
    return b"".join(chunks)


def request_body(scraper, url, phase):
    with scraper.get(
        url,
        proxies=PROXIES,
        timeout=TIMEOUT_SECONDS,
        allow_redirects=False,
        stream=True,
    ) as response:
        return read_response(response, phase)


def main():
    validate_proxy_url(PROXY_URL)
    with cloudscraper.create_scraper() as scraper:
        exit_body = request_body(scraper, EXIT_CHECK_URL, "exit check")
        exit_value = json.loads(exit_body)["ip"]
        exit_ip = ipaddress.ip_address(exit_value)

        target_body = request_body(scraper, TARGET_URL, "target").decode("utf-8", errors="replace")
        if "Example Domain" not in target_body:
            raise ProbeFailure("target content did not contain the expected marker")

    print(json.dumps({"exit_ip": str(exit_ip), "target_check": "passed"}))


if __name__ == "__main__":
    try:
        main()
    except ProbeFailure as error:
        print(f"Probe failed: {error}")
        raise SystemExit(1) from None
    except Exception as error:
        print(f"Probe failed ({type(error).__name__}); check proxy, status, and content separately.")
        raise SystemExit(1) from None

Run it with secrets already loaded by the deployment platform, local secret manager, or an untracked environment file. Do not type the authenticated URL as a command-line argument. Use an output file that does not yet exist if the runner captures the result.

python cloudscraper-probe.py

Expected output has an observed exit address and a passed target marker:

{"exit_ip":"<OBSERVED_EXIT_IP>","target_check":"passed"}

<OBSERVED_EXIT_IP> is a value returned by the configured echo endpoint, not a value to paste into the script. The request bodies are streamed and capped at 65,536 bytes. Each call passes timeout=10 to Requests, which applies to connection establishment and read-idle waiting. The read timeout measures the wait between bytes, not total response-transfer time, and neither Requests timeout is a wall-clock deadline for one call. A separate job deadline is needed to bound the whole job or sequence of requests.

The proxy scheme controls the connection to the proxy. An https:// target also uses TLS between the client and target through the proxy tunnel. This example accepts an HTTP proxy endpoint only; Requests verifies target certificates by default. A proxy endpoint using TLS needs separate configuration and certificate validation.

Check the failure layer

The cloudscraper project builds on Requests and adds challenge handling. A successful proxy request does not establish that a challenge will be accepted or that a collection is authorized. Follow the target's access policy and rate limits; a challenge page or incomplete body fails the content check even when the HTTP request returns successfully.

For a plain Requests baseline, use the Python Requests proxy guide. For proxy authentication failures, use HTTP 407 troubleshooting.

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