• API >
• API Resources >
• Clusters >
• Create a Cluster

Create a 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.

Note

This feature is not available for M0 (Free Tier) clusters. For more information, see Atlas M0 (Free Tier) Limitations.

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

copy

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

Request Path Parameters

Path Element	Type	Necessity	Description
GROUP-ID	string	Required	Unique identifier for the project in which to create the cluster. Each Atlas project supports up to 25 clusters. Please contact Atlas support for questions or assistance regarding the cluster limit. To contact support, select Support from the left-hand navigation bar of the Atlas UI.

Request Body Parameters

Body Parameter	Type	Necessity	Description
autoScaling	document	Optional	Configure your cluster to automatically scale its storage and cluster tier. For more information on cluster auto-scaling, see Cluster Auto-Scaling.
autoScaling .compute	document	Optional	Specifies whether the cluster automatically scales its cluster tier and whether the cluster can scale down. Important Cluster tier auto-scaling is not available for clusters using Low CPU or NVME storage classes.
autoScaling .compute .enabled	boolean	Optional	Specifies whether cluster tier auto-scaling is enabled. The default is false. Set to true to enable cluster tier auto-scaling. If enabled, you must specify a value for providerSettings.autoScaling.compute.maxInstanceSize. Set to false to disable cluster tier auto-scaling.
autoScaling .compute .scaleDownEnabled	boolean	Optional	Set to true to enable the cluster tier to scale down. This option is only available if autoScaling.compute.enabled is true. If this option is enabled, you must specify a value for providerSettings.autoScaling.compute.minInstanceSize
autoScaling .diskGBEnabled	boolean	Optional	Specifies whether disk auto-scaling is enabled. The default is true. Set to true to enable disk auto-scaling. Set to false to disable disk auto-scaling. Note Disk auto-scaling is subject to limitations based on the maximum amount of RAM for the selected cluster tier and the oplog size. See Customize Your Storage for details.
backupEnabled	boolean	Optional	Applicable only for M10+ clusters. Set to true to enable Atlas continuous backups for the cluster. Set to false to disable continuous backups for the cluster. Atlas deletes any stored snapshots. See the continuous backup Snapshot Schedule for more information. You cannot enable continuous backups if you have an existing cluster in the project with Cloud Provider Snapshots enabled. The default value is false. Note This option is not supported on sharded clusters running MongoDB 4.2. Sharded clusters running MongoDB 4.2 must use Cloud Provider Snapshots.
biConnector	document	Optional	Specifies BI Connector for Atlas configuration on this 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 .enabled	boolean	Optional	Specifies whether or not BI Connector for Atlas is enabled on the cluster. Set to true to enable BI Connector for Atlas. Set to false to disable BI Connector for Atlas.
biConnector .readPreference	string	Optional	Specifies the read preference to be used by BI Connector for Atlas on the cluster. Each BI Connector for Atlas read preference contains a distinct combination of readPreference and readPreferenceTags options. To learn more about BI Connector for Atlas read preferences, see BI Connector Read Preferences Table. Set to "primary" to have BI Connector for Atlas read from the primary. Set to "secondary" to have BI Connector for Atlas read from a secondary member. The preference defaults to this value if there are no analytics nodes in the cluster. Set to "analytics" to have BI Connector for Atlas read from an analytics node. Default if the cluster contains analytics nodes. Note To set the readPreference value to "analytics", the cluster must have at least one analytics node. If the readPreference value is "analytics", you cannot remove all analytics nodes from the cluster.
clusterType	string	Conditional	Type of the cluster that you want to create. When should you use clusterType? Condition Necessity You set replicationSpecs. Required You are deploying Global Clusters. Required You are deploying non-Global replica sets and sharded clusters. Optional Accepted values include: Value Cluster Type REPLICASET replica set SHARDED sharded cluster GEOSHARDED Global Cluster
diskSizeGB	double	Conditional	Capacity, in gigabytes, of the host’s root volume. Increase this number to add capacity, up to a maximum possible value of 4096 (i.e., 4 TB). This value must be a positive integer. When should you use diskSizeGB? This setting: Cannot be used with clusters with local NVMe SSDs Cannot be used with Azure clusters Must be used when replicationSpecs is set The minimum disk size for dedicated clusters is 10GB for AWS and GCP, and 32GB 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. For details, see Storage Capacity. 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.
encryptionAtRestProvider	string	Optional	Set the Encryption at Rest parameter to one of the following: AWS GCP Azure NONE Specify AWS to enable Encryption at Rest using the Atlas project AWS Key Management System settings. The cluster must meet the following requirements: Parameter Requirement providerSettings .instanceSizeName M10 or greater backupEnabled false or omitted 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 Encryption at Rest using Customer Key Management. Specify GCP to enable Encryption at Rest using the Atlas project GCP Key Management System settings. The cluster must meet the following requirements: Parameter Requirement providerSettings .instanceSizeName M10 or greater backupEnabled false or omitted 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 Encryption at Rest using Customer Key Management. Specify AZURE to enable Encryption at Rest using the Atlas project Azure Key Management System settings. The cluster must meet the following requirements: Parameter Requirement providerSettings .instanceSizeName M10 or greater backupEnabled false or omitted 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 Encryption at Rest using Customer Key Management. Specify NONE to disable Encryption at rest.
labels	array of documents	Optional	Array containing key-value pairs that tag and categorize the cluster. Each key and value has a maximum length of 255 characters. "labels": [ { "key": "example key", "value": "example value" } ]
name	string	Required	Name of the cluster as it appears in Atlas. Once the cluster is created, its name cannot be changed.
mongoDBMajorVersion	string	Optional	Version of the cluster to deploy. Atlas supports the following MongoDB versions for M10+ clusters: 3.4 3.6 4.0 4.2 You must set this value to 4.0 if providerSettings.instanceSizeName is either M2 or M5. Atlas always deploys the cluster with the latest stable release of the specified version. You can upgrade to a newer version of MongoDB when you modify a cluster.
numShards	integer	Conditional	Number of shards to deploy in a sharded cluster. Important If you use the replicationSpecs parameter, you must set numShards. The possible values are 1 through 50, inclusive. The default value is 1. If you specify a numShards value of 1 and a clusterType of SHARDED, Atlas deploys a single-shard sharded cluster. If you specify a numShards value of 1 and a clusterType of REPLICASET, Atlas deploys a replica set. Note A sharded cluster with a single shard is not recommended for production environments. Single-shard sharded clusters do not provide the same high availability and horizontal scaling benefits as configurations with multiple shards. For more information on sharded clusters, see Sharding in the MongoDB manual. For details on how this setting affects costs, see Number of Servers. Note Do not include in the request body for Global Clusters.
pitEnabled	boolean	Optional	Indicates if the cluster uses Point-in-Time backups. If set to true, providerBackupEnabled must also be set to true.
providerBackupEnabled	boolean	Optional	Applicable only for M10+ clusters. Flag indicating if the cluster uses Cloud Provider Snapshots for backups. If true, the cluster uses Cloud Provider Snapshots for backups. If providerBackupEnabled and backupEnabled are false, the cluster does not use Atlas backups. You cannot enable cloud provider snapshots if you have an existing cluster in the project with Continuous Backups enabled. Important You must set this value to true for NVMe clusters.
providerSettings	document	Required	Configuration for the provisioned servers on which MongoDB runs. The available options are specific to the cloud service provider.
providerSettings .autoScaling	document	Conditional	Contains the compute field which specifies the range of instance sizes to which your cluster can scale. Required if autoScaling.compute.enabled is true.
providerSettings .autoScaling .compute	document	Conditional	Contains the minInstanceSize and maxInstanceSize fields which specify the range of instance sizes to which your cluster can scale. Required if autoScaling.compute.enabled is true.
providerSettings .autoScaling .compute .minInstanceSize	string	Conditional	Minimum instance size to which your cluster can automatically scale (e.g., M10). Required if autoScaling.compute.scaleDownEnabled is true.
providerSettings .autoScaling .compute .maxInstanceSize	string	Conditional	Maximum instance size to which your cluster can automatically scale (e.g., M40). Required if autoScaling.compute.enabled is true.
providerSettings .backingProviderName	string	Conditional	Cloud service provider on which the server for a multi-tenant cluster is provisioned. This setting is only valid when providerSetting.providerName is TENANT and providerSetting.instanceSizeName is M2 or M5. The possible values are: AWS - Amazon AWS GCP - Google Cloud Platform AZURE - Microsoft Azure
providerSettings .diskIOPS	integer	AWS Optional	Maximum input/output operations per second (IOPS) the system can perform. The possible values depend on the selected providerSettings.instanceSizeName and diskSizeGB. This setting requires that providerSettings.instanceSizeName to be M30 or greater and cannot be used with clusters with local NVMe SSDs. To view the possible range of IOPS values for the selected instance size and storage capacity: Open the Atlas web interface. Select Build a New Cluster. Under Cloud Provider & Region, select AWS. Under Cloud Provider & Region, select the region corresponding to your configured providerSettings.regionName. Under Cluster Tier, select the cluster tier corresponding to your configured providerSettings.instanceSizeName. Under Cluster Tier, set the Storage Capacity slider to your configured diskSizeGB. Alternatively, input the exact value of diskSizeGB in the input box to the right of the slider. You can see the available IOPS range by checking the Provision IOPS box. Note If you set the diskIOPS value to a value higher than the default value for the selected volume size, Atlas automatically sets providerSettings.volumeType to PROVISIONED. If you manually set diskIOPS to the default value, you must specify providerSettings.volumeType to be either PROVISIONED or STANDARD. The default value for providerSettings.diskIOPS is the same as the cluster tier’s Standard IOPS value, as viewable in the Atlas interface. Changing this value affects the cost of running the cluster as described in the billing documentation. Atlas enforces the following minimum ratios by cluster tier to facilitate consistent network performance with large datasets. Disk Capacity to RAM: < M40: 3:1 M40: 50:1 => M50: 100 to 1 Example A cluster with 50 GB storage requires a value for IOPS of at least 150. To support 3 TB of disk capacity, you must select a cluster tier with at least 32 GB of RAM (M50 or higher).
providerSettings .diskTypeName	string	Azure Required	Azure disk type of the server’s root volume. If omitted, Atlas uses the default disk type for the selected providerSettings.instanceSizeName. 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 clusters 2 Default for M40+ Azure clusters
providerSettings .encryptEBSVolume	boolean	AWS Optional	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. Note This setting is always enabled for clusters with local NVMe SSDs. The default value is true.
providerSettings .instanceSizeName	string	Required	Atlas provides different cluster tiers, each with a default storage capacity and RAM size. The cluster you select is used for all the data-bearing servers in your cluster tier. For definitions of data-bearing servers, see Number of Servers. Important If you are deploying a Global Cluster, you must choose a cluster tier of M30 or larger. AWS Azure GCP 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 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 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 .providerName	string	Required	Cloud service provider on which the servers are provisioned. The possible values are: AWS - Amazon AWS GCP - Google Cloud Platform AZURE - Microsoft Azure TENANT - A multi-tenant deployment on one of the supported cloud service providers. Only valid when providerSettings.instanceSizeName is either M2 or M5. 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 .regionName	string	Conditional	Required if replicationSpecs array is empty This field is required if you have not set any values in the replicationSpecs array. Physical location of your MongoDB cluster. The region you choose can affect network latency for clients accessing your databases. Do not specify this field when creating a multi-region cluster using the replicationSpec document or a Global Cluster with the replicationSpecs array. During deployment of an M10+ dedicated paid cluster, Atlas creates a VPC for the selected provider and region or regions if no existing VPC or VPC peering connection exists for that provider and region. Atlas assigns the VPC a Classless Inter-Domain Routing (CIDR) block. For clusters deployed on AWS, if you want to create a VPC peering connection to an AWS VPC and require a specific CIDR block for a given region, you must create a VPC connection before deploying the cluster. See Set up a Network Peering Connection for for complete documentation on VPC peering connections. Important Multi-region clusters require one VPC peering connection for each region. MongoDB nodes can use only the peering connection that resides in the same region as the nodes to communicate with the peered VPC. Select your cloud provider’s tab for example cluster region names: AWS Azure GCP US_EAST_1 US_WEST_2 EU_WEST_1 For a complete list of supported AWS regions, see Amazon Web Services (AWS). US_EAST_2 US_WEST EUROPE_NORTH For a complete list of supported Azure regions, see Microsoft Azure. CENTRAL_US WESTERN_EUROPE EASTERN_ASIA_PACIFIC For a complete list of supported GCP regions, see Google Cloud Platform (GCP).
providerSettings .volumeType	string	AWS Optional	Possible values are: Volume Type providerSettings.diskIOPS Value STANDARD Must not exceed the default IOPS rate for the selected volume size. PROVISIONED Must fall within the allowable IOPS range for the selected volume size.
replicationFactor	number	Optional	Use replicationSpecs replicationFactor is deprecated. Use replicationSpecs. Number of replica set members. Each member keeps a copy of your databases, providing high availability and data redundancy. The possible values are 3, 5, or 7. The default value is 3. Do not specify this field when creating a multi-region cluster using the replicationSpec document. 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. Atlas ignores this value if you pass the replicationSpec document.
replicationSpec	document	Optional	Use replicationSpecs replicationSpec is deprecated. Use replicationSpecs. Configuration of each region in a multi-region cluster. Each element in this document represents a region where Atlas deploys your cluster. For single-region clusters, you can either specify the providerSettings.regionName and replicationFactor, or you can use the replicationSpec document to define a single region. For multi-region clusters, omit the providerSettings.regionName field. For Global Clusters, specify the replicationSpecs parameter rather than a replicationSpec parameter. Important If you use replicationSpec, you must specify a minimum of one replicationSpec.<region> document and sort each .<region> document by .<region>.priority in descending order. Use the replicationSpecs parameter to create a Global Cluster. Note You cannot specify both the replicationSpec and replicationSpecs parameters in the same request body.
replicationSpec .<region>	document	Required	Physical location of the region. Replace <region> with the name of the region. Each <region> document describes the region’s priority in elections and the number and type of MongoDB nodes Atlas deploys to the region. Important If you use replicationSpec, you must specify a minimum of one replicationSpec.<region> document and sort each .<region> document by .<region>.priority in descending order. Select your cloud provider’s tab for example cluster region names: AWS Azure GCP US_EAST_1 US_WEST_2 EU_WEST_1 For a complete list of supported AWS regions, see Amazon Web Services (AWS). US_EAST_2 US_WEST EUROPE_NORTH For a complete list of supported Azure regions, see Microsoft Azure. CENTRAL_US WESTERN_EUROPE EASTERN_ASIA_PACIFIC For a complete list of supported GCP regions, see Google Cloud Platform (GCP). For each <region> document, you must specify the analyticsNodes, electableNodes, priority, and readOnlyNodes fields. For information on cross-region node limits, see Considerations. During deployment of an M10+ dedicated paid cluster, Atlas creates a VPC for the selected provider and region or regions if no existing VPC or VPC peering connection exists for that provider and region. Atlas assigns the VPC a Classless Inter-Domain Routing (CIDR) block. For clusters deployed on AWS, if you want to create a VPC peering connection to an AWS VPC and require a specific CIDR block for a given region, you must create a VPC connection before deploying the cluster. See Set up a Network Peering Connection for for complete documentation on VPC peering connections. Important Multi-region clusters require one VPC peering connection for each region. MongoDB nodes can use only the peering connection that resides in the same region as the nodes to communicate with the peered VPC.
replicationSpec .<region> .electableNodes	integer	Optional	Number of electable nodes for Atlas to deploy to the region. Electable nodes can become the primary and can facilitate local reads. The total number of electableNodes across all replicationSpec.<region> document must be 3, 5, or 7. Specify 0 if you do not want any electable nodes in the region. You cannot create electable nodes if the replicationSpec.<region>.priority is 0.
replicationSpec .<region> .priority	integer	Optional	Election priority of the region. For regions with only replicationSpec.<region>.readOnlyNodes, set this value to 0. For regions where replicationSpec.<region>.electableNodes is at least 1, each replicationSpec.<region> must have a priority of exactly one (1) less than the previous region. The first region must have a priority of 7. The lowest possible priority is 1. The priority 7 region identifies the Preferred Region of the cluster. Atlas places the primary node in the Preferred Region. Priorities 1 through 7 are exclusive - no more than one region per cluster can be assigned a given priority. Example If you have three regions, their priorities would be 7, 6, and 5 respectively. If you added two more regions for supporting electable nodes, the priorities of those regions would be 4 and 3 respectively.
replicationSpec .<region> .readOnlyNodes	integer	Optional	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.
replicationSpec .<region> .analyticsNodes	integer	Optional	The 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	array of documents	Conditional	Configuration for cluster regions. When should you use replicationSpecs? Condition Necessity Values You are deploying Global Clusters. Required Each document in the array represents a zone where Atlas deploys your cluster’s nodes. You are deploying non-Global replica sets and sharded clusters. Optional This array has one document representing where Atlas deploys your cluster’s nodes. You must specify all parameters in replicationSpecs document array. What parameters depend on replicationSpecs? If you set replicationSpecs, you must: Set clusterType Set numShards Not set replicationSpec Not use clusters with local NVMe SSDs Not use Azure clusters
replicationSpecs[n] .id	string	Conditional	Unique identifer of the replication document for a zone in a Global Cluster. When is this value needed? Condition Necessity Existing zones included in a cluster modification request body. Required Adding a new zone to an existing Global Cluster. Optional Warning Atlas deletes any existing zones in a Global Cluster that are not included in a cluster modification request.
replicationSpecs[n] .numShards	integer	Required	Number of shards to deploy in the specified zone. The default value is 1.
replicationSpecs[n] .regionsConfig	document	Optional	Physical location of the region. Each regionsConfig document describes the region’s priority in elections and the number and type of MongoDB nodes that Atlas deploys to the region. Important If you use replicationSpec, you must specify a minimum of one replicationSpec.<regionsConfigs> document and sort each .<regionsConfig> by .<regionsConfig>.priority in descending order. During deployment of an M10+ dedicated paid cluster, Atlas creates a VPC for the selected provider and region or regions if no existing VPC or VPC peering connection exists for that provider and region. Atlas assigns the VPC a Classless Inter-Domain Routing (CIDR) block. For clusters deployed on AWS, if you want to create a VPC peering connection to an AWS VPC and require a specific CIDR block for a given region, you must create a VPC connection before deploying the cluster. See Set up a Network Peering Connection for for complete documentation on VPC peering connections. Important Multi-region clusters require one VPC peering connection for each region. MongoDB nodes can use only the peering connection that resides in the same region as the nodes to communicate with the peered VPC. Select your cloud provider’s tab for example cluster region names: AWS Azure GCP US_EAST_1 US_WEST_2 EU_WEST_1 For a complete list of supported AWS regions, see Amazon Web Services (AWS). US_EAST_2 US_WEST EUROPE_NORTH For a complete list of supported Azure regions, see Microsoft Azure. CENTRAL_US WESTERN_EUROPE EASTERN_ASIA_PACIFIC For a complete list of supported GCP regions, see Google Cloud Platform (GCP).
replicationSpecs[n] .regionsConfig .electableNodes	integer	Required	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 .readOnlyNodes	integer	Required	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 .analyticsNodes	integer	Optional	The 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 .priority	integer	Required	Election priority of the region. For regions with only read-only nodes, set this value to 0.
replicationSpecs[n] .zoneName	string	Optional	Name for the zone in a Global Cluster. Do not provide this value if clusterType is not GEOSHARDED.

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: Open the Atlas web interface. Click the button to add a new cluster. View the available default sizes. 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: AWS GCP Azure 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. AWS Azure GCP 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

• Create Single Region
• Create Multi-Region
• Create Global

copy

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
  --header "Content-Type: application/json" \
  --include \
  --request POST "https://cloud.mongodb.com/api/atlas/v1.0/groups/{group-id}/clusters" \
  --data '
    {
      "name" : "DataStore",
      "diskSizeGB" : 100,
      "numShards" : 1,
      "providerSettings" : {
        "providerName" : "AWS",
        "diskIOPS" : 300,
        "instanceSizeName" : "M40",
        "regionName" : "US_EAST_1"
      },
      "replicationFactor" : 3,
      "backupEnabled" : true,
      "autoScaling": {
        "diskGBEnabled" :true
      }
    }'

copy

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
  --header "Content-Type: application/json" \
  --include \
  --request POST "https://cloud.mongodb.com/api/atlas/v1.0/groups/{group-id}/clusters" \
  --data '
    {
      "name" : "DataStore2",
      "diskSizeGB" : 100,
      "numShards" : 1,
      "providerSettings" : {
        "providerName" : "AWS",
        "diskIOPS" : 300,
        "instanceSizeName" : "M10"
      },
      "replicationSpec": {
          "US_EAST_1": {
            "electableNodes": 3,
            "priority": 7,
            "readOnlyNodes" : 0
          },
          "US_EAST_2": {
            "electableNodes": 2,
            "priority" : 6,
            "readOnlyNodes" : 0
          },
          "US_WEST_1": {
            "electableNodes" : 2,
            "priority" : 5,
            "readOnlyNodes": 2
          }
      },
      "backupEnabled" : true
    }'

copy

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
   --header "Content-Type: application/json" \
   --include \
   --request POST "https://cloud.mongodb.com/api/atlas/v1.0/groups/{group-id}/clusters?pretty=true" \
   --data '
     {
       "name": "DataStore3",
       "diskSizeGB": 80,
        "providerSettings": {
          "providerName": "AWS",
          "diskIOPS": "240",
          "instanceSizeName": "M30"
        },
        "replicationSpecs": [{
          "zoneName": "Zone 1",
          "numShards": 2,
          "regionsConfig": {
            "US_EAST_1": {
              "electableNodes": 3,
              "readOnlyNodes": 0,
              "priority": 7
            }
          }
        },
        {
          "zoneName": "Zone 2",
          "numShards": 2,
          "regionsConfig": {
            "EU_CENTRAL_1": {
              "electableNodes": 3,
              "readOnlyNodes": 0,
              "priority": 7
            }
          }
        }],
        "backupEnabled": false,
        "providerBackupEnabled" : true,
        "clusterType": "GEOSHARDED"
     }'

Response

{
  "autoScaling": {
    "compute": {
      "enabled": false,
      "scaleDownEnabled": false
    },
    "diskGBEnabled": true
  },
  "backupEnabled":true,
  "biConnector":{
     "enabled":false,
     "readPreference":"secondary"
  },
  "clusterType":"REPLICASET",
  "diskSizeGB":100.0,
  "encryptionAtRestProvider":"NONE",
  "groupId":"{group-id}",
  "id":"5c87f79087d9d612a175f46d",
  "labels": [],
  "links":[
     {
        "href":"https://cloud.mongodb.com/api/atlas/v1.0/groups/{group-id}/clusters/DataStore",
        "rel":"self"
     },
     {
        "href":"https://cloud.mongodb.com/api/atlas/v1.0/groups/{group-id}/clusters/DataStore/restoreJobs",
        "rel":"http://mms.mongodb.com/restoreJobs"
     },
     {
        "href":"https://cloud.mongodb.com/api/atlas/v1.0/groups/{group-id}/clusters/DataStore/snapshots",
        "rel":"http://mms.mongodb.com/snapshots"
     }
  ],
  "mongoDBMajorVersion":"4.0",
  "mongoDBVersion":"4.0.6",
  "mongoURIUpdated":"2019-03-12T18:16:48Z",
  "name":"DataStore",
  "numShards":1,
  "paused":false,
  "providerBackupEnabled":false,
  "providerSettings":{
     "providerName":"AWS",
     "diskIOPS":300,
     "encryptEBSVolume":true,
     "instanceSizeName":"M40",
     "regionName":"US_EAST_1",
     "volumeType":"STANDARD"
  },
  "replicationFactor":3,
  "replicationSpec":{
     "US_EAST_1":{
        "analyticsNodes":0,
        "electableNodes":3,
        "priority":7,
        "readOnlyNodes":0
     }
  },
  "replicationSpecs":[
     {
        "id":"5c87f79087d9d612a175f46c",
        "numShards":1,
        "regionsConfig":{
           "US_EAST_1":{
              "analyticsNodes":0,
              "electableNodes":3,
              "priority":7,
              "readOnlyNodes":0
           }
        },
        "zoneName":"Zone 1"
     }
  ],
  "stateName":"CREATING"
}

{
  "autoScaling": {
    "compute": {
      "enabled": false,
      "scaleDownEnabled": false
    },
    "diskGBEnabled": true
  },
  "backupEnabled":true,
  "biConnector":{
     "enabled":false,
     "readPreference":"secondary"
  },
  "clusterType":"REPLICASET",
  "diskSizeGB":100.0,
  "encryptionAtRestProvider":"NONE",
  "groupId":"{group-id}",
  "id":"5c87f50987d9d612a1739b89",
  "links":[
     {
        "href":"https://cloud.mongodb.com/api/atlas/v1.0/groups/{group-id}/clusters/DataStore2",
        "rel":"self"
     },
     {
        "href":"https://cloud.mongodb.com/api/atlas/v1.0/groups/{group-id}/clusters/DataStore2/restoreJobs",
        "rel":"http://mms.mongodb.com/restoreJobs"
     },
     {
        "href":"https://cloud.mongodb.com/api/atlas/v1.0/groups/{group-id}/clusters/DataStore2/snapshots",
        "rel":"http://mms.mongodb.com/snapshots"
     }
  ],
  "mongoDBMajorVersion":"4.0",
  "mongoDBVersion":"4.0.6",
  "mongoURIUpdated":"2019-03-12T18:06:01Z",
  "name":"DataStore2",
  "numShards":1,
  "paused":false,
  "providerBackupEnabled":false,
  "providerSettings":{
     "providerName":"AWS",
     "diskIOPS":300,
     "encryptEBSVolume":true,
     "instanceSizeName":"M10",
     "volumeType":"STANDARD"
  },
  "replicationSpec":{
     "US_EAST_1":{
        "analyticsNodes":0,
        "electableNodes":3,
        "priority":7,
        "readOnlyNodes":0
     },
     "US_EAST_2":{
        "analyticsNodes":0,
        "electableNodes":2,
        "priority":6,
        "readOnlyNodes":0
     },
     "US_WEST_1":{
        "analyticsNodes":0,
        "electableNodes":2,
        "priority":5,
        "readOnlyNodes":2
     }
  },
  "replicationSpecs":[
     {
        "id":"5c87f50887d9d612a1739b86",
        "numShards":1,
        "regionsConfig":{
           "US_EAST_1":{
              "analyticsNodes":0,
              "electableNodes":3,
              "priority":7,
              "readOnlyNodes":0
           },
           "US_EAST_2":{
              "analyticsNodes":0,
              "electableNodes":2,
              "priority":6,
              "readOnlyNodes":0
           },
           "US_WEST_1":{
              "analyticsNodes":0,
              "electableNodes":2,
              "priority":5,
              "readOnlyNodes":2
           }
        }
     }
  ],
  "stateName":"CREATING"
}

{
  "autoScaling": {
    "compute": {
      "enabled": false,
      "scaleDownEnabled": false
    },
    "diskGBEnabled": true
  },
  "backupEnabled" : false,
  "biConnector" : {
    "enabled" : false,
    "readPreference" : "secondary"
  },
  "clusterType" : "GEOSHARDED",
  "diskSizeGB" : 80.0,
  "encryptionAtRestProvider" : "NONE",
  "groupId" : "{group-id}",
  "id" : "5c87f04780eef53f47af4f8b",
  "links" : [ {
    "href" : "https://cloud.mongodb.com/api/atlas/v1.0/groups/{group-id}/clusters/DataStore3",
    "rel" : "self"
  }, {
    "href" : "https://cloud.mongodb.com/api/atlas/v1.0/groups/{group-id}/clusters/DataStore3/restoreJobs",
    "rel" : "http://mms.mongodb.com/restoreJobs"
  }, {
    "href" : "https://cloud.mongodb.com/api/atlas/v1.0/groups/{group-id}/clusters/DataStore3/snapshots",
    "rel" : "http://mms.mongodb.com/snapshots"
  } ],
  "mongoDBMajorVersion" : "4.0",
  "mongoDBVersion" : "4.0.6",
  "mongoURIUpdated" : "2019-03-12T17:45:43Z",
  "name" : "DataStore3",
  "paused" : false,
  "providerBackupEnabled" : true,
  "providerSettings" : {
    "providerName" : "AWS",
    "diskIOPS" : 240,
    "encryptEBSVolume" : true,
    "instanceSizeName" : "M30",
    "volumeType" : "STANDARD"
  },
  "replicationSpecs" : [ {
    "id" : "5c87f04680eef53f47af4f7d",
    "numShards" : 2,
    "regionsConfig" : {
      "US_EAST_1" : {
        "analyticsNodes" : 0,
        "electableNodes" : 3,
        "priority" : 7,
        "readOnlyNodes" : 0
      }
    },
    "zoneName" : "Zone 1"
  }, {
    "id" : "5c87f04680eef53f47af4f7e",
    "numShards" : 2,
    "regionsConfig" : {
      "EU_CENTRAL_1" : {
        "analyticsNodes" : 0,
        "electableNodes" : 3,
        "priority" : 7,
        "readOnlyNodes" : 0
      }
    },
    "zoneName" : "Zone 2"
  } ],
  "stateName" : "CREATING"
}

Considerations

• For a given region in an Atlas project with multi-region clusters or clusters in multiple regions, there is a limit of 40 MongoDB nodes on all other regions in that project. This limit applies across all cloud service providers and can be raised upon request. GCP regions communicating with each other do not count against this limit.

  Example

  If an Atlas project has 20 nodes in Region A and 20 nodes in Region B, you can deploy no more than 20 additional nodes in that project in any given region. This limit applies even if Region A and Region B are backed by different cloud service providers.

  For Atlas projects where every cluster is deployed to a single region, you cannot create a multi-region cluster in that project if there are already 40 or more nodes in that single region unless you request that the limit be raised.

  Please contact Atlas support for questions or assistance raising this limit. To contact support, click Support from the left-hand navigation bar of the Atlas UI.

• If your Atlas project contains a custom role that uses actions introduced in a specific MongoDB version, you must delete that role before creating clusters with an earlier MongoDB version.

←   Get Advanced Configuration Options for One Cluster Modify a Cluster  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.