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:

1
const client = new AirtopClient({apiKey: "YOUR_API_KEY"});
2
const session = await 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.

1
const client = new AirtopClient({apiKey: "YOUR_API_KEY"});
2
const session = await client.sessions.create({
3
  configuration: {
4
    skipWaitSessionReady: true,
5
  }
6
});

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

1
const client = new AirtopClient({apiKey: "YOUR_API_KEY"});
2
const session = await client.sessions.create({
3
  configuration: {
4
    skipWaitSessionReady: true,
5
  }
6
});
7
8
// Session will be returned immediately but may not be ready for use
9
await client.sessions.waitForSessionReady(session.data.id);
10
11
// Session is now ready for use

By default, sessions have a TTL (Time To Live) of 10 mins. Once the TTL expires, the session will be automatically terminated. You can also specify a custom timeout when creating a session by passing the timeoutMinutes parameter.

1
const client = new AirtopClient({apiKey: "YOUR_API_KEY"});
2
const session = await client.sessions.create({configuration: {
3
  timeoutMinutes: 15,
4
}});

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

1
const client = new AirtopClient({apiKey: "YOUR_API_KEY"});
2
const session = await client.sessions.create();
3
await client.sessions.terminate(session.data.id);

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 TTL 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.

1
const client = new AirtopClient({apiKey: "YOUR_API_KEY"});
2
const session = await client.sessions.getInfo(session.data.id);
3
console.log(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.

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.

1
const window = await 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.

1
const window = await client.windows.create(session.data.id, { url: "https://www.airtop.ai" waitUntil: "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.

1
const window = await client.windows.create(session.data.id, { url: "https://www.airtop.ai", screenResolution: "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.

1
// Create a window and load URL 1
2
const windowResponse = await client.windows.create(session.data.id, { url: "https://www.airtop.ai" });
3
4
// Load URL 2
5
await client.windows.loadUrl(session.data.id, windowResponse.data.windowId, { url: "https://www.google.com" });

Closing Windows

If you terminate a browser session (see 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.

1
await client.windows.close(sessionId, windowId);

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.