v56

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-01142337440.5 KB

WidgetSessionService

Widget Sessions

List widget sessions

Lists widget sessions in a workspace, filterable by widget, tenant, subject, and state

get/v1/workspaces/{workspaceId}/widget_sessions

Path parameters

workspaceIdstring required

Example:workspace_01HXKD2E5NQM3T9AYWCF133E3Q

Workspace ID.

Query parameters

limitinteger

Maximum number of results to return.

cursorstring

Pagination cursor from previous response.

widgetIdstring

Filter to sessions on a specific widget. Accepts the canonical wgt_… form or the external_id:<value> form.

tenantIdstring

Filter to sessions belonging to a tenant. Accepts the canonical tenant_… form or the external_id:<value> form.

subjectIdstring

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.

state'STATE_UNSPECIFIED' | 'STATE_ACTIVE' | 'STATE_EXPIRED' | 'STATE_REVOKED' | 'STATE_EXHAUSTED' enum

Filter by state.

labelsstring

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).

sortOrderstring

Sort order for results (asc or desc by creation time).

includeInfoboolean

When true, the info field on each returned session is populated. Requests with this flag count more against your rate limit.

Response

Example response

{
  "items": [
    {
      "metadata": {
        "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
        "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
        "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08"
      },
      "spec": {
        "widgetId": "wgt_01HXKD2E5NQM3T9AYWCFMZZZBD",
        "tenant": {
          "id": "acme-corp",
          "name": "Acme Corp"
        },
        "subject": {
          "id": "customer-user-42",
          "name": "Jane Doe"
        }
      },
      "info": {
        "tenant": {
          "id": "tenant_01HXKD2E5NQM3T9AYWCF133E3Q",
          "externalId": "acme-corp",
          "name": "Acme Corp"
        },
        "subject": {
          "id": "subj_01HXKD2E5NQM3T9AYWCFQAZGFV",
          "externalId": "customer-user-42",
          "name": "Jane Doe"
        },
        "host": "k7m2xq9fp4wn.widgets.cadenya.com"
      }
    }
  ]
}