> 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 Puppeteer

[Puppeteer](https://pptr.dev) is a popular automation library for Node.js that allows you to control headless browsers. Airtop provides a Puppeteer connector that allows you to use Puppeteer to automate your browser.

> **Note**
>
> Puppeteer is not supported in Python. We recommend using Playwright or Selenium instead.

## Installation

You will need to install the `puppeteer-core` package to use Puppeteer with Airtop.

**`npm`**

```bash npm
npm i puppeteer-core
```

**`yarn`**

```bash yarn
yarn add puppeteer-core
```

**`pnpm`**

```bash pnpm
pnpm add puppeteer-core
```

## Usage

Once you have created a session with Airtop, you can use the `puppeteer-core` package to control the browser by connecting Puppeteer to the CDP endpoint provided by Airtop.

```typescript
import puppeteer from "puppeteer-core";

const session = await client.sessions.create();
const puppeteerBrowser = await puppeteer.connect({
  browserWSEndpoint: session.data?.cdpWsUrl,
  headers: {
    authorization: `Bearer YOUR_API_KEY`,
  },
});

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

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

If you're not already familiar with Puppeteer, you might want to check out their [documentation](https://pptr.dev/guides/getting-started) to learn more about the library and its capabilities.

## Combining Puppeteer and Airtop Window Management

You can use Airtop's window management functions in combination with Puppeteer 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 Puppeteer 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 Puppeteer to the window.

```typescript
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 Puppeteer
const puppeteerBrowser = await puppeteer.connect({
  browserWSEndpoint: session.data?.cdpWsUrl,
  headers: {
    authorization: `Bearer YOUR_API_KEY`,
  },
});


// Iterate through the pages to find the one that matches the target ID
const pages = await puppeteerBrowser.pages();
let matchingPage;
for (const page of pages) {
  const pageTargetId = await (page.mainFrame() as any)._id;
  if (pageTargetId === targetId) {
    matchingPage = page;
    break;
  }
}

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

## Common Errors

Here are some common errors you might encounter when using Puppeteer 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.        |