Book a demo

list_sessions

List an org's active sessions

read collection tenant-private since 2026-10-01

Lists the org's active sessions, most recently active first: each with the person, whether it is a sign-in or an MCP connection, when it started and was last seen, where (a masked address and the browser), how the person signed in, and whether it is the session making this call. Give user_id to list one person's; a member who is not an admin lists only their own.

Contract

shape
collection
authority
read
evidence
none
subscription
false
permission
any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
idempotency
safe
emits
none
MCP tool
list_sessions
REST
POST https://api.containertradehq.com/v1/cap/list_sessions

Idempotency: a read: calling again changes nothing

Inputs

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org whose sessions to list.
user_iduser_idoptionaltradehq-user-id; 1 to 20 characters
Only this person's sessions. A member who is not an admin gives their own.

Paginated: next next_after · page_max 1000 · walk_max 1000 · ceiling declared

Response

  • items · object[]
  • next_after · stringnull · Pass as `after` for the next page; null on the last one.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "session_id": {
            "type": "string",
            "description": "The session: what revoke_sessions takes.",
            "x-data-class": "operational"
          },
          "user_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20,
            "pattern": "^[A-Za-z0-9_-]{1,20}$",
            "format": "tradehq-user-id",
            "description": "The person.",
            "x-data-class": "operational"
          },
          "email": {
            "anyOf": [
              {
                "type": [
                  "string",
                  "null"
                ]
              },
              {
                "const": "•••",
                "description": "Masked by the caller's data policy."
              },
              {
                "type": "null",
                "description": "Denied by the caller's data policy."
              }
            ],
            "description": "The person's email address.",
            "x-data-class": "personal"
          },
          "surface": {
            "type": "string",
            "enum": [
              "clerk",
              "mcp"
            ],
            "description": "clerk: a sign-in. mcp: an MCP connection.",
            "x-data-class": "operational"
          },
          "started_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the session was first seen.",
            "x-data-class": "operational"
          },
          "last_seen_at": {
            "type": "string",
            "format": "date-time",
            "description": "Its last request, to the minute.",
            "x-data-class": "operational"
          },
          "ip_masked": {
            "anyOf": [
              {
                "type": [
                  "string",
                  "null"
                ]
              },
              {
                "const": "•••",
                "description": "Masked by the caller's data policy."
              },
              {
                "type": "null",
                "description": "Denied by the caller's data policy."
              }
            ],
            "description": "Where from, masked.",
            "x-data-class": "personal"
          },
          "user_agent": {
            "type": [
              "string",
              "null"
            ],
            "description": "The browser or client it last named.",
            "x-data-class": "operational"
          },
          "factors": {
            "type": "string",
            "enum": [
              "sso_idp_mfa",
              "sso",
              "totp",
              "passkey",
              "magic_link",
              "unknown"
            ],
            "description": "How the person signed in.",
            "x-data-class": "operational"
          },
          "current": {
            "type": "boolean",
            "description": "Whether it is the session making this call.",
            "x-data-class": "operational"
          }
        },
        "required": [
          "session_id",
          "user_id",
          "email",
          "surface",
          "started_at",
          "last_seen_at",
          "ip_masked",
          "user_agent",
          "factors",
          "current"
        ],
        "additionalProperties": false
      },
      "maxItems": 1000
    },
    "next_after": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pass as `after` for the next page; null on the last one."
    }
  },
  "required": [
    "items",
    "next_after"
  ],
  "additionalProperties": false
}

Refusals

  • security_policy_unenforced · 422 · the org's stored security settings do not parse; the step that applies them refuses the org's requests with the same code until a person restores them

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF
MobileF
APIF
MCPF
VoiceD4
PushN
OneBoxN
OutboundN
  • Voice: degraded: visualization
  • Push: emits nothing
  • OneBox: no document originates a session
  • Outbound: crosses to no counterparty

Events

None emitted.

Related

grant_unit_role, impersonate_user, list_unit_access, revoke_sessions, revoke_unit_role, set_member_role