Skip to main content
Docs

getSessionList()

Retrieves a list of sessions. Returns a PaginatedResourceResponse object with a data property that contains an array of Session objects, and a totalCount property that indicates the total number of sessions for the specified user.

function getSessionList(
  queryParams: SessionListParams,
): Promise<PaginatedResourceResponse<Session[]>>

SessionListParams

getSessionList() requires either clientId or userId to be provided.

  • Name
    clientId?
    Type
    string
    Description

    The client ID to retrieve the list of sessions for.

  • Name
    userId?
    Type
    string
    Description

    The user ID to retrieve the list of sessions for.

  • Name
    status?
    Type
    SessionStatus
    Description

    The status of the session.

  • Name
    limit?
    Type
    number
    Description

    The number of results to return. Must be an integer greater than zero and less than 501. Can be used for paginating the results together with offset. Defaults to 10.

  • Name
    offset?
    Type
    number
    Description

    Skip the first offset results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with limit. Defaults to 0.

SessionStatus

type SessionStatus =
  | 'abandoned'
  | 'active'
  | 'pending'
  | 'ended'
  | 'expired'
  | 'removed'
  | 'replaced'
  | 'revoked'
ValueDescription
abandonedThe session was abandoned client-side.
activeThe session is valid and all activity is allowed.
pendingThe user has signed in but hasn't completed session tasks.
endedThe user signed out of the session, but the Session remains in the Client object.
expiredThe period of allowed activity for this session has passed.
removedThe user signed out of the session and the Session was removed from the Client object.
replacedThe session has been replaced by another one, but the Session remains in the Client object.
revokedThe application ended the session and the Session was removed from the Client object.

Examples

Note

Importing clerkClient varies based on your framework. Refer to the Backend SDK overview for usage details, including guidance on how to access the userId and other properties.

Retrieve a list of sessions for a specific userId:

const userId = 'user_123'

const response = await clerkClient.sessions.getSessionList({ userId })

Filter by session status

In this example, a list of sessions with a status of 'expired' is retrieved. You can see that the returned PaginatedResourceResponse includes data, which is an array of Session objects, and totalCount, which indicates the total number of sessions for the specified user.

const userId = 'user_123'

const status = 'expired'

const response = await clerkClient.sessions.getSessionList({ userId, status })

Backend API (BAPI) endpoint

This method in the SDK is a wrapper around the BAPI endpoint GET/sessions. See the BAPI reference for more information.

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on