Sessions

Create Session

Creates a new browser session with optional configuration.

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

Endpoint: POST /api/session

Parameters:

• CreateSessionParams:

  • use_stealth?: boolean - Use stealth mode.

  • use_proxy?: boolean - Use proxy.

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

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

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

  • proxy_country?: Country - Desired proxy country.

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

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

  • operating_systems?: 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.

  • solve_captchas?: boolean - Solve captchas.

  • adblock?: boolean - Block ads.

  • trackers?: boolean - Block trackers.

  • annoyances?: boolean - Block annoyances.

  • enable_web_recording?: boolean - Default true

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

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

  • url_blocklist?: string[]

  • browser_args?: 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:

session = client.sessions.create()
print(session.id)

Get Session Details

Retrieves details of a specific session.

Method: client.sessions.get(id: str): SessionDetail

Endpoint: GET /api/session/{id}

Parameters:

• id: string - Session ID

Response: SessionDetail

Example:

session = client.sessions.get("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")
print(session.id)

​List Sessions

Retrieves a list of all sessions with optional filtering.

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

Endpoint: GET /api/sessions

Parameters:

• SessionListParams:

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

  • page?: number - Page number for pagination

Response: SessionListResponse

Example:

response = client.sessions.list()
print(response.sessions)

​Stop Session

Stops a running session.

Method: client.sessions.stop(id: str): BasicResponse

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

Parameters:

• id: string - Session ID

Response: BasicResponse

Example:

response = client.sessions.stop(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)
print(f"Session stopped: {response.success}")

Get Session Recording

Get the recording of a session.

Method: client.sessions.get_recording(id: str): SessionRecording[]

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

Parameters:

• id: string - Session ID

Response: SessionRecording[]

Example:

recordingData = client.sessions.get_recording(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
);
print(recordingData)

Types

SessionStatus

SessionStatus = Literal["active", "closed", "error"]

Country

Country = Literal["AD", "AE", "AF", ...]

States

State = Literal["AL", "AK", "AZ", ...]

OperatingSystem

OperatingSystem = Literal["windows", "android", "macos", "linux", "ios"]

Platform

Platform = Literal["chrome", "firefox", "safari", "edge"]

ISO639_1

ISO639_1 = Literal["aa", "ab", "ae", ...]

BasicResponse

class BasicResponse(BaseModel):
    success: bool

Session

class Session(BaseModel):
    id: str
    team_id: str = Field(alias="teamId")
    status: SessionStatus
    created_at: datetime = Field(alias="createdAt")
    updated_at: datetime = Field(alias="updatedAt")
    start_time: Optional[int] = Field(default=None, alias="startTime")
    end_time: Optional[int] = Field(default=None, alias="endTime")
    duration: Optional[int] = None
    session_url: str = Field(alias="sessionUrl")

SessionDetail

class SessionDetail(Session):
    ws_endpoint: Optional[str] = Field(alias="wsEndpoint", default=None)
    live_url: str = Field(alias="liveUrl")
    token: str = Field(alias="token")

SessionListResponse

class SessionListResponse(BaseModel):
    sessions: List[Session]
    total_count: int = Field(alias="totalCount")
    page: int
    per_page: int = Field(alias="perPage")

ScreenConfig

class ScreenConfig(BaseModel):
    width: int = Field(default=1280, serialization_alias="width")
    height: int = Field(default=720, serialization_alias="height")

CreateSessionParams

class CreateSessionParams(BaseModel):
    use_stealth: bool = Field(default=False, serialization_alias="useStealth")
    use_proxy: bool = Field(default=False, serialization_alias="useProxy")
    proxy_server: Optional[str] = Field(default=None, serialization_alias="proxyServer")
    proxy_server_password: Optional[str] = Field(
        default=None, serialization_alias="proxyServerPassword"
    )
    proxy_server_username: Optional[str] = Field(
        default=None, serialization_alias="proxyServerUsername"
    )
    proxy_country: Optional[Country] = Field(
        default="US", serialization_alias="proxyCountry"
    )
    operating_systems: Optional[List[OperatingSystem]] = Field(
        default=None, serialization_alias="operatingSystems"
    )
    device: Optional[List[Literal["desktop", "mobile"]]] = Field(default=None)
    platform: Optional[List[Platform]] = Field(default=None)
    locales: List[ISO639_1] = Field(default=["en"])
    screen: Optional[ScreenConfig] = Field(default=None)
    solve_captchas: bool = Field(default=False, serialization_alias="solveCaptchas")
    adblock: bool = Field(default=False, serialization_alias="adblock")
    trackers: bool = Field(default=False, serialization_alias="trackers")
    annoyances: bool = Field(default=False, serialization_alias="annoyances")
    enable_web_recording: Optional[bool] = Field(
        default=True, serialization_alias="enableWebRecording"
    )
    extension_ids: Optional[List[str]] = Field(
        default=None, serialization_alias="extensionIds"
    )
    accept_cookies: Optional[bool] = Field(
        default=None, serialization_alias="acceptCookies"
    )
    url_blocklist: Optional[List[str]] = Field(default=None, serialization_alias="urlBlocklist")
    browser_args: Optional[List[str]] = Field(default=None, serialization_alias="browserArgs")

SessionRecording

class SessionRecording(BaseModel):
    type: int
    data: Any
    timestamp: int
    delay: Optional[int] = None

ImageCaptchaParam

class ImageCaptchaParam(BaseModel):
    image_selector: str
    input_selector: str