Skip to main content
POST
/
v1
/
sessions
/
{id}
/
embed
/
live
Live View Embed
curl --request POST \
  --url https://api.bctrl.ai/v1/sessions/{id}/embed/live \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "interactive": true,
  "showControls": true,
  "viewerMode": "<string>"
}
'
{
  "token": "<string>",
  "iframeUrl": "<string>",
  "expiresAt": "<string>",
  "expiresInSeconds": 123
}
​
id
string
required
Session ID.
​
interactive
boolean
Enable mouse and keyboard input in the viewer. Default: false.
​
showControls
boolean
Show navigation toolbar in the viewer. Default: true.
​
viewerMode
string
Tab-following mode: last_used (follows the most recently used tab) or automation (follows the automation driver). Default: last_used.
The token is valid for 24 hours. When interactive is enabled, the viewer captures mouse and keyboard events and forwards them to the browser session via WebSocket.

​
Examples

const live = await session.live({
  interactive: true,
  showControls: true,
  viewerMode: 'automation',
});
console.log(live.iframeUrl); // embeddable URL
console.log(live.token);     // JWT token
console.log(live.expiresAt); // token expiry

​
Response

​
token
string
required
Signed JWT for authenticated live viewing.
​
iframeUrl
string
required
Embeddable URL for the live viewer.
​
expiresAt
string
required
Token expiration time (ISO datetime).
​
expiresInSeconds
number
required
Token TTL in seconds (86400).
Response Example
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "iframeUrl": "/embed/live/sess_abc123?token=eyJhbGci...",
  "expiresAt": "2025-01-16T10:00:00Z",
  "expiresInSeconds": 86400
}