adspower

AdsPower Python SDK

Typed synchronous and asynchronous clients for AdsPower Local API. The SDK covers profile, proxy and tag operations plus Selenium and Playwright browser attachment. It preserves the server response envelope and does not forward an AdsPower API key to CDP, WebDriver, or browser-version probes.

Capabilities

• Manage profiles, groups, proxies, tags, categories and browser kernels.
• Start and stop AdsPower browser profiles.
• Attach Selenium, sync Playwright, or async Playwright to a running profile.
• Use the same resource-oriented API in synchronous and asynchronous code.
• Configure timeouts, networking and request-rate policies.

Requirements

• Python 3.10–3.15.
• AdsPower running with Local API enabled.
• An API key when the Local API installation requires one.
• Selenium and/or Playwright only for browser automation.

Installation

pip install adspower
pip install 'adspower[selenium]'
pip install 'adspower[playwright]'
pip install 'adspower[all]'

Agent skill

This repository includes the adspower-python skill for agents that write, review, debug, or migrate code using this SDK. It captures the v3 API surface, browser lifecycle, pagination, topology, rate-limit, and safety conventions.

Install it with:

npx skills add https://github.com/CrocoFactory/adspower/tree/master/skills/adspower-python

Quick start: Selenium

from adspower import AdsPowerClient, AdsPowerRatePolicy

with AdsPowerClient(
    base_url="http://127.0.0.1:50325",
    api_key="your-api-key",
    rate_policy=AdsPowerRatePolicy.for_profile_count(200),
) as client:
    created = client.profiles.create(name="example")

    with client.browsers.session(created.profile_id, headless=True) as session:
        with session.selenium() as driver:
            driver.get("https://example.com")
            print(driver.title)

    client.profiles.delete(created.profile_id)

BrowserSession owns the AdsPower browser lifecycle. Exiting the session stops the profile even if an attached driver raises an exception.

Quick start: async Playwright

import asyncio

from adspower import AdsPowerRatePolicy, AsyncAdsPowerClient


async def main() -> None:
    async with AsyncAdsPowerClient(
        api_key="your-api-key",
        rate_policy=AdsPowerRatePolicy.conservative(),
    ) as client:
        async with await client.browsers.session("profile-id", headless=True) as session:
            async with session.playwright() as browser:
                context = browser.contexts[0]
                page = context.pages[0] if context.pages else await context.new_page()
                await page.goto("https://example.com")
                print(await page.title())


asyncio.run(main())

By default, browser endpoints are used exactly as AdsPower returns them. This avoids CDP WebSocket host-header failures on Local API installations. For a remote or Docker topology where AdsPower returns unreachable loopback endpoints, opt into browser_endpoint_policy="rewrite_loopback_to_api_host"; see configuration.

Profiles, proxies, and pagination

from adspower import StoredProxyConfig

page = client.profiles.list(
    name="shop",
    name_filter="include",
    tag_ids=["tag-id"],
    tags_filter="include",
    page_size=100,  # AdsPower V2 allows 1–100
)

proxy_ids = client.proxies.create_many(
    [StoredProxyConfig("http", "127.0.0.1", 8080, remark="example")]
)

for profile in client.profiles.iter_all(group_id="0"):
    print(profile.profile_id)

groups.list() accepts pages up to 2000; proxies.create_many() accepts up to 500 proxy definitions. AdsPowerRatePolicy applies the documented 1 req/s limits to profile/group listings, cookies, and UA generation in addition to the global rate limit.

Raw API

envelope = client.raw.request("POST", "/api/v2/future-endpoint", json={"x": 1})

Raw paths must be root-relative. Absolute URLs are rejected so the Local API authorization header cannot be sent to another host.

Documentation

• Configuration and topology
• Profiles and browser sessions
• Automation adapters
• Local API reference
• API overview
• Errors
• Migration 2.x → 3.x

See the MIT License.