Navigation

Get One Cluster

Important With Circle IconCreated with Sketch.Important
Multi-Cloud Clusters Unsupported

This endpoint returns the MULTI_CLOUD_CLUSTER_INVALID error if you specify a multi-cloud cluster.

Info With Circle IconCreated with Sketch.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 authenticates using HTTP Digest Authentication. Provide a programmatic API public key and corresponding private key as the username and password when constructing the HTTP request.

To learn how to configure API access for an Atlas project, see Configure Atlas API Access.

To use this resource, your API Key must have the Project Read Only role.

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

GET /groups/{PROJECT-ID}/clusters/{CLUSTER-NAME}
Path ParameterTypeNecessityDescription
PROJECT-IDRequiredstringUnique identifier for the project containing the cluster you want to retrieve.
CLUSTER-NAMERequiredstringName of the cluster to retrieve.

This endpoint might use any of the HTTP request query parameters available to all Atlas API resources. All of these are optional.

NameTypeNecessityDescriptionDefault
prettybooleanOptionalFlag indicating whether the response body should be in a prettyprint format.false
envelopebooleanOptional

Flag indicating if Atlas should wrap the response in a JSON envelope.

This option may be needed for some API clients. These clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query.

For endpoints that return one result, the response body includes:

statusHTTP response code
envelopeExpected response body
false

This endpoint doesn't use HTTP request body parameters.

NameTypeDescription
autoScalingobject

Collection of settings that configures auto-scaling information for the cluster.

Bulb IconTip
autoScaling.autoIndexingEnabledboolean

Flag that indicates whether autopilot mode for Performance Advisor is enabled. The default is false.

Important With Circle IconCreated with Sketch.Important

Autopilot mode is only available if you are enrolled in the Auto Pilot Early Access program.

autoScaling.computeobjectCollection of settings that configure how a cluster might scale its cluster tier and whether the cluster can scale down.
autoScaling.compute.enabledbooleanFlag that indicates whether cluster tier auto-scaling is enabled.
autoScaling.compute.scaleDownEnabledbooleanFlag that indicates whether the cluster tier can scale down.
autoScaling.diskGBEnabledbooleanFlag that indicates whether disk auto-scaling is enabled.
backupEnabledboolean

Flag that indicates whether legacy backup has been enabled.

Important With Circle IconCreated with Sketch.Important

Clusters running MongoDB FCV 4.2 or later and any newnew Atlas clusters of any type do not support this parameter. These clusters must use Cloud Backups: providerBackupEnabled

This change doesn't affect existing Atlas clusters that use legacy backups.

biConnectorobject

Collection of settings that configure a BI Connector for Atlas 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.

biConnector.enabledbooleanFlag that indicates whether Atlas enabled the BI Connector for Atlas for this cluster.
biConnector.readPreferencestring

Source from which the BI Connector for Atlas reads data.

ValueDescription
primaryBI Connector for Atlas reads data from the primary.
secondaryBI Connector for Atlas reads data from a secondary.
analytics
BI Connector for Atlas reads data from an
analytics node.
clusterTypestring

Type of the cluster:

ValueDescription
REPLICASETreplica set
SHARDEDsharded cluster
GEOSHARDEDglobal cluster
connectionStringsobject

Set of connection strings that your applications use to connect to this cluster.

Use the parameters in this object to connect your applications to this cluster.

Bulb IconTip

Atlas returns the contents of this object after the cluster is operational, not while it builds the cluster.

connectionStrings.privateEndpointarray of objectsPrivate endpoint connection strings. Each object describes the connection strings you can use to connect to this cluster through a private endpoint. Atlas returns this parameter only if you deployed a private endpoint to all regions to which you deployed this cluster's nodes.
connectionStrings.privateEndpoint[n].connectionStringstringPrivate-endpoint-aware mongodb://connection string for this private endpoint.
connectionStrings.privateEndpoint[n].endpointsarray of objectsPrivate endpoint through which you connect to Atlas when you use connectionStrings.privateEndpoint[n].connectionString or connectionStrings.privateEndpoint[n].srvConnectionString.
connectionStrings.privateEndpoint[n].endpoints[n].endpointIdstringUnique identifier of the private endpoint.
connectionStrings.privateEndpoint[n].endpoints[n].providerNamestringCloud provider to which you deployed the private endpoint. Atlas returns AWS or AZURE.
connectionStrings.privateEndpoint[n].endpoints[n].regionstringRegion to which you deployed the private endpoint.
connectionStrings.privateEndpoint[n].srvConnectionStringstring

Private-endpoint-aware mongodb+srv:// connection string for this private endpoint.

The mongodb+srv protocol tells the driver to look up the seed list of hosts in DNS . Atlas synchronizes this list with the nodes in a cluster. If the connection string uses this URI format, you don't need to:

  • Append the seed list or
  • Change the URI if the nodes change.

Use this URI format if your driver supports it. If it doesn't, use connectionStrings.privateEndpoint[n].connectionString.

Bulb IconTip
See Also:
connectionStrings.privateEndpoint[n].typestring

Type of MongoDB process that you connect to with the connection strings. Atlas returns:

  • MONGOD for replica sets, or
  • MONGOS for sharded clusters.
connectionStrings.standardstringPublic mongodb:// connection string for this cluster.
connectionStrings.standardSrvstring

Public mongodb+srv:// connection string for this cluster.

Bulb IconTip
See Also:
connectionStrings.privatestring

Network-peering-endpoint-aware mongodb://connection strings for each interface VPC endpoint you configured to connect to this cluster. Atlas returns this parameter only if you created a network peering connection to this cluster.

Info With Circle IconCreated with Sketch.Note

For AWS clusters, Atlas doesn't return this parameter unless you enable custom DNS.

connectionStrings.privateSrvstring

Network-peering-endpoint-aware mongodb+srv:// connection strings for each interface VPC endpoint you configured to connect to this cluster. Atlas returns this parameter only if you created a network peering connection to this cluster.

The mongodb+srv protocol tells the driver to look up the seed list of hosts in DNS . Atlas synchronizes this list with the nodes in a cluster. If the connection string uses this URI format, you don't need to:

  • Append the seed list or
  • Change the URI if the nodes change.

Use this URI format if your driver supports it. If it doesn't, use connectionStrings.private.

Bulb IconTip
See Also:
Info With Circle IconCreated with Sketch.Note

For AWS clusters, Atlas doesn't return this parameter unless you enable custom DNS.

connectionStrings.awsPrivateLinkobject
Important With Circle IconCreated with Sketch.Important

This field is deprecated. Use connectionStrings.privateEndpoint[n].connectionString instead.

Info With Circle IconCreated with Sketch.Note

Atlas returns this parameter only if:

  • the cluster is deployed to AWS , and
  • you deployed a AWS PrivateLink private endpoint to the same regions as all of this cluster's nodes.

Private-endpoint-aware mongodb://connection strings for each AWS PrivateLink private endpoint. Atlas returns this parameter only if you deployed a AWS PrivateLink private endpoint to the same regions as all of this cluster's nodes.

In this object:

  • Each key is the unique identifier of an interface endpoint.
  • Each value is the mongodb:// connection string you use to connect to Atlas through the interface endpoint the key names.
connectionStrings.awsPrivateLinkSrvobject
Important With Circle IconCreated with Sketch.Important

This field is deprecated. Use connectionStrings.privateEndpoint[n].srvConnectionString instead.

Info With Circle IconCreated with Sketch.Note

Atlas returns this parameter only if:

  • the cluster is deployed to AWS , and
  • you deployed a AWS PrivateLink private endpoint to the same regions as all of this cluster's nodes.

Private-endpoint-aware mongodb+srv:// connection strings for each AWS PrivateLink private endpoint.

In this object:

  • Each key is the unique identifier of an interface endpoint.
  • Each value is the mongodb+srv:// connection string you use to connect to Atlas through the interface endpoint the key names.

The mongodb+srv protocol tells the driver to look up the seed list of hosts in DNS . Atlas synchronizes this list with the nodes in a cluster. If the connection string uses this URI format, you don't need to:

  • Append the seed list or
  • Change the URI if the nodes change.

Use this URI format if your driver supports it. If it doesn't, use connectionStrings.awsPrivateLink.

Bulb IconTip
See Also:
createDatestringTimestamp in ISO 8601 date and time format in UTC when Atlas created the cluster.
diskSizeGBnumber

Capacity, in gigabytes, of the host's root volume. Increase this number to add capacity, up to a maximum possible value of 4096 (4 TB). This value must be a positive integer.

Info With Circle IconCreated with Sketch.Note
When should you use diskSizeGB?

This setting:

The minimum disk size for dedicated clusters is 10 GB for AWS and GCP , and 32 GB for Azure . If you specify diskSizeGB with a lower disk size, Atlas defaults to the minimum disk size value.

Important With Circle IconCreated with Sketch.Important

Atlas calculates storage charges differently depending on whether you choose the default value or a custom value.

Bulb IconTip
See Also:
Info With Circle IconCreated with Sketch.Note

The maximum value for disk storage cannot exceed 50 times the maximum RAM for the selected cluster. If you require additional storage space beyond this limitation, consider upgrading your cluster to a higher tier.

encryptionAtRestProviderstring

Cloud service provider that offers Encryption at Rest.

groupIdstringUnique identifier of the project to which the cluster belongs.
idstringUnique identifier of the cluster.
labelsarray of documentsCollection of key-value pairs that tag and categorize the cluster.
mongoDBVersionstringVersion of MongoDB the cluster runs, in <major version>.<minor version> format.
mongoDBMajorVersionstring

Major version of MongoDB the cluster runs:

  • 3.6
  • 4.0
  • 4.2
  • 4.4
mongoURIstring

Base connection string for the cluster.

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

mongoURIUpdatedstringTimestamp in ISO 8601 date and time format in UTC when the connection string was last updated. The connection string changes if you update any of the other values.
mongoURIWithOptionsstring

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 database users to a Atlas project, see Configure Database Users.

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

namestringName of the cluster as it appears in Atlas.
numShardsnumber

Positive integer that 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.

Bulb IconTip
See Also:

Atlas might return values between 1 and 50.

Info With Circle IconCreated with Sketch.Note

Atlas doesn't return this value in the response body for Global Clusters.

pausedbooleanFlag that indicates whether the cluster is paused.
pitEnabledbooleanFlag that indicates if the cluster uses Continuous Cloud Backup backups.
providerBackupEnabledboolean

Applicable only for M10+ clusters.

Flag that indicates if the cluster uses Cloud Backups for backups.

If true, the cluster uses Cloud Backups for backups. If providerBackupEnabled and backupEnabled are false, the cluster does not use Atlas backups.

providerSettingsobjectConfiguration for the provisioned hosts on which MongoDB runs. The available options are specific to the cloud service provider.
providerSettings.autoScalingobject

Range of instance sizes to which your cluster can scale.

Important With Circle IconCreated with Sketch.Important

You can't specify the providerSettings.autoScaling object if "autoScaling.compute.enabled" : false.

providerSettings.autoScaling.computeobjectRange of instance sizes to which your cluster can scale. Atlas requires this parameter if "autoScaling.compute.enabled" : true.
providerSettings.autoScaling.compute.minInstanceSizestringMinimum instance size to which your cluster can automatically scale.
providerSettings.autoScaling.compute.maxInstanceSizestringMaximum instance size to which your cluster can automatically scale.
providerSettings.backingProviderNamestring

Cloud service provider on which the multi-tenant host is provisioned. Atlas returns this parameter only if "providerSettings.providerName" : "TENANT".

Atlas can return:

AWSAmazon AWS
GCPGoogle Cloud Platform
AZUREMicrosoft Azure
providerSettings.providerNamestring

Cloud service provider on which Atlas provisioned the hosts.

Atlas can return:

AWSAmazon AWS
GCPGoogle Cloud Platform
AZUREMicrosoft Azure
TENANT

M2 or M5 multi-tenant cluster.

See providerSettings.backingProviderName for the cloud service provider where Atlas provisioned the host serving the cluster.

providerSettings.regionNamestring

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.diskIOPSnumberMaximum IOPS the system can perform.
providerSettings.diskTypeNamestring

Disk type of the host's root volume for Azure instances.

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

diskTypeNameStorage Size
P4 [1]32GB
P664GB
P10 [2]128GB
P15256GB
P20512GB
P301024GB
P402048GB
P504095GB
[1] Default for M20 and M30 Azure cluster tiers
[2] Default for M40+ Azure cluster tiers
providerSettings.encryptEBSVolumebooleanFlag that indicates whether the Amazon EBS encryption feature encrypts the host's root volume for both data at rest within the volume and for data moving between the volume and the cluster.
providerSettings.instanceSizeNamestring

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.

Info With Circle IconCreated with Sketch.Note
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.
Instance SizeDefault StorageDefault RAM
M22 GBShared
M55 GBShared
M1010 GB2 GB
M2020 GB4 GB
M3040 GB8 GB
M4080 GB16 GB
M40 Low-CPU (R40)80 GB16 GB
M40_NVME380 GB15.25 GB
M50160 GB32 GB
M50 Low-CPU (R50)160 GB32 GB
M50_NVME760 GB30.5 GB
M60320 GB64 GB
M60 Low-CPU (R60)320 GB64 GB
M60_NVME1.6 TB61 GB
M80760 GB131 GB
M80 Low-CPU (R80)750 GB122 GB
M80_NVME1.6 TB122 GB
M1001 TB160 GB
M140 11 TB192 GB
M2001.5 TB256 GB
M200 Low-CPU (R200)1.5 TB256 GB
M200_NVME3.1 TB244 GB
M300 12 TB384 GB
M300 Low-CPU (R300)2 TB384 GB
M400 Low-CPU (R400)3 TB488 GB
M400_NVME 24 TB512 GB
M700 Low-CPU (R700)4 TB768 GB

1 Unavailable in the AP_SOUTHEAST_2 region.

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
Important With Circle IconCreated with Sketch.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.

replicationFactornumber

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.

Atlas may return 3, 5, or 7.

Bulb IconTip
replicationSpecobjectConfiguration of each region in the cluster. Each element in this object represents a region where Atlas deploys your cluster.
replicationSpec.<region>object

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

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

replicationSpec.<region>.analyticsNodesnumberNumber 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.
replicationSpec.<region>.electableNodesnumberNumber of electable nodes in the region. Electable nodes can become the primary and can facilitate local reads.
replicationSpec.<region>.prioritynumber

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: only one region per cluster can be assigned a given priority.

replicationSpec.<region>.readOnlyNodesnumberNumber of read-only nodes in the region. Read-only nodes can never become the primary member, but can facilitate local reads.
replicationSpecsarrayConfiguration for each zone in a Global Cluster. Each object in this array represents a zone where Atlas deploys nodes for your Global Cluster.
replicationSpecs[n].idstringUnique identifier of the replication object.
replicationSpecs[n].zoneNamestringName for the zone.
replicationSpecs[n].numShardsnumberNumber of shards to deploy in the specified zone.
replicationSpecs[n].regionsConfigobjectPhysical location of the region. Each regionsConfig object describes the region's priority in elections and the number and type of MongoDB nodes that Atlas deploys to the region.
replicationSpecs[n].regionsConfig.<region>.analyticsNodesnumberThe number of analytics nodes for Atlas to deploy to 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.If you do not specify this option, no analytics nodes are deployed to the region.
replicationSpecs[n].regionsConfig.<region>.electableNodesnumberNumber of electable nodes for Atlas to deploy to the region. Electable nodes can become the primary and can facilitate local reads.
replicationSpecs[n].regionsConfig.<region>.readOnlyNodesnumber

Number of read-only nodes for Atlas to deploy to the region. Read-only nodes can never become the primary, but can facilitate local-reads.

Specify 0 if you do not want any read-only nodes in the region.

replicationSpecs[n].regionsConfig.<region>.prioritynumberElection priority of the region. If you have regions with only read-only nodes, set this value to 0.
replicationSpecs[n].zoneNamestringName for the zone in a Global Cluster. Do not provide this value if clusterType is not GEOSHARDED.
srvAddressstringConnection string for connecting to the Atlas cluster. The +srv modifier forces the connection to use TLS . The mongoURI parameter lists additional options.
stateNamestring

Current state of the cluster. The possible states are:

  • IDLE
  • CREATING
  • UPDATING
  • DELETING
  • DELETED
  • REPAIRING
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
--header "Content-Type: application/json" \
--include \
--request GET "https://cloud.mongodb.com/api/atlas/v1.0/groups/{PROJECT-ID}/clusters/{CLUSTER-NAME}?pretty=true"
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=ISO-8859-1
Date: {dateInUnixFormat}
WWW-Authenticate: Digest realm="MMS Public API", domain="", nonce="{nonce}", algorithm=MD5, op="auth", stale=false
Content-Length: {requestLengthInBytes}
Connection: keep-alive
HTTP/1.1 200 OK
Vary: Accept-Encoding
Content-Type: application/json
Strict-Transport-Security: max-age=300
Date: {dateInUnixFormat}
Connection: keep-alive
Content-Length: {requestLengthInBytes}
1{
2 "autoScaling":{
3 "compute":{
4 "enabled":false,
5 "scaleDownEnabled":false
6 },
7 "diskGBEnabled":true
8 },
9 "backupEnabled":false,
10 "biConnector":{
11 "enabled":false,
12 "readPreference":"secondary"
13 },
14 "clusterType":"REPLICASET",
15 "connectionStrings":{
16 "privateEndpoint":[
17 {
18 "connectionString":"mongodb://pl-0-us-east-1.uzgh6.mongodb.net:1024,pl-0-us-east-1.uzgh6.mongodb.net:1025,pl-0-us-east-1.uzgh6.mongodb.net:1026/?ssl=true&authSource=admin&replicaSet=atlas-8dhkjj-shard-0",
19 "endpoints":[
20 {
21 "endpointId":"vpce-0c86b555d9a233152",
22 "providerName":"AWS",
23 "region":"US_EAST_1"
24 }
25 ],
26 "srvConnectionString":"mongodb+srv://cluster1-pl-0.uzgh6.mongodb.net",
27 "type":"MONGOD"
28 }
29 ],
30 "standardSrv":"mongodb+srv://cluster1.uzgh6.mongodb.net",
31 "awsPrivateLink":{
32 "vpce-0c86b555d9a233152":"mongodb://pl-0-us-east-1.uzgh6.mongodb.net:1024,pl-0-us-east-1.uzgh6.mongodb.net:1025,pl-0-us-east-1.uzgh6.mongodb.net:1026/?ssl=true&authSource=admin&replicaSet=atlas-8dhkjj-shard-0"
33 },
34 "awsPrivateLinkSrv":{
35 "vpce-0c86b555d9a233152":"mongodb+srv://cluster1-pl-0.uzgh6.mongodb.net"
36 },
37 "standard":"mongodb://cluster1-shard-00-00.uzgh6.mongodb.net:27017,cluster1-shard-00-01.uzgh6.mongodb.net:27017,cluster1-shard-00-02.uzgh6.mongodb.net:27017/?ssl=true&authSource=admin&replicaSet=atlas-8dhkjj-shard-0"
38 },
39 "createDate":"2020-10-03T17:34:08Z",
40 "diskSizeGB":100.0,
41 "encryptionAtRestProvider":"NONE",
42 "groupId":"{GROUP-ID}",
43 "id":"{CLUSTER-ID}",
44 "labels":[
45
46 ],
47 "mongoDBMajorVersion":"4.0",
48 "mongoDBVersion":"4.0.13",
49 "mongoURIUpdated":"2020-10-04T17:34:08Z",
50 "name":"SingleRegionCluster",
51 "numShards":1,
52 "paused":false,
53 "pitEnabled":false,
54 "providerBackupEnabled":true,
55 "providerSettings":{
56 "providerName":"AWS",
57 "autoScaling":{
58 "compute":{
59 "maxInstanceSize":null,
60 "minInstanceSize":null
61 }
62 },
63 "diskIOPS":300,
64 "encryptEBSVolume":true,
65 "instanceSizeName":"M40",
66 "regionName":"US_EAST_1",
67 "volumeType":"STANDARD"
68 },
69 "replicationFactor":3,
70 "replicationSpec":{
71 "US_EAST_1":{
72 "analyticsNodes":0,
73 "electableNodes":3,
74 "priority":7,
75 "readOnlyNodes":0
76 }
77 },
78 "replicationSpecs":[
79 {
80 "id":"{REPLICA-ID}",
81 "numShards":1,
82 "regionsConfig":{
83 "US_EAST_1":{
84 "analyticsNodes":0,
85 "electableNodes":3,
86 "priority":7,
87 "readOnlyNodes":0
88 }
89 },
90 "zoneName":"Zone 1"
91 }
92 ],
93 "stateName":"IDLE",
94 "links":[
95 {
96 "href":"https://cloud.mongodb.com/api/atlas/v1.0/groups/{GROUP-ID}/clusters/SingleRegionCluster",
97 "rel":"self"
98 },
99 {
100 "href":"https://cloud.mongodb.com/api/atlas/v1.0/groups/{GROUP-ID}/clusters/SingleRegionCluster/restoreJobs",
101 "rel":"http://mms.mongodb.com/restoreJobs"
102 },
103 {
104 "href":"https://cloud.mongodb.com/api/atlas/v1.0/groups/{GROUP-ID}/clusters/SingleRegionCluster/snapshots",
105 "rel":"http://mms.mongodb.com/snapshots"
106 }
107 ]
108}
Give Feedback