Get a widget session by ID
Retrieves a widget session. The bearer token is never returned on reads.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Workspace ID.
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
Session ID. Accepts the canonical wsess_… form or the external_id:<value> form.
Response
OK
WidgetSession is a delegated, narrowed credential for one visitor's use of a widget, minted server-to-server by the customer's backend. The session carries all customer-asserted context — tenant, subject, labels, secrets — and every conversation (objective) created through the widget inherits it. The bearer token returned at mint is short-lived and refreshed at the widget host; the session row is what makes revocation possible.
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
WidgetSessionSpec is the configuration of a session, fixed at mint.
The current lifecycle state of the session. Output only. Sessions are created STATE_ACTIVE; use :revoke to end one early.
STATE_UNSPECIFIED, STATE_ACTIVE, STATE_EXPIRED, STATE_REVOKED, STATE_EXHAUSTED Names of the secrets attached to the session. Values are write-only: provided at creation, encrypted at rest, and interpolated into tool-call headers server-side — never returned by any API.
WidgetSessionInfo provides read-only server-derived data about a session.