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

# Creating a Session

## What is a session?

A session represents an instance of a browser. Each session is identified by a unique UUID and can contain multiple windows that each can load a page.

## How to create a session

You can create a session by simply calling the `create` function on the API as follows:

**`NodeJS`**

```typescript NodeJS
const client = new AirtopClient({apiKey: "YOUR_API_KEY"});
const session = await client.sessions.create();
```

**`Python`**

```python Python
client = Airtop(api_key="YOUR_API_KEY")
session = client.sessions.create()
```

When you create a session, it may take a small amount of time to initialize. Usually it's a matter of seconds, but in rare cases when hardware isn't immediately available, it may take around 1 minute. The `create` function will wait until the session is fully initialized and ready to be used. However, if you would like to create a session and not wait for initialization, you can pass the `skipWaitSessionReady` parameter as `true`.

**`NodeJS`**

```typescript NodeJS
const client = new AirtopClient({apiKey: "YOUR_API_KEY"});
const session = await client.sessions.create({
  configuration: {
    skipWaitSessionReady: true,
  }
});
```

**`Python`**

```python Python
# Also import SessionConfig to pass the configuration parameter
from airtop import Airtop, SessionConfig

client = Airtop(api_key="YOUR_API_KEY")
session = client.sessions.create(configuration=SessionConfig(skip_wait_session_ready=True))
```

If you choose to not wait for the session to initialize, you can use the `waitForSessionReady` function to wait until the session is ready.

**`NodeJS`**

```typescript NodeJS
const client = new AirtopClient({apiKey: "YOUR_API_KEY"});
const session = await client.sessions.create({
  configuration: {
    skipWaitSessionReady: true,
  }
});

// Session will be returned immediately but may not be ready for use
await client.sessions.waitForSessionReady(session.data.id);

// Session is now ready for use
```

**`Python`**

```python Python
client = Airtop(api_key="YOUR_API_KEY")
session = await client.sessions.create(configuration=SessionConfig(skip_wait_session_ready=True))

# Session will be returned immediately but may not be ready for use
client.sessions.wait_for_session_ready(session.data.id)

# Session is now ready for use
```

## Timeouts and Termination

By default, sessions have an idle timeout of 10 minutes. After 10 minutes of inactivity, the session will be automatically terminated. You can also specify a custom timeout when creating a session by passing the `timeoutMinutes` parameter.

**`NodeJS`**

```typescript NodeJS
const client = new AirtopClient({apiKey: "YOUR_API_KEY"});
const session = await client.sessions.create({configuration: {
  timeoutMinutes: 5, // Terminate the session after 5 mins of inactivity
}});
```

**`Python`**

```python Python
# Also import SessionConfigV1 to pass the configuration parameter
from airtop import Airtop, SessionConfig

client = Airtop(api_key="YOUR_API_KEY")
session = client.sessions.create(configuration=SessionConfig(timeout_minutes=5))
```

You can also terminate a session at any point by calling the `terminate` function.

**`NodeJS`**

```typescript NodeJS
const client = new AirtopClient({apiKey: "YOUR_API_KEY"});
const session = await client.sessions.create();
await client.sessions.terminate(session.data.id);
```

**`Python`**

```python Python
client = Airtop(api_key="YOUR_API_KEY")
session = client.sessions.create()
client.sessions.terminate(session.data.id)
```

> **Note**
>
> Remember that sessions are billed per 30s increments, so it's important to terminate sessions when you're done with them to avoid unnecessary charges.

## Session States

Sessions can be in one of the following states:

* `initializing`: The session is pending initialization.
* `awaiting_capacity`: The session is waiting for capacity.
* `running`: The session is running and ready for use.
* `ended`: The session has been ended by the user or due to inactivity.

In general, if you are creating a session via the SDK without the `skipWaitSessionReady: true` parameter, you do not need to worry about `initializing` and `awaiting_capacity` states. These states are only relevant if you are creating a session with the `skipWaitSessionReady: true` parameter or directly through the REST API. A session might be `ended` if it terminated due to idle timeout, if you explicitly terminate it, or if it was terminated due to an error.

You can check the state of a session by calling the `getInfo` function.

**`NodeJS`**

```typescript NodeJS
const client = new AirtopClient({apiKey: "YOUR_API_KEY"});
const session = await client.sessions.getInfo(session.data.id);
console.log(session.data.status);
```

**`Python`**

```python Python
client = Airtop(api_key="YOUR_API_KEY")
session = client.sessions.getinfo(session.data.id)
print(session.data.status)
```

## Profiles

When creating a session, you can choose to save the profile of the browser for future use, or load a saved profile. This will allow you to reuse cookies and local storage between sessions. For more detailed information on how to use profiles, see [Profiles](/guides/how-to/saving-a-profile).

## Windows

After you create a session, you can create one or more windows to load pages within the session. You can create a window by calling the `create` function on the `windows` API.

**`NodeJS`**

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

**`Python`**

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

### Wait Until Options

Before you can interact or prompt the page, the page must be fully loaded. You can provide a `waitUntil` parameter to the `create` function to customize exactly what you are waiting for. There are 2 options for the `waitUntil` parameter: `load` and `domcontentloaded`.

* `load`: Wait until the page and all resources are fully loaded (default).
* `domcontentloaded`: Wait until the DOM is fully loaded.

**`NodeJS`**

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

**`Python`**

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

### Screen Resolution

You can also specify the screen resolution of the window by passing the `screenResolution` parameter to the `create` function. This is useful if you want to ensure that the browser is loaded at a specific resolution. The screen resolution should be passed as a string in the format of `widthxheight`.

**`NodeJS`**

```typescript NodeJS
const window = await client.windows.create(session.data.id, { url: "https://www.airtop.ai", screenResolution: "1920x1080" });
```

**`Python`**

```python Python
window = client.windows.create(session.data.id, url="https://www.airtop.ai", screen_resolution="1920x1080")
```

### Loading URLs

If you've already created a window and want to load a URL in it, you can use the `loadUrl` function using the window ID.

**`NodeJS`**

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

// Load URL 2
await client.windows.loadUrl(session.data.id, windowResponse.data.windowId, { url: "https://www.google.com" });
```

**`Python`**

```python Python
# Create a window and load URL 1
window = client.windows.create(session.data.id, url="https://www.airtop.ai")

# Load URL 2
client.windows.load_url(session.data.id, window.data.window_id, url="https://www.google.com")
```

### Closing Windows

If you terminate a browser session (see [Timeouts and Termination](#timeouts-and-termination) above), all windows associated with that session will be closed automatically.

If you have a window ID, you can close that specific window by calling the `close` function.

**`NodeJS`**

```typescript NodeJS
await client.windows.close(sessionId, windowId);
```

**`Python`**

```python Python
client.windows.close(session_id, window_id)
```

This can be useful if you have a long running session with multiple windows and want to close windows you aren't using anymore to free up resources.

> How to create a session with Airtop