Session Management

Fresh Source: docs.airtop.ai

Sessions are the core resource in Airtop. Each session represents a cloud browser instance with its own state, cookies, and configuration.

Session States

State	Description
initializing	Session is being created
awaiting_capacity	Waiting for available browser capacity
running	Session is active and ready for use
ended	Session has been terminated

Creating a Session

Basic Session

TypeScript

const session = await client.sessions.create({
  configuration: {
    timeoutMinutes: 10,
  },
});

Python

session = client.sessions.create(
    configuration={"timeoutMinutes": 10}
)

Session with Full Configuration

TypeScript

const session = await client.sessions.create({
  configuration: {
    timeoutMinutes: 30,
    persistProfile: true,
    profileName: 'my-profile',
    solveCaptcha: true,
    proxy: {
      type: 'airtop',
      options: { country: 'US', sticky: true },
    },
    screenResolution: '1920x1080',
  },
});

Python

session = client.sessions.create(
    configuration={
        "timeoutMinutes": 30,
        "persistProfile": True,
        "profileName": "my-profile",
        "solveCaptcha": True,
        "proxy": {
            "type": "airtop",
            "options": {"country": "US", "sticky": True}
        },
        "screenResolution": "1920x1080"
    }
)

Configuration Options

Option	Type	Default	Description
timeoutMinutes	number	10	Auto-terminate after this many minutes
persistProfile	boolean	false	Enable profile saving
profileName	string	—	Name for saving/loading profile
solveCaptcha	boolean	false	Enable built-in captcha solving
proxy	object	—	Proxy configuration
screenResolution	string	"1920x1080"	Browser viewport resolution

Listing Sessions

TypeScript

const sessions = await client.sessions.list();
for (const session of sessions.data) {
  console.log(`${session.id}: ${session.status}`);
}

Python

sessions = client.sessions.list()
for session in sessions.data:
    print(f"{session.id}: {session.status}")

Getting Session Info

TypeScript

const info = await client.sessions.getInfo(sessionId);
console.log('Status:', info.data.status);
console.log('Created:', info.data.createdAt);

Python

info = client.sessions.get_info(session_id)
print(f"Status: {info.data.status}")
print(f"Created: {info.data.created_at}")

Terminating a Session

TypeScript

// Basic termination
await client.sessions.terminate(sessionId);

// Terminate and save profile
await client.sessions.terminate(sessionId, {
  saveProfileOnTermination: 'my-saved-profile',
});

Python

# Basic termination
client.sessions.terminate(session_id)

# Terminate and save profile
client.sessions.terminate(
    session_id,
    save_profile_on_termination="my-saved-profile"
)

Windows within Sessions

Each session can have multiple windows (browser tabs).

TypeScript

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

// List windows
const windows = await client.windows.list(sessionId);

// Close a window
await client.windows.close(sessionId, windowId);

Python

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

# List windows
windows = client.windows.list(session_id)

# Close a window
client.windows.close(session_id, window_id)

Window Options

Option	Type	Description
url	string	URL to load
waitUntil	string	Wait condition: "load" or "domcontentloaded"
screenResolution	string	Override session resolution for this window

Billing

• Sessions are billed per 30-second increment
• Default timeout: 10 minutes
• Always terminate sessions when done to avoid unnecessary charges
• Use timeoutMinutes as a safety net

Best Practices

1. Always use try/finally to ensure sessions are terminated
2. Set appropriate timeouts — don't use longer than needed
3. Reuse sessions when performing multiple operations on the same site
4. Use profiles for authenticated sessions to avoid re-login
5. Monitor session state before performing operations