Python SDK reference

from rayobrowse import Rayobrowse

client = Rayobrowse(api_key="rb_live_YOUR_KEY")

Constructor

Parameter	Type	Default	Description
endpoint	str | None	None	Gateway base URL. Left out, the client reads RAYOBYTE_ENDPOINT from the environment and falls back to DEFAULT_ENDPOINT
api_key	str | None	None	Your rb_live_ key
timeout	float	120.0	HTTP timeout in seconds

rayobrowse.DEFAULT_ENDPOINT is https://browser.rayobyte.com. The resolved value is on client.endpoint.

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.

close_browser(browser_id: str) -> bool

Closes one browser by id. True also comes back for an id that is not a live session, with a warning on the rayobrowse logger saying it was not found, so the return value is not proof a session existed. list_browsers() is.

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 missing or malformed proxy is 400, a proxy the browser cannot get through is 422, a rejected key is 401
ConnectionFailedError	The gateway could not be reached
ConcurrencyLimitError	A 429 for the concurrent-browser limit. Carries limit, active, retry_after
RateLimitError	A 429 for the per-minute launch limit. Carries retry_after

There is no auth exception in this SDK. A rejected key is BrowserCreateError with status_code 401 and {"error":"Invalid API key"} in body. The Node.js SDK raises AuthError for the same answer, so code ported between the two has to change here.

Each 429 class names the limit that was hit: ConcurrencyLimitError when your browsers are all running, RateLimitError when more than 60 launches went out in the last minute. retry_after is a whole number of seconds and never negative, 5 for a full account and 60 for the rate limit. 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.