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 codesproxy_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 trueextension_ids?: string[]
- Array of extension Idsaccept_cookies?: boolean
- Automatically Accept Cookies on the pageurl_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 statuspage?: 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