Guides
Live view
Watch a session as it runs, in a browser tab or inside your own page.
At the end you are watching a session's browser while your code or an agent drives it. You need an API key and a running session.
Get the URL
Creating a session returns a live_view_url. Keep it along with the session ID.
CREATED=$(curl -s -X POST "$SPHYNX_URL/v1/sessions" \
-H "Authorization: Bearer $SPHYNX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"start_url": "https://example.com"}')
SESSION=$(echo "$CREATED" | jq -r .id)
echo "$CREATED" | jq -r .live_view_urlhttps://api.example/v1/sessions/sess_9f2c.../view?token=...Open it
Open the URL in a browser. It carries its own token, so it needs no API key and no header. Drive the session from another terminal and the view follows.
curl -s -X POST "$SPHYNX_URL/v1/sessions/$SESSION/navigate" \
-H "Authorization: Bearer $SPHYNX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://news.ycombinator.com"}'Embed it
Put the URL in an iframe to show the session inside your own page.
<iframe
src="LIVE_VIEW_URL"
style="width: 100%; aspect-ratio: 16 / 10; border: 0"
></iframe>Mint a fresh URL
The token in the URL is valid for token_expires_in_seconds, 1800 when issued, and can be reused until then. It works for the live view only, not for cdp_url. The URL is not on GET /v1/sessions/{id}. For a new one, call POST/v1/sessions/{id}/tokens on the running session.
Do this on your server and hand only the live_view_url to the page. The API key never has to reach a browser.
curl -s -X POST "$SPHYNX_URL/v1/sessions/$SESSION/tokens" \
-H "Authorization: Bearer $SPHYNX_API_KEY"const base = process.env.SPHYNX_URL;
async function liveViewUrl(sessionId: string): Promise<string> {
const res = await fetch(`${base}/v1/sessions/${sessionId}/tokens`, {
method: "POST",
headers: { Authorization: `Bearer ${process.env.SPHYNX_API_KEY}` },
});
if (!res.ok) throw new Error(`tokens: ${res.status}`);
const { live_view_url } = await res.json();
return live_view_url;
}import os
import requests
def live_view_url(session_id: str) -> str:
res = requests.post(
f"{os.environ['SPHYNX_URL']}/v1/sessions/{session_id}/tokens",
headers={"Authorization": f"Bearer {os.environ['SPHYNX_API_KEY']}"},
timeout=30,
)
res.raise_for_status()
return res.json()["live_view_url"]{
"cdp_url": "wss://api.example/v1/sessions/sess_9f2c.../cdp?token=...",
"live_view_url": "https://api.example/v1/sessions/sess_9f2c.../view?token=...",
"token_expires_in_seconds": 1800
}What watching does not do
- It is view only in v0. A viewer cannot click or type.
- It does not keep the session alive. Watching does not reset the idle clock, so a session nobody drives still ends after
idle_timeout_seconds. - It does not need the API key, so anyone who has the URL can watch until the token expires. Share it with that in mind.
- At most 5 viewers can watch one session at a time. One more is refused with 429
connection_limit.
Watch an agent run
Starting an agent run returns a live_view_url for the run's session. Open it next to the run's event stream to see each step as it happens. The console shows the live view of each running session.
What can go wrong
| HTTP | Code | When |
|---|---|---|
| 403 | invalid_token | The token in the URL is bad or expired. Mint a new URL |
| 404 | session_not_found | No such session for this key, when minting |
| 410 | session_closed | The session has ended, so there is nothing to watch |
| 429 | connection_limit | The session already has 5 viewers. Close one, then open the URL again |
Next
- Sessions: the session object and the tokens call.
- Authentication: how session tokens differ from the API key.
- Agent runs: give a task to an agent and watch it work.