Navigation

Get All Clusters

Note

Groups and projects are synonymous terms. Your {GROUP-ID} is the same as your project ID. For existing groups, your group/project ID remains the same. The resource and corresponding endpoints use the term groups.

The Atlas API uses HTTP Digest Authentication. Provide a programmatic API public key and corresponding private key as the username and password when constructing the HTTP request.

For complete documentation on configuring API access for an Atlas project, see Configure Atlas API Access.

Base URL: https://cloud.mongodb.com/api/atlas/v1.0

Syntax

GET /api/atlas/v1.0/groups/{GROUP-ID}/clusters

Request Path Parameters

Path Element Required/Optional Description
GROUP-ID Required. Unique identifier for the project whose clusters you want to retrieve.

HTTP Response Elements

Name Type Description
autoScaling document Contains auto-scaling information for the cluster. For more information on cluster auto-scaling, see Cluster Auto-Scaling.
autoScaling
.compute
document Specifies whether the cluster automatically scales its cluster tier and whether the cluster can scale down.
autoScaling
.compute
.enabled
boolean Specifies whether cluster tier auto-scaling is enabled.
autoScaling
.compute
.scaleDownEnabled
boolean Specifies whether the cluster tier can scale down.
autoScaling
.diskGBEnabled
boolean Specifies whether disk auto-scaling is enabled. This is the same value as autoScaling.diskGB.enabled.
autoScaling
.diskGB
document Contains the enabled field which specifies whether to enable or disable disk auto-scaling.
autoScaling
.diskGB
.enabled
boolean Specifies whether disk auto-scaling is enabled. This is the same value as autoScaling.diskGBEnabled.
backupEnabled boolean If true, the cluster uses Atlas Continuous Backups for backing up cluster data.
biConnector document

Information on whether BI Connector for Atlas is enabled or disabled for the cluster.

The MongoDB Connector for Business Intelligence for Atlas (BI Connector) is only available for M10 and larger clusters.

The BI Connector is a powerful tool which provides users SQL-based access to their MongoDB databases. As a result, the BI Connector performs operations which may be CPU and memory intensive. Given the limited hardware resources on M10 and M20 cluster tiers, you may experience performance degradation of the cluster when enabling the BI Connector. If this occurs, upgrade to an M30 or larger cluster or disable the BI Connector.

The biConnector document includes the following fields:

Field Description
enabled
true if BI Connector for Atlas is enabled.
false if BI Connector for Atlas is disabled.
readPreference
"primary" if BI Connector for Atlas reads from the primary.
"secondary" if BI Connector for Atlas reads from a secondary.
"analytics" if BI Connector for Atlas reads from an analytics node.
clusterType string

Specifies the type of the cluster:

Value Description
REPLICASET replica set
SHARDED sharded cluster
GEOSHARDED Global Cluster
diskSizeGB double

AWS / GCP Only The size in gigabytes of the server’s root volume. You can add capacity by increasing this number, up to a maximum possible value of 4096 (i.e., 4 TB).

Each cluster tier has its own default value. To view default values:

  1. Open the Atlas web interface.
  2. Click the button to add a new cluster.
  3. View the available default sizes.
  4. Close the window without saving changes.
encryptionAtRestProvider string

Encryption at Rest is enabled or disabled.

For complete documentation on Encryption-at-Rest restrictions, see Prerequisites.

You must configure encryption at rest for the Atlas project before enabling it on any cluster in the project. For complete documentation on configuring Encryption at Rest, see Customer Key Management with AWS KMS.

groupId string Unique identifier of the project the cluster belongs to.
id string Unique identifier of the cluster.
mongoDBVersion string Version of MongoDB the cluster runs, in <major version>.<minor version> format.
mongoDBMajorVersion string

Major version of MongoDB the cluster runs:

  • 3.4
  • 3.6
  • 4.0
  • 4.2
mongoURI string

Base connection string for the cluster.

Atlas only displays this field after the cluster is operational, not while it builds the cluster.

mongoURIUpdated string

Lists when the connection string was last updated. The connection string changes, for example, if you change a replica set to a sharded cluster.

Atlas only displays this field after the cluster is operational, not while it builds the cluster.

mongoURIWithOptions string

connection string for connecting to the Atlas cluster. Includes the replicaSet, ssl, and authSource query parameters in the connection string with values appropriate for the cluster.

To review the connection string format, see the connection string format documentation. To add MongoDB users to a Atlas project, see Configure MongoDB Users.

Atlas only displays this field after the cluster is operational, not while it builds the cluster.

name string Name of the cluster as it appears in Atlas.
numShards integer

Specifies the number of shards for a sharded cluster.

If this is set to 1, the cluster is a replica set.

If this is set to 2 or higher, the cluster is a sharded cluster with the number of shards specified.

For details on how this setting affects costs, see Number of Servers.

The possible values are 1 through 12.

Note

Not present in the response body for Global Clusters.

paused boolean Flag that indicates whether the cluster is paused or not.
pitEnabled boolean Indicates if the cluster uses Point-in-Time backups. If set to true, providerBackupEnabled must also be set to true.
providerBackupEnabled boolean If true, the cluster uses Cloud Provider Snapshots for backups. If providerBackupEnabled and backupEnabled are false, the cluster does not use Atlas backups.
providerSettings document Configuration for the provisioned servers on which MongoDB runs. The available options are specific to the cloud service provider.
providerSettings
.autoScaling
document Contains the compute field which specifies the range of instance sizes to which your cluster can scale.
providerSettings
.autoScaling
.compute
document Contains the minInstanceSize and maxInstanceSize fields which specify the range of instance sizes to which your cluster can scale.
providerSettings
.autoScaling
.compute
.minInstanceSize
string Minimum instance size to which your cluster can automatically scale.
providerSettings
.autoScaling
.compute
.maxInstanceSize
string Maximum instance size to which your cluster can automatically scale.
providerSettings
.providerName
string

Cloud service provider on which the servers are provisioned.

The possible values are:

  • AWS - Amazon AWS
  • GCP - Google Cloud Platform
  • AZURE - Microsoft Azure
  • TENANT - Indicates an M2 or M5 multi-tenant cluster. See providerSettings.backingProviderName for the cloud service provider on which the server hosting the cluster is provisioned.
providerSettings
.backingProviderName
string

Cloud service provider on which the multi-tenant server is provisioned. Only visible if providerSettings.providerName is TENANT.

The possible values are:

  • AWS - Amazon AWS
  • GCP - Google Cloud Platform
  • AZURE - Microsoft Azure
providerSettings
.regionName
string

Physical location of your MongoDB cluster. The region you choose can affect network latency for clients accessing your databases.

For a complete list of region name values, refer to the the cloud provider reference pages:

For multi-region clusters, see replicationSpec.<region>.

providerSettings
.instanceSizeName
string

Name of the cluster tier used for the Atlas cluster.

Atlas supports the following cluster tiers. Atlas supports deploying M2 and M5 tiers into a subset of available regions. The documentation for providersettings.regionName includes a list of these regions.

Cluster Tier Naming Conventions

Cluster tier names that are:

  • Appended with _NVME (M40_NVME for example) use direct attached NVMe storage for exceptional performance with the most I/O-intensive workloads.
  • Prepended with R instead of an M (R40 for example) run a low CPU version of the cluster.

Clusters with _NVME appended (for example: M40_NVME) use locally attached NVMe storage for exceptional performance with the most IO-intensive workloads.

Cluster Tiers Default Storage Default RAM
M2 2GB Shared
M5 5GB Shared
M10 10GB 2GB
M20 20GB 4GB
M30 40GB 8GB
M40 or R40 80GB 16GB
M40_NVME 380GB 15.25GB
M50 or R50 160GB 32GB
M50_NVME 760GB 30.5GB
M60 or R60 320GB 64GB
M60_NVME 1.6TB 61GB
R80 750GB 122GB
M80_NVME 1.6TB 122GB
M140 1 1TB 192GB
M200 or R200 1.5TB 256GB
M200_NVME 3.1TB 244GB
M300 1 2TB 384GB
R400 3TB 488GB
M400_NVME 2 4TB 512GB

1 Only available if providerSettings.regionName is EU-WEST-3 (Paris).

2 Available only in the following regions:

  • US_EAST_1
  • US_EAST_2
  • US_WEST_2
  • EU_WEST_1
  • EU_CENTRAL_1
  • AP_NORTHEAST_1
Cluster Tiers Default Storage Default RAM
M2 2GB Shared
M5 5GB Shared
M10 32GB 2GB
M20 32GB 4GB
M30 32GB 8GB
M40 128GB 16GB
M50 128GB 32GB
M60 128GB 64GB
M80 256GB 128GB
M200 256GB 256GB
Cluster Tiers Default Storage Default RAM
M2 2GB Shared
M5 5GB Shared
M10 10GB 1.70GB
M20 20GB 3.75GB
M30 40GB 7.5GB
M40 80GB 15GB
M50 160GB 30GB
M60 320GB 60GB
M80 750GB 120GB
M200 1 1.5TB 240GB
M300 1 2.2TB 360GB

1 Not available if providerSettings.regionName is SOUTH_AMERICA_EAST_1 , EUROPE_WEST_3, NORTHEASTERN_ASIA_PACIFIC, or AUSTRALIA_SOUTHEAST_1

Important

M2 and M5 clusters are multi-tenant deployments. You must set providerSettings.providerName to TENANT and specify the cloud service provider in providerSettings.backingProviderName.

providerSettings
.diskIOPS
integer Maximum input/output operations per second (IOPS) the system can perform.
providerSettings
.diskTypeName
string

Azure Only The disk type of the server’s root volume.

The following table lists the possible values for this field, and their corresponding storage size.

diskTypeName Storage Size
P4 1 32GB
P6 64GB
P10 2 128GB
P20 512GB
P30 1024GB
P40 2048GB
P50 4095GB

1 Default for M20 and M30 Azure cluster tiers

2 Default for M40+ Azure cluster tiers

providerSettings
.encryptEBSVolume
boolean AWS only. If enabled, the Amazon EBS encryption feature encrypts the server’s root volume for both data at rest within the volume and for data moving between the volume and the cluster.
replicationFactor number

Number of replica set members. Each member keeps a copy of your databases, providing high availability and data redundancy.

For multi-region clusters, add the total number of replicationSpec.<region>.electableNodes to calculate the replication factor of the cluster.

If your cluster is a sharded cluster, each shard is a replica set with the specified replication factor.

For information on how the replication factor affects costs, see Number of Servers. For more information on MongoDB replica sets, see Replication in the MongoDB manual.

The possible values are 3, 5, or 7.

replicationSpec document Configuration of each region in the cluster. Each element in this document represents a region where Atlas deploys your cluster.
replicationSpec
.<region>
document

Physical location of the region. The <region> string corresponds to a region where Atlas deploys your cluster.

Each <region> document describes the region’s priority in elections and the number and type of MongoDB nodes Atlas deploys to the region.

replicationSpec
.<region>
.electableNodes
integer Number of electable nodes in the region. Electable nodes can become the primary and can facilitate local reads.
replicationSpec
.<region>
.priority
integer

Election priority of the region. The highest possible priority is 7, which identifies the Preferred Region of the cluster. Atlas places the primary node in the Preferred Region. The lowest possible priority is 0, which identifies a read only region.

You can have any number of priority 0 read only regions. Priorities 1 through 7 are exclusive - no more than one region per cluster can be assigned a given priority.

replicationSpec
.<region>
.readOnlyNodes
integer Number of read-only nodes in the region. Read-only nodes can never become the primary, but can facilitate local-reads.
replicationSpec.<region>.analyticsNodes integer The number of analytics nodes in the region. Analytics nodes are useful for handling analytic data such as reporting queries from BI Connector for Atlas. Analytics nodes are read-only, and can never become the primary.
replicationSpecs array of documents Configuration for each zone in a Global Cluster. Each document in this array represents a zone where Atlas deploys nodes for your Global Cluster.
replicationSpecs[n]
.id
string Unique identifier of the replication document.
replicationSpecs[n]
.zoneName
string Name for the zone.
replicationSpecs[n]
.numShards
integer Number of shards to deploy in the specified zone.
replicationSpecs[n]
.regionsConfig
document Physical location of the region. Each regionsConfig document describes the region’s priority in elections and the number and type of MongoDB nodes Atlas deploys to the region.
srvAddress string Connection string for connecting to the Atlas cluster. The +srv modifier forces the connection to use TLS/SSL. See the mongoURI for additional options.
stateName string

Current state of the cluster. The possible states are:

  • IDLE
  • CREATING
  • UPDATING
  • DELETING
  • DELETED
  • REPAIRING

Example

Request

curl -i -u "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest "https://cloud.mongodb.com/api/atlas/v1.0/groups/5356823b3794de37132bb7b/clusters"

Response

HTTP/1.1 200 OK

{
  "results" : [ {
    "autoScaling":{"diskGBEnabled":true},
    "backupEnabled" : true,
    "biConnector": {
      "enabled": false,
      "readPreference": "secondary"
    },
    "clusterType": "REPLICASET",
    "diskSizeGB" : 160,
    "encryptionAtRestProvider" : "AWS",
    "groupId" : "5356823b3794de37132bb7b",
    "mongoDBVersion" : "3.4.9",
    "mongoURI" : "mongodb://mongo-shard-00-00.mongodb.net:27017,mongo-shard-00-01.mongodb.net:27017,mongo-shard-00-02.mongodb.net:27017",
    "mongoURIUpdated" : "2017-10-23T21:26:17Z",
    "mongoURIWithOptions" : "mongodb://mongo-shard-00-00.mongodb.net:27017,mongo-shard-00-01.mongodb.net:27017,mongo-shard-00-02.mongodb.net:27017/?ssl=true&authSource=admin&replicaSet=mongo-shard-0",
    "name" : "AppData",
    "numShards" : 1,
    "paused" : false,
    "providerSettings" : {
      "providerName" : "AWS",
      "diskIOPS" : 1320,
      "encryptEBSVolume" : false,
      "instanceSizeName" : "M40",
      "regionName" : "US_WEST_2"
    },
    "replicationFactor" : 3,
    "replicationSpec": {
        "US_EAST_1": {
            "electableNodes": 3,
            "priority": 7,
            "readOnlyNodes": 0
        }
    },
    "srvAddress" : "mongodb+srv://mongo.mongodb.net",
    "stateName" : "IDLE"
  },
  ...
  ],
  "links" : [ ... ],
  "totalCount" : 4
}