For an aiohttp request, pass the HTTP proxy through session.get(..., proxy=proxy_url). Keep a session alive across related requests, set bounded timeouts, and verify the destination observation. aiohttp 3.14.5 was tested here; it ignores proxy environment variables by default.
Reviewed and locally tested: October 12, 2026. Version and route observations below describe the stated test environment. A working local route does not establish a provider’s public exit, country, anonymity, speed, or uptime.
Start with the tested version
python -m pip install "aiohttp==3.14.5"The local tests ran with Python 3.12.14 on Windows. Check your application’s interpreter and dependency constraints before adopting the pin. HTTPX and aiohttp expose different proxy APIs: copying a client constructor from another library can create a plausible configuration that never affects the request.
Make one request with explicit proxy and TLS settings
import asyncio, os, ssl
import aiohttp
def tls_context(ca_file=None):
return ssl.create_default_context(cafile=ca_file)
async def aiohttp_request(url, proxy_url=None, ca_file=None):
timeout=aiohttp.ClientTimeout(total=5, connect=2)
async with aiohttp.ClientSession(timeout=timeout, trust_env=False) as session:
async with session.get(url, proxy=proxy_url, ssl=tls_context(ca_file),
allow_redirects=False) as response:
return response.status, await response.json()
status, body = asyncio.run(aiohttp_request(
os.environ["CHECK_URL"], os.environ["PROXY_URL"]))
print({"status": status})Use a trusted endpoint returning JSON, and supply credentials through an environment value or secret manager. This helper reads the body before leaving the response context. It does not treat a JSON response or successful status as proof of a public proxy exit; compare the destination’s recorded observation with the direct call using proxy_url=None. Redirects are disabled to keep the check on one endpoint.
The session in this small diagnostic closes after the request. In a long-running application, create one session for a suitable lifetime and pass it to request functions. The aiohttp client quickstart explains response handling and connection reuse.
Choose authentication for the installed release
The tested example uses a proxy URL containing username/password credentials. Percent-encode each credential component and keep the resulting URL out of source control, logs and screenshots. Proxy authentication is separate from an API token used by the destination.
from urllib.parse import quote
proxy_url = "http://{}:{}@proxy.example:8080".format(
quote(os.environ["PROXY_USER"], safe=""),
quote(os.environ["PROXY_PASSWORD"], safe=""))Current 3.14 documentation deprecates the older proxy_auth argument, with removal planned for 4.0, and describes encode_basic_auth with proxy_headers for explicit headers. The URL form above was the form exercised in our fixture. For a migration, consult the installed version’s proxy support reference rather than silently carrying older BasicAuth examples forward.
Separate total and connection budgets
ClientTimeout(total=5, connect=2) sets a total request budget and a connection budget. Pool waiting can affect the connection budget when many requests share a connector. A timeout does not tell you whether authentication was correct or whether the API would have accepted the request. Use the ClientTimeout reference to choose values for your workload.
Avoid retrying every exception immediately. A failed credential needs a configuration fix; a bounded transient connection failure may justify a limited retry; a destination rate limit needs the destination’s policy. Record a sanitized failure class and attempt count without printing the proxy URL.
Enable environment inheritance only when you intend it
async with aiohttp.ClientSession(trust_env=True) as session:
async with session.get(os.environ["CHECK_URL"],
timeout=aiohttp.ClientTimeout(total=5)) as response:
print({"status": response.status})This is an alternative configuration path, not an addition to the explicit proxy helper. Our five-case matrix showed default sessions using the direct route, and sessions with trust_env=True honoring the proxy and matching NO_PROXY rule. Read the environment-variable matrix before applying shell-wide settings.
Measured HTTP and CONNECT behavior
| Case | Local observation |
|---|---|
| Authenticated HTTP proxy | Owned destination recorded the proxy route |
| HTTPS through HTTP CONNECT | Request passed with the disposable destination CA explicitly trusted |
| Untrusted destination certificate | Request rejected while certificate verification remained enabled |
| Proxy credentials at destination | Proxy-Authorization header absent |
The fixture connected only to owned loopback endpoints. It did not test an HTTPS connection to the proxy itself, TLS-in-TLS, SOCKS support, commercial exits, or throughput. An HTTP proxy tunneling an HTTPS destination is a different case from an https:// proxy endpoint; verify your exact transport against the current support reference.
Resolve the error at the responsible endpoint
A 407 points to proxy authentication; a destination 401 points to API authentication; a connection refusal points to reachability; a certificate failure points to trust or hostname validation. Confirm that all requests use the intended session. Compare HTTPX async setup when choosing a client, and use the error checklist for a repeatable incident record.
Frequently asked questions
Can I put proxy credentials in the destination Authorization header?
No. Destination Authorization authenticates to the API. Keep proxy credentials in the proxy configuration and the API token in the destination request configuration.
Does a session route every request automatically?
Verify the configuration path used by each call. This guide supplies proxy= at request level, while environment inheritance is a separate, deliberate choice.
Verify one client before increasing workload
Return to Proxy Setup and Developer Guides for adjacent clients. Use the proxy verification checklist to record a direct baseline and the destination’s observation. When that is repeatable, compare Mexela proxy locations against the actual destination and location requirements.
Download the developer examples
Download the developer examples ZIP for the locally tested Python clients, environment checks, CI route-check files and native PHP cURL helper. The n8n workflow is a separate illustrative reference: it was not imported or executed in n8n. Read the included README for runtime versions, setup and the limits of each check.
ZIP SHA-256: 3a43f7d1e6cbb9b2917dbcf88aaa8fe1a2733c33326187cb89c9a9119aad3e20. Keep real proxy credentials and destination secrets in your approved secret store; they are absent from this archive. Start with one approved destination and compare its observation with a direct baseline.
Versioned Python aiohttp source files
Use the Python aiohttp folder in the public source repository for the example, setup instructions, exact dependency versions and a sanitized test summary. The repository is a dated snapshot of owned examples; its loopback checks do not certify a commercial endpoint or every application configuration.