Show a user's active or historical sessions
Account security settings
Clerk · Module
sessions.getSessionList
Lists sessions for a specified client or user, with optional status filtering and pagination. The result contains session data plus the total matching-session count.
How it works
Call this server-side method with a client or user identifier, optionally adding status and pagination controls. The promise resolves to a paginated response whose data contains Session objects and whose totalCount reports the overall number of matching sessions.
Syntax
function getSessionList(params: SessionListParams): Promise<PaginatedResourceResponse<Session[]>>Parameters
| Name | Type | Description |
|---|---|---|
clientId | string | The ID of the client to get sessions for. |
userId | string | The ID of the user to get sessions for. |
limit | number | Maximum items per request; an integer greater than zero and less than 501. Defaults to 10. |
offset | number | Number of items to skip while paginating; an integer greater than or equal to zero. Defaults to 0. |
status | SessionStatus | The status of the sessions to get. |
Returns
Promise<PaginatedResourceResponse<Session[]>>
Key points
- Use the method to enumerate sessions belonging to one client or one user.
- The default ordering places recently created sessions before older ones.
- Read the sessions from the response's data property rather than expecting the promise to resolve to an array.
- Use totalCount to know how many matching sessions exist overall.
- The limit parameter controls the maximum number of sessions included in one request.
- Use offset to skip earlier results when requesting a later page.
Common mistakes
- A request must identify either the client or the user; calling it without one of those identifiers is invalid.
- Keep limit between 1 and 500 inclusive; larger values are not accepted.
- Offset is intended for pagination together with limit rather than as an independent paging control.
Example: List a user's expired sessions
const userId = 'user_123'
const { data, totalCount } = await clerkClient.sessions.getSessionList({
userId,
status: 'expired',
limit: 20,
})
console.log(`Found ${totalCount} sessions`)
for (const session of data) {
console.log(session.id, session.status)
}This server-side example retrieves up to 20 expired sessions for one user and reads both the returned session array and its total count.
When to use it
Inspect sessions associated with a specific client
Administrative support
Build session tables without loading every result at once
Paginated dashboards
Interview questions
QWhat does getSessionList return?
It accepts a SessionListParams object and returns a promise of PaginatedResourceResponse<Session[]>. The response exposes data for the matching sessions and totalCount for the total number of sessions.
Follow-up: Why should callers destructure totalCount instead of treating the result as an array? The current response is an object containing both data and totalCount, not a direct session array.
QWhich inputs control scope, filtering, and pagination?
The call must include either clientId or userId. It can additionally filter by status and page through results with limit and offset.
Follow-up: How would you retrieve the second page? Supply a positive limit and set offset to the number of items skipped, such as limit: 20 and offset: 20.
QWhat are the default ordering and pagination behaviors?
Results are ordered newest first by creation date unless the documentation specifies another ordering option. The default limit is 10 and the default offset is 0.
Follow-up: What should a UI use totalCount for? It can determine the total number of matching sessions and calculate page availability.
Related
SessionListParamsPaginatedResourceResponseSessionSessionStatussessions.getSessionsessions.revokeSession