View and Embed Live Sessions
How to embed and share live browser sessions in your applications
Every Steel browser session comes with a debug URL that provides a flexible way to view and interact with the session. While Steel's dashboard includes a full-featured session viewer for monitoring your sessions, the debug URL feature allows you to implement custom viewing solutions in your applications and let viewers control browser sessions remotely.
PrerequisitesCopied!
-
A Steel API key
-
An active Steel browser session
-
Basic familiarity with HTML and JavaScript/Python
Getting the Debug URLCopied!
When creating a session through our API, the response includes a debugUrl
.
Here's how to retrieve it using Steel’s SDKs:
from steel import Steel
client = Steel()
session = client.sessions.create()
# Get the debug URL
debug_url = session.debug_url
print(f"Debug URL: {debug_url}")
import Steel from 'steel-sdk';
const client = new Steel();
const session = await client.sessions.create();
// Get the debug URL
const debugUrl = session.debugUrl;
console.log(`Debug URL: ${debugUrl}`);
Once you have the debug URL, you can open it directly in your browser to quickly view your session.
Embedding Sessions in Your ApplicationCopied!
For production use cases, you can embed the session view in your application using an iframe:
<iframe
src={session.debugUrl}
style="width: 100%; height: 600px; border: none;"
></iframe>
The view will automatically scale to fit the iframe container while maintaining aspect ratio.
Debug URLs are not authenticated. Anyone with access to a session's debug URL can view that session. Consider this when implementing session sharing features.
Configuration OptionsCopied!
Customize the embedded view using UTM parameters:
<iframe
src={`${session.debugUrl}?theme=light&interactive=true&showControls=true`}
style="width: 100%; height: 600px; border: none;"
></iframe>
Available parameters:
Parameter |
Type |
Default |
Description |
---|---|---|---|
|
string |
(empty) |
Optional: This will enable a single tab view of a particular pageId. You can fetch pageIds either directly from Playwright/Puppeteer or using the Live Details endpoint. |
|
string |
(empty) |
Optional: This will enable a single tab view of tab N where N is the index passed in. So if you want to only display the first page, passing in |
|
string |
|
Visual theme of the interface ( |
|
boolean |
|
When enabled, viewers can interact with the page through clicks, scrolling, and navigation |
|
boolean |
|
Shows/hides the URL input and navigation controls |
Common Use CasesCopied!
Sharing Session Views
Embed a fullscreen read-only session view:
<iframe
src={`${session.debugUrl}?interactive=false&showControls=false`}
style="width: 100%; height: 600px; border: none;"
></iframe>
Human-in-the-Loop Workflows
The debug URL feature is particularly useful for human-in-the-loop workflows, where you need to enable human intervention in automated processes. See our detailed guide on implementing human-in-the-loop workflows for more information.
Working with TabsCopied!
Multi-tab View
By default, the debug url will return a multi-tab view of the browser. When a new page/tab is created, the viewer will auto switch to that new tab. It will not switch back if the focus is set to a previous tab. When interactive=false
is appended to the debugUrl in the iframe, switching between tabs will be disabled (along with every other interaction), so be wary of that if you need to switch between tabs in a non-interactive view.
Single-tab View
When a pageId
or a pageIndex
is passed into the debug url, the browser view will only focus on that page and no other tabs will be shown. This is useful when you only want to present one tab to the user and either manually switch tabs (by passing in a different pageId
or pageIndex
) or just generally disable other pages.
TroubleshootingCopied!
-
If the iframe appears blank, ensure your session is still active and has actions sent to it like navigating to new pages.
-
If interaction isn't working, verify that
interactive=true
is set -
For sizing issues, check that your container has explicit dimensions (use the
dimensions
parameter when creating your session) -
Make sure your session hasn't timed out (default timeout is 5 minutes)
What's NextCopied!
Learn more about:
Implement Human-in-the-Loop ControlsHow to let users take control of Steel browser sessions
Session LifecycleLearn how to start and release browser sessions programatically.