Sessions

Create Session

Creates a new browser session with optional configuration.

Method: client.sessions.create(params?: CreateSessionParams): Promise<SessionDetail>

Endpoint: POST /api/session

Parameters:

• CreateSessionParams:

  • useStealth?: boolean - Use stealth mode.

  • useProxy?: boolean - Use proxy.

  • proxyServer?: string - Proxy server URL to route the session through.

  • proxyServerUsername?: string - Username for proxy server authentication.

  • proxyServerPassword?: string - Password for proxy server authentication.

  • proxyCountry?:Country - Desired proxy country.

  • proxyState?: State- Desired State. Is mutually exclusive with proxyCity. Currently only US states are supported. States need to be in two letter codes

  • proxyCity?: string - Desired City. Is mutually exclusive with proxyState. Some cities might not be supported, so before using a new city, we recommend trying it out.

  • operatingSystems?: OperatingSystem[] - Preferred operating systems for the session. Possible values are:

    • OperatingSystem.WINDOWS

    • OperatingSystem.ANDROID

    • OperatingSystem.MACOS

    • OperatingSystem.LINUX

    • OperatingSystem.IOS

  • device?: ("desktop" | "mobile")[] - Preferred device types. Possible values are:

    • "desktop"

    • "mobile"

  • platform?: Platform[] - Preferred browser platforms. Possible values are:

    • Platform.CHROME

    • Platform.FIREFOX

    • Platform.SAFARI

    • Platform.EDGE

  • locales?: ISO639_1[] - Preferred locales (languages) for the session. Use ISO 639-1 codes.

  • screen?: ScreenConfig - Screen configuration for the session.

    • width: number - Screen width.

    • height: number - Screen height.

  • solveCaptchas?: boolean - Solve captchas.

  • adblock?: boolean - Block ads.

  • trackers?: boolean - Block trackers.

  • annoyances?: boolean - Block annoyances.

  • enableWebRecording?: boolean - Default true

  • extensionIds?: string[] - Array of extension Ids

  • acceptCookies?: boolean - Automatically Accept Cookies on the page

  • urlBlocklist?: string[]

  • browserArgs?: string[]

  • imageCaptchaParams?: ImageCaptchaParam[] - Specify the image selectors and input box selectors to be used for solving standard image based captchas. Captchas will get solved, but accept/verify will have to be clicked by the user/script.

Response: SessionDetail

Example:

const session = await client.sessions.create();
console.log(session.id);

Get Session Details

Retrieves details of a specific session.

Method: client.sessions.get(id: string): Promise<SessionDetail>

Endpoint: GET /api/session/{id}

Parameters:

• id: string - Session ID

Response: SessionDetail

Example:

const session = await client.sessions.get("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e");
console.log(session.id);

​List Sessions

Retrieves a list of all sessions with optional filtering.

Method: client.sessions.list(params?: SessionListParams): Promise<SessionListResponse>

Endpoint: GET /api/sessions

Parameters:

• SessionListParams:

  • status?: "active" | "closed" | "error" - Filter sessions by status

  • page?: number - Page number for pagination

Response: SessionListResponse

Example:

const response = await client.sessions.list({
  status: "active",
  page: 1,
});
console.log(response.sessions);

​Stop Session

Stops a running session.

Method: client.sessions.stop(id: string): Promise<BasicResponse>

Endpoint: PUT /api/session/{id}/stop

Parameters:

• id: string - Session ID

Response: BasicResponse

Example:

const response = await client.sessions.stop(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
);
console.log(`Session stopped: ${response.success}`);

Get Session Recording

Get the recording of a session.

Method: client.sessions.getRecording(id: string): Promise<SessionRecording[]>

Endpoint: GET /api/session/{id}/recording

Parameters:

• id: string - Session ID

Response: SessionRecording[]

Example:

const recordingData = await client.sessions.getRecording(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
);
console.log(recordingData);

Types

SessionStatus

type SessionStatus = "active" | "closed" | "error";

Country

type Country =
  | "AD"
  | "AE"
  | "AF"
  ...

State

Currently only US States are supported. Standard two letter state codes are used.

type State =
  | "AL"
  | "AK"
  | "AZ"
  ...

OperatingSystem

type OperatingSystem = "windows" | "android" | "macos" | "linux" | "ios";

Platform

type Platform = "chrome" | "firefox" | "safari" | "edge";

ISO639_1

type ISO639_1 =
  | "aa"
  | "ab"
  | "ae"
  ...

BasicResponse

interface BasicResponse {
  success: boolean;
}

Session

interface Session {
  id: string;
  teamId: string;
  status: SessionStatus;
  startTime?: number;
  endTime?: number;
  createdAt: string;
  updatedAt: string;
  sessionUrl: string;
}

SessionDetail

interface SessionDetail extends Session {
  wsEndpoint?: string;
  liveUrl?: string;
  token?: string;
}

SessionListResponse

interface SessionListResponse {
  sessions: Session[];
  totalCount: number;
  page: number;
  perPage: number;
}

ScreenConfig

interface ScreenConfig {
  width: number;
  height: number;
}

CreateSessionParams

interface CreateSessionParams {
  useStealth?: boolean;
  useProxy?: boolean;
  proxyServer?: string;
  proxyServerPassword?: string;
  proxyServerUsername?: string;
  proxyCountry?: Country;
  operatingSystems?: OperatingSystem[];
  device?: ("desktop" | "mobile")[];
  platform?: Platform[];
  locales?: ISO639_1[];
  screen?: ScreenConfig;
  solveCaptchas?: boolean;
  adblock?: boolean;
  trackers?: boolean;
  annoyances?: boolean;
  enableWebRecording?: boolean;
  extensionIds?: string[];
  acceptCookies?: boolean;
  urlBlocklist?: string[];
  browserArgs?: string[];
}

SessionRecording

interface SessionRecording {
  type: number;
  data: unknown;
  timestamp: number;
  delay?: number;
}

ImageCaptchaParam

interface ImageCaptchaParam {
  imageSelector: string;
  inputSelector: string;
}