Mobile proxy¶

Every active device rental can include a credentialed mobile proxy with a current public mobile address.

One endpoint, two protocols¶

HTTP and SOCKS5 use the same hostname, port, username, and password. There is no protocol selection step when a rental or browser session starts.

GET /v1/devices returns these fields:

Field	Use
`proxy.http_url`	HTTP proxy URL
`proxy.socks5_url`	SOCKS5 URL; DNS behavior depends on the client
`proxy.socks5h_url`	SOCKS5 URL requesting hostname resolution through the proxy
`proxy.protocols`	Currently `['http', 'socks5']`
`proxy.url`	Compatibility field for older integrations; prefer an explicit URL above

The URLs contain credentials. Redact the entire user-info portion if you must log an endpoint. New rentals can receive a different port and credentials, so obtain the current URL from the API rather than carrying it across rentals.

HTTP example¶

import httpx

async with Aimlib() as ai:
    device = (await ai.devices.list())[0]
    async with httpx.AsyncClient(proxy=device.proxy.http_url) as client:
        response = await client.get("https://example.com")
        response.raise_for_status()

With curl:

curl --fail-with-body --proxy "$AIMLIB_HTTP_PROXY" https://example.com

SOCKS5 and DNS¶

Use socks5h_url when your library recognizes socks5h:// and you want the proxy to resolve the destination hostname. Use socks5_url for libraries that require socks5://; consult that library's DNS option because some clients resolve locally by default.

curl --fail-with-body --proxy "$AIMLIB_SOCKS5H_PROXY" https://example.com

IP-address destinations do not require DNS resolution.

Current public IP¶

device.current_egress_ip is the latest public address observed for the rental. Mobile addresses are dynamic and can change independently of an API request.

Refresh the device list after an IP rotation if your application needs the latest value.

Rotate the IP¶

result = await device.rotate_ip()
if result["status"] == "succeeded":
    print(result["new_ip"])

Rotations are limited to one network operation per device every 30 seconds. With wait=False, the request returns an operation_id; poll it through ai.operations.wait(operation_id) or GET /v1/operations/{id}.

Switch carrier¶

Carrier switching is available only when the requested carrier is available for the rental.

result = await device.switch_carrier("tmobile")

Accepted carrier identifiers are tmobile, att, and verizon. Availability is device-specific.

Connection availability¶

Connections are subject to the applicable customer agreement and service availability. If an authorized public destination is unexpectedly unavailable, collect the public error code and contact support without including credentials or request content.