Navigation

Get a Single Cluster

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/{CLUSTER-NAME}

Request Path Parameters

Path Element Required/Optional Description
GROUP-ID Required. The unique identifier for the project containing the cluster you want to retrieve.
CLUSTER-NAME Required The name of the cluster 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.
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.
labels array of documents Array containing key-value pairs that tag and categorize 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.

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

1 Unavailable if providerSettings.regionName equals AP_SOUTHEAST_2.

2 Availability limited to 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 2 GB Shared
M5 5 GB Shared
M10 32 GB 2 GB
M20 32 GB 4 GB
M30 32 GB 8 GB
M40 128 GB 16 GB
M50 128 GB 32 GB
M60 128 GB 64 GB
M80 256 GB 128 GB
M200 256 GB 256 GB
Cluster Tiers Default Storage Default RAM
M2 2 GB Shared
M5 5 GB Shared
M10 10 GB 1.70 GB
M20 20 GB 3.75 GB
M30 40 GB 7.5 GB
M40 80 GB 15 GB
M50 160 GB 30 GB
M60 320 GB 60 GB
M80 750 GB 120 GB
M200 1.5 TB 240 GB
M300 1 2.2 TB 360 GB

1 Unavailable if providerSettings.regionName equals:

  • SOUTH_AMERICA_EAST_1
  • EUROPE_WEST_3
  • NORTHEASTERN_ASIA_PACIFIC
  • 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/LogData"

Response

HTTP/1.1 200 OK

{
  "autoScaling": {
    "compute": {
      "enabled": false,
      "scaleDownEnabled": false
    },
    "diskGBEnabled": true
  },
  "backupEnabled" : true,
  "biConnector": {
    "enabled": true,
    "readPreference": "secondary"
  },
  "clusterType": "SHARDED",
  "diskSizeGB" : 80,
  "encryptionAtRestProvider" : "NONE"
  "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",
  "labels": [],
  "name" : "LogData",
  "numShards" : 2,
  "paused" : false,
  "providerSettings" : {
    "providerName" : "AWS",
    "diskIOPS" : 240,
    "encryptEBSVolume" : false,
    "instanceSizeName" : "M40",
    "regionName" : "US_EAST_1"
  },
  "replicationFactor" : 3,
  "replicationSpec": {
      "US_EAST_1": {
          "electableNodes": 3,
          "priority": 7,
          "readOnlyNodes": 0
      }
  },
  "srvAddress" : "mongodb+srv://mongo.mongodb.net",
  "stateName" : "IDLE"
}