> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.airtop.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.airtop.ai/_mcp/server.

# Integrating with Playwright

[Playwright](https://playwright.dev) is a powerful automation library that allows you to control headless browsers. Airtop provides a Playwright connector that allows you to use Playwright to automate your browser.

## Installation

You will need to install the `playwright-core` package to use Playwright with Airtop.

**`NodeJS (npm)`**

```bash NodeJS (npm)
npm i playwright-core
```

**`NodeJS (yarn)`**

```bash NodeJS (yarn)
yarn add playwright-core
```

**`NodeJS (pnpm)`**

```bash NodeJS (pnpm)
pnpm add playwright-core
```

**`Python`**

```bash Python
pip install playwright
```

## Usage

Once you have created a session with Airtop, you can use the Playwright library to control the browser by connecting Playwright to the CDP endpoint provided by Airtop. Please note that currently, Airtop only supports using the default browser context.

**`NodeJS`**

```typescript NodeJS
import { chromium } from 'playwright-core';

const session = await client.sessions.create();
const playwrightBrowser = await chromium.connectOverCDP(session.data.cdpWsUrl, {
  headers: {
    authorization: `Bearer YOUR_API_KEY`,
  },
});

// Airtop does not currently support multiple contexts.
// Please be sure to use the default context.
const defaultContext = playwrightBrowser.contexts()[0];

// Navigate to a new page
const page = await defaultContext.newPage();
await page.goto('https://www.airtop.ai');

// Get the page content
const content = await page.content();
console.log(content);
```

**`Python`**

```python Python
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    # Connect to the cloud browser.
    browser = p.chromium.connect_over_cdp(session.data.cdp_ws_url, headers={
        'authorization': f'Bearer YOUR_API_KEY'
    })

    # Airtop does not currently support multiple contexts.
    # Please be sure to use the default context.
    default_context = browser.contexts[0]
    page = default_context.new_page()
    page.goto("https://www.airtop.ai")

    # Get the page content
    content = page.content()
    print(content)
```

If you're not already familiar with Playwright, you might want to check out their [documentation](https://playwright.dev/docs/intro) to learn more about the library and its capabilities.

## Combining Playwright and Airtop Window Management

You can use Airtop's window management functions in combination with Playwright to automate your browser. For example, you might want to create a new window, load a URL in it, use our AI APIs, but use Playwright to push a few buttons on the page.

Once you create a window, you'll be given a window ID, which you'll use to interact with the window using Airtop's SDK. But you'll also be given a `targetId`, which you'll use to connect Playwright to the window.

**`NodeJS`**

```typescript NodeJS
const windowResponse = await client.windows.create(session.data.id, { url: "https://www.airtop.ai", waitUntil: "load" });

// Get the target ID from the window response
const { targetId } = windowResponse.data;

// Connect to the session using Playwright
const playwrightBrowser = await chromium.connectOverCDP(session.data.cdpWsUrl, {
  headers: {
    authorization: `Bearer YOUR_API_KEY`,
  }
});

// Iterate through the pages to find the one that matches the target ID
const pages = playwrightBrowser.contexts()[0].pages();
let matchingPage;
for (const page of pages) {
  const cdpSession = await page.context().newCDPSession(page);
  const { targetInfo } = await cdpSession.send('Target.getTargetInfo');
  const pageTargetId = targetInfo.targetId;
  if (pageTargetId === targetId) {
    matchingPage = page;
    break;
  }
}

// Once the page is found you can use Playwright to interact with it
if (matchingPage) {
  await matchingPage.getByRole('button').click();
}
```

**`Python`**

```python Python
window_response = client.windows.create(session.data.id, url="https://www.airtop.ai", wait_until="load")

# Get the target ID from the window response
window_target_id = window_response.data.target_id

with sync_playwright() as p:
    # Connect to the session using Playwright.
    browser = p.chromium.connect_over_cdp(session.data.cdp_ws_url, headers={
        'authorization': 'Bearer YOUR_API_KEY'
    })

    pages = browser.contexts[0].pages
    for page in pages:
        cdp_session = page.context.new_cdp_session(page)
        result = cdp_session.send('Target.getTargetInfo')
        if result['targetInfo']['targetId'] == window_target_id:
            matching_page = page
            break

    # Once the page is found you can use Playwright to interact with it
    if matching_page:
        matching_page.get_by_role('button').click()
```

## Common Errors

Here are some common errors you might encounter when using Playwright with Airtop when you initially connect to the CDP endpoint:

| Error Code | Common Cause                                                                                                                                                         |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **400**    | Bad request. Check that you specify the essential parts of the request. For example, is there an “Authorization: Bearer API\_KEY” header with a valid airtop API key |
| **401**    | Unauthorized. Check that you are using a valid API key.                                                                                                              |
| **404**    | Not found. Check that the session ID you specified in your request is correct, and that the url path is correct                                                      |
| **422**    | Unprocessable Content. Check that your inputs are well-formed. For example, is your session ID a valid UUID?                                                         |
| **503**    | Service Unavailable. The session is valid, but it cannot be connected to. Check whether the session has timed out or that you haven't already terminated it.         |