# getSessionList()

Retrieves a list of sessions. Returns a [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response.md) object with a `data` property that contains an array of [`Session`](https://clerk.com/docs/reference/backend/types/backend-session.md) objects, and a `totalCount` property that indicates the total number of sessions for the specified user.

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

## `SessionListParams`

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

| Name      | Type          | Description                                                                                                                                                           |
| --------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| clientId? | string        | The client ID to retrieve the list of sessions for.                                                                                                                   |
| userId?   | string        | The user ID to retrieve the list of sessions for.                                                                                                                     |
| status?   | SessionStatus | The status of the session.                                                                                                                                            |
| limit?    | number        | 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. |
| offset?   | number        | 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`

```tsx
type SessionStatus =
  | 'abandoned'
  | 'active'
  | 'pending'
  | 'ended'
  | 'expired'
  | 'removed'
  | 'replaced'
  | 'revoked'
```

| Value       | Description                                                                                                            |
| ----------- | ---------------------------------------------------------------------------------------------------------------------- |
| `abandoned` | The session was abandoned client-side.                                                                                 |
| `active`    | The session is valid and all activity is allowed.                                                                      |
| `pending`   | The user has signed in but hasn't completed [session tasks](https://clerk.com/docs/guides/configure/session-tasks.md). |
| `ended`     | The user signed out of the session, but the `Session` remains in the `Client` object.                                  |
| `expired`   | The period of allowed activity for this session has passed.                                                            |
| `removed`   | The user signed out of the session and the `Session` was removed from the `Client` object.                             |
| `replaced`  | The session has been replaced by another one, but the `Session` remains in the `Client` object.                        |
| `revoked`   | The application ended the session and the `Session` was removed from the `Client` object.                              |

## Examples

> Using `clerkClient` varies based on the SDK you're using. Refer to the [overview](https://clerk.com/docs/reference/backend/overview.md) for usage details, including guidance on [how to access the `userId` and other properties](https://clerk.com/docs/reference/backend/overview.md#example-get-the-user-id-and-other-properties).

Retrieve a list of sessions for a specific `userId`:

```tsx
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`](https://clerk.com/docs/reference/backend/types/paginated-resource-response.md) includes `data`, which is an array of [`Session`](https://clerk.com/docs/reference/backend/types/backend-session.md) objects, and `totalCount`, which indicates the total number of sessions for the specified user.

```tsx
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](https://clerk.com/docs/reference/backend-api/tag/sessions/GET/sessions){{ target: '_blank' }} for more information.

---

## Sitemap

[Overview of all docs pages](https://clerk.com/docs/llms.txt)