List widget sessions
Every session in a workspace, filterable by widget, tenant, subject, and state. Tokens never appear.
spec (minus the token), its state, and (with includeInfo) the widget, agent, tenant, subject, and activity counters in info.
Filtering
widgetId, tenantId, and subjectId each accept the canonical id form or external_id:<value>. One catch on subjects: a subject’s external ID is only unique within its tenant, so the external_id: form of subjectId requires tenantId too.
state narrows to one lifecycle state:
What a row never shows
The bearer token. It exists in exactly one response, the create call, and secrets come back name-only. A leaked list response is annoying, not a credential spill.Related
Create a widget session
Revoke a widget session
List tenants
Get a widget session
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Workspace ID.
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
Query Parameters
Maximum number of results to return.
Pagination cursor from previous response.
Filter to sessions on a specific widget. Accepts the canonical wgt_…
form or the external_id:<value> form.
Filter to sessions belonging to a tenant. Accepts the canonical
tenant_… form or the external_id:<value> form.
Filter to sessions asserted for a subject. Accepts the canonical
subj_… form or the external_id:<value> form; the external_id form is
scoped within a tenant and requires tenant_id to also be set.
Filter by state.
STATE_UNSPECIFIED, STATE_ACTIVE, STATE_EXPIRED, STATE_REVOKED, STATE_EXHAUSTED Filters by metadata labels. Comma-separated key=value pairs, e.g. "env=prod,team=ai". A resource matches only if every pair matches exactly (AND semantics).
Sort order for results (asc or desc by creation time).
When true, the info field on each returned session is populated.
Requests with this flag count more against your rate limit.