Inspect one session
A backend endpoint needs details about a known authenticated session.
Clerk · Module
sessions.getSession
Retrieves a specific Clerk Session by its session ID. It returns a promise resolving to the Session object.
How it works
Call clerkClient.sessions.getSession with a Clerk session ID to retrieve the corresponding Session object asynchronously. The SDK method wraps Clerk's Backend API endpoint for fetching an individual session.
Syntax
function getSession(sessionId: string): Promise<Session>Parameters
| Name | Type | Description |
|---|---|---|
sessionId | string | The ID of the session to get. |
Returns
Promise<Session>
Key points
- Retrieves one Clerk Session identified by the supplied session ID.
- The method takes a string session ID and resolves asynchronously to a Session object.
- Clerk implements the SDK method as a wrapper around its Backend API.
- The underlying backend route uses the session ID as a path parameter.
- After retrieval, consult the SDK usage guidance for accessing the session's user ID and other properties.
Common mistakes
- The argument must be the target session's ID, not a user ID or client ID.
- The exact way to obtain
clerkClientdepends on the Clerk SDK in use; follow that SDK's setup guidance.
Example: Retrieve a session
import { clerkClient } from '@clerk/nextjs/server'
const sessionId = 'sess_123'
const session = await clerkClient.sessions.getSession(sessionId)
console.log(session.id)Fetches a session by its Clerk session ID and logs the returned session identifier.
When to use it
Read session properties
Server-side code has a session ID and needs associated session properties.
Backend session lookup
An administrative workflow needs to fetch a session through Clerk's backend client.
Interview questions
QWhat is the signature and purpose of sessions.getSession?
It accepts one string argument, sessionId, and returns a Promise<Session>. The method retrieves the specified Clerk session through the backend SDK.
Follow-up: What backend operation does it represent? It is an SDK wrapper around GET/sessions/{session_id}.
QHow do you call sessions.getSession?
Pass the session identifier to clerkClient.sessions.getSession. Await the promise to receive the corresponding Session object.
Follow-up: How would you adapt the call across Clerk integrations? Use the integration's documented way to access clerkClient, because that setup varies by SDK.
QHow does getSession differ from a session-list operation?
The method is intended for backend use through Clerk's backend client. It retrieves one session rather than listing sessions for a user or client.
Follow-up: Which related operation lists multiple sessions? sessions.getSessionList returns a paginated response and requires either a client ID or user ID.
Related
clerkClientsessions.getSessionListSessionuserId