Sessions & HITL
Check whether the sign-in you sent was completed
Every connect link created for this tenant with its current state — pending, active, connected, failed or expired. The token is never returned.
list_connections
What it is
The job: Stop an agent from re-running a task before the user has actually signed in.
The loop connect_account starts has a gap in it: you send a link and then you are waiting on a human. list_connections closes it. Each link reports its state, its host and account, and the timestamps around it, so an agent can wait rather than burning a run on a session that does not exist yet.
The five states are worth reading precisely. `pending` means the link has not been opened; `active` means someone is in the middle of the sign-in; `connected` is the one you are waiting for; `failed` and `expired` mean mint a new one. The link token itself is never returned — it is shown once, at creation.
The call
Call it exactly like this.
Copied from the tool's registration and the route handler — not paraphrased.
// MCP tool call — server "twin-browser"
{
"tool": "list_connections",
"arguments": {}
}curl -X GET "https://twin-browser.com/api/v1/connect/sessions" \
-H "Authorization: Bearer $TWIN_API_KEY"Returns
{ "sessions": [ { "id": "…", "host": "example.com", "account": "work",
"status": "connected", "created_at": "…", "expires_at": "…",
"connected_at": "…", "error": null } ] }What it costs
Free
A metadata read, and deliberately cheap to poll — it is meant to sit in an agent’s wait loop.
See the full rate cardWhich one
When a different tool is the right call.
The honest answer is often the neighbouring tool. These are the trades.
list_accountslist_connections is about links in flight; list_accounts is about logins you already hold. A completed connection shows up in both — as `connected` here, and as a usable label there.
list_accountsKeep going