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

Last updated