Python SDK reference

from rayobrowse import Rayobrowse

client = Rayobrowse(
    endpoint="https://browser.rayobyte.com",
    api_key="rb_live_YOUR_KEY",
    timeout=120.0,
)

Constructor

Parameter	Type	Default	Description
endpoint	str	"http://localhost:9222"	Gateway base URL. Always pass the cloud endpoint, "https://browser.rayobyte.com". The built-in value reaches nothing and raises ConnectionFailedError
api_key	str | None	None	Your rb_live_ key
timeout	float	120.0	HTTP timeout in seconds

A browser can take tens of seconds to come up on a busy pool. Dropping timeout to something short gives you a client-side timeout on a create that then succeeds, leaving a session running that your code has no id for.

connect_url(**kwargs) -> str

Creates a browser and returns its CDP WebSocket URL. Pass the result to playwright.chromium.connect_over_cdp().

Parameter	Type	Default	Description
proxy	str	—	Required. scheme://user:pass@host:port
os	str	"windows"	windows, android, linux, macos
headless	bool	False	Run without a window
vnc	bool	False	Request a live-view URL
max_lifetime	int | None	None	Seconds. Omitted means 7200, clamped into 120 to 86400
browser_language	str | None	None	Accept-Language value
**kwargs			Passed through as query parameters, such as screen_width_min=1280

The accepted query parameters are listed on Connecting.

reconnect_url(session_id: str, *, vnc: bool = False) -> str

The CDP URL of a session that is already running. Creates nothing and takes no concurrency slot. Raises BrowserCreateError with status_code 410 if the session has ended, or 404 if the id is not one of your sessions. Pass the last_session_id value, not the br_ id inside a CDP URL.

close(session_id: str | None = None) -> None

Closes the given session, or the browser from the most recent connect_url() when no id is passed. A no-op when there is neither. Either id works: the last_session_id value or the br_ id at the end of the CDP URL.

list_browsers() -> list[dict]

Your running sessions, one dict per session.

get_health() -> dict

The gateway’s GET /health response.

Properties

Property	Type	Description
last_session_id	str | None	br_ id from the last connect_url()
last_vnc_url	str | None	Live-view URL, set only when vnc=True was passed and the browser came up with one

Exceptions

Exception	Raised when
RayobrowseError	Base class for everything below
BrowserCreateError	Any other non-200 answer. Carries status_code and body. A bad key is 401 (there is no separate auth exception), a missing or malformed proxy is 400, a proxy the browser cannot get through is 422
ConnectionFailedError	The gateway could not be reached
ConcurrencyLimitError	A 429. Carries limit, active, retry_after
RateLimitError	A 429. Carries retry_after

In 2.2.0 the two 429 classes do not reliably match the limit that was hit, and neither carries the response’s code. Catch both and sleep for retry_after, which comes from the retry-after header: 5 seconds for a full account, 60 for the rate limit. To tell the two limits apart, read code from the HTTP API directly. See Limits.

The 400 and 422 bodies on /connect are plain text, not JSON:

from rayobrowse import BrowserCreateError

try:
    client.connect_url(os="windows")
except BrowserCreateError as e:
    print(e.status_code)  # 400
    print(e.body)         # A proxy is required for this account. ... (no proxy supplied)

Neither is worth retrying. Fix the proxy.