> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!--
Tab options on this page. Append to the .md URL to filter:
  ?tabs=<id,...>   select specific tabs (e.g. ?tabs=nodejs,shell)
  ?allTabs=true    include every tab
  (no param)       default: one tab per tabset

Available tabs:
  drivers: shell, nodejs
-->

# $listSessions (aggregation stage)

## Definition

Lists all sessions stored in the [`system.sessions`](https://www.mongodb.com/docs/manual/reference/config-database.md#mongodb-data-config.system.sessions) collection in the `config` database. These sessions are visible to all members of the MongoDB deployment.

**Important:**

When a user creates a session on a [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) or [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance, the record of the session initially exists only in-memory on the instance; i.e. the record is local to the instance. Periodically, the instance will sync its cached sessions to the [`system.sessions`](https://www.mongodb.com/docs/manual/reference/config-database.md#mongodb-data-config.system.sessions) collection in the `config` database, at which time, they are visible to [`$listSessions`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/listsessions.md#mongodb-pipeline-pipe.-listSessions) and all members of the deployment. Until the session record exists in the `system.sessions` collection, you can only list the session via the [`$listLocalSessions`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/listlocalsessions.md#mongodb-pipeline-pipe.-listLocalSessions) operation.

To run [`$listSessions`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/listsessions.md#mongodb-pipeline-pipe.-listSessions), it must be the first stage in the pipeline.

The stage has the following syntax:

```javascript
{ $listSessions: <document> }
```

The [`$listSessions`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/listsessions.md#mongodb-pipeline-pipe.-listSessions) stage takes a document with one of the following contents:

| Field | Description |
| --- | --- |
| `{ }` | If running with access control, returns all sessions for the current authenticated user. If running without access control, returns all sessions. |
| `{ users: [ { user: <user>, db: <db> }, ... ] }` | Returns all sessions for the specified users. If running with access control, the authenticated user must have privileges with [`listSessions`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-listSessions) action on the cluster to list sessions for other users. |
| `{ allUsers: true }` | Returns all sessions for all users. If running with access control, the authenticated user must have privileges with [`listSessions`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-listSessions) action on the cluster. |

## Restrictions

`$listSessions` is not allowed in [transactions.](https://www.mongodb.com/docs/manual/core/transactions.md#std-label-transactions)

## Examples

### MongoDB Shell

### List All Sessions

From the [`system.sessions`](https://www.mongodb.com/docs/manual/reference/config-database.md#mongodb-data-config.system.sessions) collection, the following aggregation operation lists all sessions:

**Note:**

If running with access control, the current user must have privileges with [`listSessions`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-listSessions) action on the cluster.

```javascript
use config

db.system.sessions.aggregate( [  { $listSessions: { allUsers: true } } ] )
```

### List All Sessions for the Specified Users

From the [`system.sessions`](https://www.mongodb.com/docs/manual/reference/config-database.md#mongodb-data-config.system.sessions) collection, the following aggregation operation lists all sessions for the specified user `myAppReader@test`:

**Note:**

If running with access control and the current user is not the specified user, the current user must have privileges with [`listSessions`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-listSessions) action on the cluster.

```javascript
use config

db.system.sessions.aggregate( [ { $listSessions: { users: [ {user: "myAppReader", db: "test" } ] } } ] )
```

### List All Sessions for the Current User

From the [`system.sessions`](https://www.mongodb.com/docs/manual/reference/config-database.md#mongodb-data-config.system.sessions) collection, the following aggregation operation lists all sessions for the current user **if** run with access control:

```javascript
use config

db.system.sessions.aggregate( [ { $listSessions: { } } ] )
```

If run **without** access control, the operation lists all sessions.

## Output

[`$listSessions`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/listsessions.md#mongodb-pipeline-pipe.-listSessions) returns a cursor with one document per session. Each document has the following prototype:

```none
{
   _id: {
      id: <UUID>,
      uid: <BinData>
   },
   lastUse: <date>
}
```

| Field | Type | Description |
| --- | --- | --- |
| `_id.id` | UUID | The universally unique identifier (UUID) of the session. |
| `_id.uid` | BinData | A hash of the authenticated user's credentials associated with the session. |
| `lastUse` | date | The date and time the session was last used. |