Python SDK¶

The aimlib SDK is an asynchronous Python client for customer device rentals, mobile proxies, remote browsers, network operations, and support tickets. Python 3.10 or newer is required.

Install¶

Install the browser extra when your application will use remote-browser sessions:

python -m pip install --upgrade "aimlib[browser]"

For proxy, operation, and ticket APIs without a browser client:

python -m pip install --upgrade aimlib

The browser extra provides the supported client integration. No separate browser installation step is required.

Configure¶

export AIMLIB_API_KEY="<api-key>"
export AIMLIB_BASE_URL="https://uswest1.aimlib.com"

Aimlib() reads those variables. Values passed to the constructor take precedence:

ai = Aimlib(api_key="<api-key>", base_url="https://uswest1.aimlib.com")

Use the async context manager so the HTTP client closes reliably:

async with Aimlib() as ai:
    devices = await ai.devices.list()

Devices¶

devices = await ai.devices.list()
device = await ai.device(devices[0].id)

Useful Device attributes:

Attribute	Meaning
`id`	Device ID used by customer endpoints
`region`	Assigned regional API location
`carrier`	Current carrier identifier
`current_egress_ip`	Latest public address observed for the rental
`lease_id`, `lease_ends_at`	Active rental metadata
`browser_available`	Whether the device currently supports a remote browser
`proxy`	`Proxy` object when endpoint provisioning is complete

Proxy¶

proxy = device.proxy
http_url = proxy.http_url
socks_url = proxy.socks5_url
socks_remote_dns_url = proxy.socks5h_url

The URL values contain credentials. repr(proxy) omits them, but application logging must still avoid printing the URL attributes. HTTP and SOCKS5 use the same proxy.host and proxy.port.

See Mobile proxy for DNS and connection guidance.

Create a browser session¶

async with await device.browser(
    ttl="10m",
    idle_timeout="2m",
    footprint="pixel-9",
) as session:
    page = await session.new_page()
    await page.goto("https://example.com", wait_until="domcontentloaded")

Durations accept seconds or strings such as "30s", "10m", and "1h"; the service still applies its documented maximum. Omit footprint unless you selected a slug from await device.list_footprints().

The browser context manager connects on entry and requests a stop on exit. When managing the lifecycle manually:

session = await device.browser(ttl="10m")
try:
    await session.connect()
    page = await session.new_page()
finally:
    await session.stop()

Key methods and attributes:

Member	Behavior
`wait_until_ready(timeout=180)`	Wait for the session to become usable
`connect(timeout=180)`	Connect the supported async browser client
`new_page()`	Return the initial tab, then create later tabs up to `max_tabs`
`disconnect()`	Close only this SDK client's connection; the session remains active
`stop(wait=True, timeout=120)`	Request a stop and optionally wait for completion
`set_footprint(slug, timeout=120)`	Apply an available footprint and reconnect
`status`, `egress_ip`, `expires_at`	Current session metadata

Rotate IP and switch carrier¶

Blocking mode waits for a terminal operation result:

rotation = await device.rotate_ip()
switch = await device.switch_carrier("att")

Inspect status; a completed HTTP request can still report failed or timeout.

Queue work when your application should not hold the request open:

queued = await device.rotate_ip(wait=False)
result = await ai.operations.wait(queued["operation_id"], timeout=300)

await ai.operations.get(operation_id) performs one status request. Returned dictionaries expose only the stable customer fields: operation_id, type, status, and, when applicable, new_ip, carrier, error, and message.

Support tickets¶

ticket = await ai.tickets.create(
    subject="Browser did not become ready",
    body="Device ID ...; observed around 20:00 UTC.",
)

tickets = await ai.tickets.list()
ticket = await ai.tickets.get(ticket.id)
ticket = await ticket.reply("The issue is still reproducible.")
ticket = await ticket.close()

ticket.complete becomes true only after both the customer and aimlib support close the ticket.

Exceptions¶

All SDK-specific exceptions derive from AimlibError.

Exception	Meaning
`BrowserUnavailableError`	Remote browser cannot currently be created or reached
`BrowserPolicyError`	Requested capability is outside the supported browser interface
`CapacityError`	Device or account browser capacity is in use
`LeaseInactiveError`	Active rental or proxy requirement is not met
`DataCapError`	Account usage allowance has been exhausted
`SessionExpiredError`	Session ended or was replaced
`SessionTimeout`	Browser readiness, connection, or stop operation timed out
`OperationTimeout`	Client-side operation polling deadline elapsed
`TabLimitError`	Session tab cap was reached

Network-operation failed and timeout states are returned as dictionaries rather than raised. HTTP, transport, and unknown public API failures surface as AimlibError or their documented dependency exceptions.

Upgrade¶

Pin an exact PyPI version for reproducible deployments:

python -m pip install "aimlib[browser]==0.4.4"

Review the customer changelog before upgrading, then run browser-session tests in a non-production customer rental.