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

# listShards (database command)

## Definition

The [`listShards`](https://www.mongodb.com/docs/manual/reference/command/listshards.md#mongodb-dbcommand-dbcmd.listShards) command returns a list of the configured shards in a sharded cluster. [`listShards`](https://www.mongodb.com/docs/manual/reference/command/listshards.md#mongodb-dbcommand-dbcmd.listShards) is only available on [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instances and must be issued against the `admin` database.

## Compatibility

This command is available in deployments hosted in the following environments:

- [MongoDB Atlas](https://www.mongodb.com/docs/atlas): The fully managed service for MongoDB deployments in the cloud

* [MongoDB Enterprise](https://www.mongodb.com/docs/manual/administration/install-enterprise.md#std-label-install-mdb-enterprise): The subscription-based, self-managed version of MongoDB

* [MongoDB Community](https://www.mongodb.com/docs/manual/administration/install-community.md#std-label-install-mdb-community-edition): The source-available, free-to-use, and self-managed version of MongoDB

## Syntax

The command has the following syntax:

```javascript
db.runCommand(
  {
    listShards: 1
  }
)
```

## Command Fields

The command takes the following fields:

| Field | Type | Description |
| --- | --- | --- |
| `listShards` | integer | `1` requests a list of configured shards. |
| `filter` | document | Specifies a filter for the shards in return documents. **New in version 8.3** |
| `filter.draining` | boolean | Filters return documents based on whether the shards are [draining.](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-draining) When set to `true`, the command returns an array the shards being drained by the balancer.; When set to `false`, the command returns an array of all shards not being drained by the balancer.; When unset, the command returns all shards, regardless of their draining status. **New in version 8.3** |

## Output Fields

[`listShards`](https://www.mongodb.com/docs/manual/reference/command/listshards.md#mongodb-dbcommand-dbcmd.listShards) returns a document that includes:

- A `shards` field which contains an array of documents, each describing one shard. Each document may contain the following fields:

  | Field | Description |
  | --- | --- |
  | `_id` | Name of the shard. |
  | `host` | Hostname of the shard. If the shard is a replica set, `host` lists the hostname of each mongod instance in the replica set. |
  | `draining` | If `true`, indicates that the [`startShardDraining`](https://www.mongodb.com/docs/manual/reference/command/startsharddraining.md#mongodb-dbcommand-dbcmd.startShardDraining) or the [`removeShard`](https://www.mongodb.com/docs/manual/reference/command/removeshard.md#mongodb-dbcommand-dbcmd.removeShard) commands have been called for this shard and it's in the process of being drained. |
  | `tags` | List of [zones](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-zone) to which the shard belongs. |
  | `state` | Internal field used during the [addShard (database command)](https://www.mongodb.com/docs/manual/reference/command/addshard.md#std-label-sharding-add-shard) sequence to ensure that all steps and configuration necessary to add the shard to the cluster are completed. |

- The `ok` status field, the `operationTime` field, and the `$clusterTime` field for the operation. For details on these fields, see [Response.](https://www.mongodb.com/docs/manual/reference/method/db.runcommand.md#std-label-command-response)

## Example

The following operation runs [`listShards`](https://www.mongodb.com/docs/manual/reference/command/listshards.md#mongodb-dbcommand-dbcmd.listShards) against the [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) `admin` database:

```javascript
db.adminCommand({ listShards: 1 })
```

The following document is an example of the output from a [`listShards`](https://www.mongodb.com/docs/manual/reference/command/listshards.md#mongodb-dbcommand-dbcmd.listShards) command:

```javascript
{
  "shards": [
    {
      "_id": "shard01",
      "host": "shard01/host1:27018,host2:27018,host3:27018",
      "state": 1
    },
    {
      "_id": "shard02",
      "host": "shard02/host4:27018,host5:27018,host6:27018",
      "tags": [ "NYC" ],
      "state": 1
    },
    {
      "_id": "shard03",
      "host": "shard03/host7:27018,host8:27018,host9:27018",
      "state": 1
    }
  ],
  "ok": 1,
  "$clusterTime" : {
     "clusterTime" : Timestamp(1510716515, 1),
     "signature" : {
        "hash" : BinData(0,"B2ViX7XLzFLS5Fl9XEuFXbwKIM4="),
        "keyId" : Long("6488045157173166092")
     }
  },
  "operationTime" : Timestamp(1510716515, 1)
}
```