SPHYNX
esc
  • Loading
Open console

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.

curl
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_url
Output
https://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
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.

HTML
<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"
200
{
  "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

HTTPCodeWhen
403invalid_tokenThe token in the URL is bad or expired. Mint a new URL
404session_not_foundNo such session for this key, when minting
410session_closedThe session has ended, so there is nothing to watch
429connection_limitThe 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.