Drıftstack docs
Docs

Watch a session you started from code

You might be here because: “watch my API session in the app” · “see the browser of a session I started from code” · “API session” · “session started from the SDK is not in Profiles” · “Only the team owner and admins can see the team’s sessions” · “Watch is greyed out” · “driftstack://session/open” · “Choose proxy” · “a profile launches only through a proxy”

Short answer

A session your own program starts with POST /v1/agent-sessions and no profile_id has no profile row, so it is not in Profiles. It is listed under Sessions in the desktop app’s sidebar, labelled API session, with its id and when it started. Press Watch on its card to open its live iPhone window; Stop ends it. The app must be signed in to the account the API key belongs to, in the same workspace.

Check first

  • Are you signed in to the right account? Watch opens any active session of the signed-in account; a session on another account is not listed.
  • Team workspace? Only the team owner and admins can see the team’s sessions; a member sees the sentence “Only the team owner and admins can see the team’s sessions. Switch to Personal to see your own.”
  • Is the session still starting? Watch reads Starting… and is off until the session is running.
  • Launching a profile instead? A profile launches only through a proxy: choose one on its card, or set one for all (below).

Likely causes and fixes

  1. Where it is listed. Sidebar → Sessions (above Session log). The Command Center’s running-sessions link and ⌘K “Go to Sessions” open the same list. A session started from a profile reads Profile session · name there; one started without a profile reads API session — that includes a quick session started from the app’s New session button.

  2. Watch. Press Watch on the card. The app mints a viewing token and the window’s control key for the signed-in account and opens the session’s iPhone window — the same path the deep link below takes. Pressing Watch again focuses the window that is already open rather than opening a second one.

  3. The deep link. Your own tool can open the window directly: driftstack://session/open?session_id=agt_… opens that session in the desktop app. It needs the app installed and signed in to the account the session belongs to; a session that has ended answers “That session has ended.”

  4. Watch is off. The button says why in its tooltip: the session is still starting, you are offline, or the window is already opening. Offline, the list shows what it last loaded and says so.

  5. Team member. The team’s agent sessions (transcripts, live control) are kept to the owner and admins, so the list is refused to a member with the sentence above. Ask the owner for the admin role, or switch to Personal to see your own sessions.

  6. The list could not load. The banner says so and the last list stays on screen, marked with the time it last loaded. Press Refresh; if the API key was refused, check Settings.

  7. A profile that will not launch. A profile launches only through a proxy: choose one on its card or set one for all. A card with no proxy chosen shows Choose proxy (or Choose another proxy when the proxy it had was deleted); it opens the picker for that profile. With exactly one saved proxy, the picker offers Use “name” for this profile and Use “name” for all N profiles without one, and the banner at the top of Profiles offers the same for every profile that never chose one. Hiding that banner lasts until you reopen the app or another profile needs a proxy.

If it still fails

If the session is active (GET /v1/agent-sessions/:id reads status: active) and Watch still reports that it ended or could not open, press Talk to a person in this chat (or open Help) and include the session id and the sentence the app showed. No account action is needed.