Quick Start

Fresh Source: docs.airtop.ai

Get up and running with Airtop in 5 minutes. This guide covers installing the SDK, creating a session, loading a URL, querying the page with AI, and cleaning up.

Prerequisites

• An Airtop API key (get one at portal.airtop.ai)
• Node.js 18+ or Python 3.8+

Step 1: Install the SDK

Node.js

npm install @airtop/sdk

Python

pip install airtop

Step 2: Initialize the Client

TypeScript

import Airtop from '@airtop/sdk';

const client = new Airtop({
  apiKey: process.env.AIRTOP_API_KEY,
});

Python

from airtop import Airtop

client = Airtop(api_key="your-api-key")

Step 3: Create a Session

TypeScript

const session = await client.sessions.create({
  configuration: {
    timeoutMinutes: 10,
  },
});
const sessionId = session.data.id;
console.log('Session created:', sessionId);

Python

session = client.sessions.create(
    configuration={"timeoutMinutes": 10}
)
session_id = session.data.id
print(f"Session created: {session_id}")

Step 4: Create a Window and Load a URL

TypeScript

const window = await client.windows.create(sessionId, {
  url: 'https://example.com',
});
const windowId = window.data.windowId;
console.log('Window created:', windowId);

Python

window = client.windows.create(
    session_id,
    url="https://example.com"
)
window_id = window.data.window_id
print(f"Window created: {window_id}")

Step 5: Query the Page with AI

TypeScript

const result = await client.windows.pageQuery(sessionId, windowId, {
  prompt: 'What is the main heading on this page?',
});
console.log('Answer:', result.data.modelResponse);

Python

result = client.windows.page_query(
    session_id, window_id,
    prompt="What is the main heading on this page?"
)
print(f"Answer: {result.data.model_response}")

Step 6: Terminate the Session

TypeScript

await client.sessions.terminate(sessionId);
console.log('Session terminated');

Python

client.sessions.terminate(session_id)
print("Session terminated")

Complete Example

TypeScript

import Airtop from '@airtop/sdk';

async function main() {
  const client = new Airtop({ apiKey: process.env.AIRTOP_API_KEY });

  // Create session
  const session = await client.sessions.create({
    configuration: { timeoutMinutes: 10 },
  });
  const sessionId = session.data.id;

  try {
    // Create window
    const window = await client.windows.create(sessionId, {
      url: 'https://example.com',
    });
    const windowId = window.data.windowId;

    // Query the page
    const result = await client.windows.pageQuery(sessionId, windowId, {
      prompt: 'Summarize the content of this page in 2 sentences.',
    });
    console.log(result.data.modelResponse);
  } finally {
    // Always terminate
    await client.sessions.terminate(sessionId);
  }
}

main();

Python

from airtop import Airtop

def main():
    client = Airtop(api_key="your-api-key")

    # Create session
    session = client.sessions.create(
        configuration={"timeoutMinutes": 10}
    )
    session_id = session.data.id

    try:
        # Create window
        window = client.windows.create(
            session_id, url="https://example.com"
        )
        window_id = window.data.window_id

        # Query the page
        result = client.windows.page_query(
            session_id, window_id,
            prompt="Summarize the content of this page in 2 sentences."
        )
        print(result.data.model_response)
    finally:
        # Always terminate
        client.sessions.terminate(session_id)

main()

Next Steps

• Session Management — learn about session states, timeouts, and configuration
• Smart Scraping — extract content as markdown
• Page Querying — advanced page querying with JSON schema output
• Profiles — save and restore authenticated sessions