Get One Cluster¶
On this page
This endpoint returns the MULTI_CLOUD_CLUSTER_INVALID
error if you specify a multi-cloud cluster.
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 Administration 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 Get Started with the Atlas Administration API.
Required Roles¶
To use this resource, your API Key must have the
Project Read Only
role.
Request¶
Base URL: https://cloud.mongodb.com/api/atlas/v1.0
GET /groups/{GROUP-ID}/clusters/{CLUSTER-NAME}
Request Path Parameters¶
Path Parameter | Type | Necessity | Description |
---|---|---|---|
GROUP-ID | Required | string | Unique identifier for the project containing
the cluster you want to retrieve. |
CLUSTER-NAME | Required | string | Name of the cluster to retrieve. |
Request Query Parameters¶
This endpoint might use any of the HTTP request query parameters available to all Atlas Administration API resources. All of these are optional.
Name | Type | Necessity | Description | Default | ||||||
---|---|---|---|---|---|---|---|---|---|---|
pretty | boolean | Optional | Flag indicating whether the response body should be in a
prettyprint format. | false | ||||||
envelope | boolean | Optional | 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:
| false |
Request Body Parameters¶
This endpoint doesn't use HTTP request body parameters.
Response¶
Name | Type | Description | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
autoScaling | object | Collection of settings that configures auto-scaling information for the cluster. Tip See also: | ||||||||||||||
autoScaling.compute | object | Collection of settings that configure how a cluster might scale
its cluster tier and whether the cluster can scale down. | ||||||||||||||
autoScaling.compute.enabled | boolean | Flag that indicates whether cluster tier auto-scaling is
enabled. | ||||||||||||||
autoScaling.compute.scaleDownEnabled | boolean | Flag that indicates whether the cluster tier can scale down. | ||||||||||||||
autoScaling.diskGBEnabled | boolean | Flag that indicates whether disk auto-scaling is enabled. | ||||||||||||||
backupEnabled | boolean | Flag that indicates whether legacy backup has been enabled. Important Clusters running MongoDB This change doesn't affect existing Atlas clusters that use legacy backups. | ||||||||||||||
biConnector | object | 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 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 | ||||||||||||||
biConnector.enabled | boolean | Flag that indicates whether Atlas enabled the BI Connector for Atlas for this
cluster. | ||||||||||||||
biConnector.readPreference | string | Source from which the BI Connector for Atlas reads data.
| ||||||||||||||
clusterType | string | Type of the cluster:
| ||||||||||||||
connectionStrings | object | 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. Tip See also: Atlas returns the contents of this object after the cluster is operational, not while it builds the cluster. | ||||||||||||||
connectionStrings.privateEndpoint | array of objects | Private 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].connectionString | string | Private-endpoint-aware
mongodb://connection string
for this private endpoint. | ||||||||||||||
connectionStrings.privateEndpoint[n].endpoints | array of objects | Private endpoint through which you connect to Atlas
when you use
connectionStrings.privateEndpoint[n].connectionString or
connectionStrings.privateEndpoint[n].srvConnectionString. | ||||||||||||||
connectionStrings.privateEndpoint[n].endpoints[n].endpointId | string | Unique identifier of the private endpoint. | ||||||||||||||
connectionStrings.privateEndpoint[n].endpoints[n].providerName | string | Cloud provider to which you deployed the private endpoint.
Atlas returns AWS, AZURE, or GCP. | ||||||||||||||
connectionStrings.privateEndpoint[n].endpoints[n].region | string | Region to which you deployed the private endpoint. | ||||||||||||||
connectionStrings.privateEndpoint[n].srvConnectionString | string | 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:
Use this URI format if your driver supports it. If it doesn't, use connectionStrings.privateEndpoint[n].connectionString. Tip See also: | ||||||||||||||
connectionStrings.privateEndpoint[n].type | string | Type of MongoDB process that you connect to with the connection strings. Atlas returns:
| ||||||||||||||
connectionStrings.standard | string | Public
mongodb:// connection string
for this cluster. | ||||||||||||||
connectionStrings.standardSrv | string | Public mongodb+srv:// connection string for this cluster. Tip See also: | ||||||||||||||
connectionStrings.private | string | 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. Note For AWS clusters, Atlas doesn't return this parameter unless you enable custom DNS. | ||||||||||||||
connectionStrings.privateSrv | string | 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:
Use this URI format if your driver supports it. If it doesn't, use connectionStrings.private. Tip See also: Note For AWS clusters, Atlas doesn't return this parameter unless you enable custom DNS. | ||||||||||||||
connectionStrings.awsPrivateLink | object | Important This field is deprecated. Use connectionStrings.privateEndpoint[n].connectionString instead. Note Atlas returns this parameter only if:
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:
| ||||||||||||||
connectionStrings.awsPrivateLinkSrv | object | Important This field is deprecated. Use connectionStrings.privateEndpoint[n].srvConnectionString instead. Note Atlas returns this parameter only if:
Private-endpoint-aware mongodb+srv:// connection strings for each AWS PrivateLink private endpoint. In this object:
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:
Use this URI format if your driver supports it. If it doesn't, use connectionStrings.awsPrivateLink. Tip See also: | ||||||||||||||
createDate | string | Timestamp in ISO 8601 date and time format in UTC when Atlas created the cluster. | ||||||||||||||
diskSizeGB | number | 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 number. Note When should you use diskSizeGB? This setting:
The minimum disk size for dedicated clusters is 10 GB for AWS and Google Cloud, and 32 GB for Azure. If you specify diskSizeGB with a lower disk size, Atlas defaults to the minimum disk size value. Important Atlas calculates storage charges differently depending on whether you choose the default value or a custom value. Tip See also: 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. | ||||||||||||||
encryptionAtRestProvider | string | Cloud service provider that offers Encryption at Rest. Tip | ||||||||||||||
groupId | string | Unique identifier of the project to which the cluster belongs. | ||||||||||||||
id | string | Unique identifier of the cluster. | ||||||||||||||
labels | array of documents | Collection of key-value pairs that tag and categorize the
cluster. | ||||||||||||||
mongoDBVersion | string | Version of MongoDB the cluster runs, in
<major version>.<minor version>.<patch version> format. | ||||||||||||||
mongoDBMajorVersion | string | Major version of MongoDB the cluster runs:
| ||||||||||||||
mongoURI | string | Base connection string for the cluster. Atlas only displays this parameter after the cluster is operational, not while it builds the cluster. | ||||||||||||||
mongoURIUpdated | string | Timestamp 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. | ||||||||||||||
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 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. | ||||||||||||||
name | string | Name of the cluster as it appears in Atlas. | ||||||||||||||
numShards | number | 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. Tip See also: Atlas might return values between 1 and 50. Note Atlas doesn't return this value in the response body for Global Clusters. | ||||||||||||||
paused | boolean | Flag that indicates whether the cluster is paused. | ||||||||||||||
pitEnabled | boolean | Flag that indicates if the cluster uses Continuous Cloud Backup
backups. | ||||||||||||||
providerBackupEnabled | boolean | This applies to dedicated clusters, M10 or greater, only. 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. | ||||||||||||||
providerSettings | object | Configuration for the provisioned hosts on which MongoDB
runs. The available options are specific to the cloud service
provider. | ||||||||||||||
providerSettings.autoScaling | object | Range of instance sizes to which your cluster can scale. Important You can't specify the providerSettings.autoScaling object if "autoScaling.compute.enabled" : false. | ||||||||||||||
providerSettings.autoScaling.compute | object | Range of instance sizes to which your cluster can scale.
Atlas requires this parameter if
"autoScaling.compute.enabled" : true. | ||||||||||||||
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.backingProviderName | string | Cloud service provider on which the multi-tenant host is provisioned. Atlas returns this parameter only if "providerSettings.providerName" : "TENANT". Atlas can return:
| ||||||||||||||
providerSettings.providerName | string | Cloud service provider on which Atlas provisioned the hosts. Atlas can return:
| ||||||||||||||
providerSettings.regionName | string | |||||||||||||||
providerSettings.diskIOPS | number | Maximum IOPS the system can perform. | ||||||||||||||
providerSettings.diskTypeName | string | |||||||||||||||
providerSettings.encryptEBSVolume | boolean | Flag 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.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. Note Cluster Tier Naming Conventions Cluster tier names that are:
M2 and M5 clusters are multi-tenant deployments. You must set providerSettings.providerName to TENANT and specify the cloud service provider in providerSettings.backingProviderName. | ||||||||||||||
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. Atlas may return 3, 5, or 7. Tip See also: | ||||||||||||||
replicationSpec | object | Configuration 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>.analyticsNodes | number | 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. | ||||||||||||||
replicationSpec.<region>.electableNodes | number | Number of electable nodes in the region. Electable nodes
can become the primary and can facilitate local reads. | ||||||||||||||
replicationSpec.<region>.priority | number | 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>.readOnlyNodes | number | Number of read-only nodes in the region. Read-only nodes can
never become the primary member, but can facilitate
local reads. | ||||||||||||||
replicationSpecs | array | Configuration 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].id | string | Unique identifier of the replication object. | ||||||||||||||
replicationSpecs[n].zoneName | string | Name for the zone. | ||||||||||||||
replicationSpecs[n].numShards | number | Number of shards to deploy in the specified zone. | ||||||||||||||
replicationSpecs[n].regionsConfig | object | Physical 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>.analyticsNodes | number | 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. | ||||||||||||||
replicationSpecs[n].regionsConfig.<region>.electableNodes | number | Number 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>.readOnlyNodes | number | 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>.priority | number | Election priority of the region. If you have regions with only
read-only nodes, set this value to 0. | ||||||||||||||
replicationSpecs[n].zoneName | string | Name for the zone in a Global Cluster. Do not provide
this value if clusterType is not GEOSHARDED. | ||||||||||||||
rootCertType | string | Certificate Authority that MongoDB Atlas clusters use. Value can be
Note Beginning on 1 May 2021, new TLS certificates that MongoDB Atlas creates use ISRG instead of IdenTrust for their root Certificate Authority in line with Let's Encrypt's announcement of this transition. | ||||||||||||||
srvAddress | string | Connection string for
connecting to the Atlas cluster. The +srv modifier
forces the connection to use TLS. The mongoURI parameter
lists additional options. | ||||||||||||||
stateName | string | Current state of the cluster. The possible states are:
| ||||||||||||||
versionReleaseSystem | string | Release cadence that Atlas uses for this cluster. Atlas supports:
|
Example Request¶
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --include \ --request GET "https://cloud.mongodb.com/api/atlas/v1.0/groups/{GROUP-ID}/clusters/{CLUSTER-NAME}?pretty=true"
Example Response¶
Response Header¶
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
200 OK Vary: Accept-Encoding Content-Type: application/json Strict-Transport-Security: max-age=300 Date: {dateInUnixFormat} Connection: keep-alive Content-Length: {requestLengthInBytes}
Response Body¶
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 "rootCertType": "ISRGROOTX1", 95 "srvAddress":"mongodb+srv://cluster0-uzgh6.mongodb.net", 96 "links":[ 97 { 98 "href":"https://cloud.mongodb.com/api/atlas/v1.0/groups/{GROUP-ID}/clusters/SingleRegionCluster", 99 "rel":"self" 100 }, 101 { 102 "href":"https://cloud.mongodb.com/api/atlas/v1.0/groups/{GROUP-ID}/clusters/SingleRegionCluster/restoreJobs", 103 "rel":"http://mms.mongodb.com/restoreJobs" 104 }, 105 { 106 "href":"https://cloud.mongodb.com/api/atlas/v1.0/groups/{GROUP-ID}/clusters/SingleRegionCluster/snapshots", 107 "rel":"http://mms.mongodb.com/snapshots" 108 } 109 ] 110 }