incogniton 0.3.0

Python client for Incogniton API

Incogniton Python Client

The official Incogniton Anti-detect browser Python SDK for seamless integration with the Incogniton Antidetect Browser API and browser automation workflows. For more about Incogniton, visit our website.

This package enables Python developers to automate browser tasks, manage profiles, and handle cookies using Incogniton's local desktop app. It supports both REST API operations and direct browser automation (Selenium and Playwright).

Key Capabilities

• Create, update, and delete browser profiles
• Manage cookies for any profile
• Launch automation endpoints to get the CDP (Chrome DevTools Protocol) URL for Puppeteer and Playwright and the WebDriver URL for Selenium
• Browser Automation SDK using Playwright and Selenium
• Built-in error handling and logging

Getting Started

Installation

# Recommended: install from PyPI
pip install incogniton

# Or, for Development:
poetry install
# with pip
pip install -e .

Requirements

• Python 3.9 or newer
• Incogniton desktop app running locally

Example Usage

Profile Management

from incogniton import IncognitonClient

client = IncognitonClient()

# Target a non-default app port (Incogniton's API port is configurable in the Debug settings tab)
client = IncognitonClient(port=40000)

# Add a new profile
data = {"profileData": {"general_profile_information": {"profile_name": "Test Profile"}}}
profile = await client.profile.add(data)

# List all profiles
profiles = await client.profile.list()

# Fetch a profile by ID
details = await client.profile.get("PROFILE_ID")

Automating Browsers

from incogniton import IncognitonBrowser

browser = IncognitonBrowser(client, profile_id="your-profile-id", headless=True)

# Playwright example (recommended)
playwright_browser = await browser.start_playwright()
page = await playwright_browser.new_page()
await page.goto("https://example.com")
page_title = await page.title()
print(page_title)  # Print page title
await page.screenshot(path="example.png")  # Take a screenshot
await browser.close(playwright_browser)

# Selenium example (also supported)
selenium_driver = await browser.start_selenium()
selenium_driver.get("https://example.com")
selenium_driver.quit()

Note: Playwright is the recommended automation tool for most use cases due to its modern API, speed, and reliability. Selenium is also supported, but its Web-driver endpoint is generally less reliable.

Configuration Options

• profile_id: Incogniton profile to use for automation
• headless: Run browsers in headless mode (default: True)
• custom_args: Pass extra arguments to the browser (optional)

Endpoints & Methods

Below is a summary of the most commonly used methods and operations available in the Incogniton Python SDK. For a complete and up-to-date API reference, please see the official Incogniton API Documentation.

System Operations (client.system)

• await client.system.alive()
  • Health probe. Returns "OK" when the desktop app is reachable.
• await client.system.close()
  • Shut down the Incogniton application.

Profile Operations (client.profile)

• await client.profile.list()
  • List all browser profiles.
• await client.profile.get(profile_id)
  • Get a specific browser profile.
• await client.profile.add(create_request)
  • Add a new browser profile. "create_request" is a "CreateBrowserProfileRequest".
• await client.profile.update(profile_id, update_request)
  • Update an existing browser profile. "update_request" is an "UpdateBrowserProfileRequest".
• await client.profile.switch_proxy(profile_id, proxy)
  • Update a browser profile's proxy configuration.
• await client.profile.clone(profile_id, profile_name=None, target_group=None, clone_cookies=None, clone_advanced_other_settings=None, clone_useragent=None, clone_other_browser_data=None)
  • Clone a profile with custom settings. Returns the new clone's profile_browser_id.
• await client.profile.clone_quick(profile_id)
  • Clone a profile using all-default settings (same name/group, every clone option on).
• await client.profile.launch(profile_id)
  • Launch a browser profile.
• await client.profile.launch_force_local(profile_id)
  • Force a browser profile to launch in local mode.
• await client.profile.launch_force_cloud(profile_id)
  • Force a browser profile to launch in cloud mode.
• await client.profile.dry_launch(profile_id)
  • Prepare a launch without opening a browser; returns the built launch command as arg.
• await client.profile.dry_launch_force_local(profile_id)
  • Dry-launch, forcing the local copy when out of sync.
• await client.profile.dry_launch_force_cloud(profile_id)
  • Dry-launch, forcing the cloud copy when out of sync.
• await client.profile.get_status(profile_id)
  • Get the current status of a browser profile.
• await client.profile.stop(profile_id)
  • Stop a running browser profile.
• await client.profile.force_stop(profile_id)
  • Force stop a running browser profile.
• await client.profile.delete(profile_id)
  • Delete a browser profile.

Cookie Operations (client.cookie)

• await client.cookie.get(profile_id)
  • Get all cookies associated with a browser profile.
• await client.cookie.add(profile_id, cookie_data)
  • Add a new cookie to a browser profile. "cookie_data" is a list of cookie dicts.
• await client.cookie.delete(profile_id)
  • Delete all cookies from a browser profile.

Automation Operations (client.automation)

• await client.automation.launch_puppeteer(profile_id)
  • Launch a browser profile with Puppeteer automation.
• await client.automation.launch_puppeteer_force_local(profile_id)
  • Launch for Puppeteer, forcing the local copy when out of sync.
• await client.automation.launch_puppeteer_force_cloud(profile_id)
  • Launch for Puppeteer, forcing the cloud copy when out of sync.
• await client.automation.launch_puppeteer_custom(profile_id, custom_args)
  • Launch a browser profile with Puppeteer automation using custom arguments.
• await client.automation.launch_selenium(profile_id)
  • Launch a browser profile with Selenium automation.
• await client.automation.launch_selenium_force_local(profile_id)
  • Launch on the Selenium grid, forcing the local copy when out of sync.
• await client.automation.launch_selenium_force_cloud(profile_id)
  • Launch on the Selenium grid, forcing the cloud copy when out of sync.
• await client.automation.launch_selenium_custom(profile_id, custom_args)
  • Launch a browser profile with Selenium automation using custom arguments (profile id in the URL path).
• await client.automation.launch_selenium_custom_body(profile_id, custom_args=None, force_local=False, force_cloud=False)
  • Launch on the Selenium grid with custom args, profile id in the request body.
• await client.automation.launch_cookie_robot(profile_id)
  • Run the cookie-collection robot on a profile.

Browser Automation SDK (browser)

• playwright_browser = await browser.start_playwright()
  • Launch the profile and return a connected Playwright browser instance (Recommended).
• selenium_driver = await browser.start_selenium()
  • Launch the profile and return a connected Selenium WebDriver instance.
• await browser.close(playwright_browser)
  • Close a single Playwright browser instance with logging and error handling.
• await browser.close_all([playwright_browser1, playwright_browser2, ...])
  • Close multiple Playwright browser instances in parallel with logging and error handling.

Running Tests

poetry run pytest
# or
pytest tests/

Contributing

We welcome improvements and bugfixes! Please fork the repository, create a branch, and open a pull request.

Need Help?

For questions or support, email [e-mail] or use the Incogniton contact form.