Resource models
Interpret session, grant, handoff, file, and pagination fields correctly.
HTTP and TypeScript use camelCase. Python models expose corresponding snake_case names.
BrowserSession
| Fields | Meaning |
|---|---|
| id, projectId, region | Resource identity, project ownership, fixed browser placement |
| status | starting, ready, closing, closed, or failed |
| controller | automation, human, or none |
| controlEpoch | Decimal integer string identifying control changes |
| handoffId, latestHandoff | Active handoff ID and latest handoff summary |
| timeoutSeconds | Approved remote lifetime |
| idleTimeoutSeconds, lastActivityAt | Optional idle budget and last activity time |
| browser | Immutable creation configuration |
| profile | Optional Profile ID, persistence choice and save outcome |
| createdAt, startupDeadlineAt | Creation and startup deadline |
| startedAt, expiresAt | Ready time and running expiry; nullable before readiness |
| endedAt, releasedAt | Management end and confirmed resource release; distinct signals |
| closeReason, error | Ending reason and optional code/message |
| downloadDirectory | Remote session download location while available |
| metadata | Caller-provided string correlation values |
Never convert controlEpoch to a JavaScript Number or compare it lexicographically. Use SDK checkpoint helpers or arbitrary-precision integer comparison.
A closed or failed status does not replace the resource-release timestamp. A ready snapshot alone also does not imply automation currently controls the browser.
ConnectionGrant
Fields: type, optional mode, url, expiresAt. URL is a credential. CDP grants require automation control; Live control grants require the active handoff. A Live view grant is read-only.
Expiry limits new handshakes; existing connections remain subject to session expiry and authorization changes.
Handoff
Fields: id, browserSessionId, status, reason, createdAt, completedAt.
The lifecycle is requested → active → returning → completed, with cancelled for a handoff that cannot finish. Returning is not yet automation control. A stable resumed session must report both the completed handoff and automation control.
SessionFile
Fields: id, origin, status, filename, contentType, sizeBytes, browserPath, error, createdAt.
Origin is upload or download. Status is uploading, downloading, ready, failed, or deleted. browserPath refers to the remote browser; it is not a path your backend can read locally.
Lists
Page responses contain items and nullable nextCursor. The Python property is next_cursor. Pass the cursor to the next call; an SDK list call does not automatically retrieve every page.