Navigation

Get a Single Cluster

Note

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

The Atlas API uses HTTP Digest Authentication. Provide your Atlas username and API key as the username and password when constructing the HTTP request.

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

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

Syntax

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

Request Path Parameters

Path Element Required/Optional Description
GROUP-ID Required. The unique identifier for the project containing the cluster you want to retrieve.
CLUSTER-NAME Required The name of the cluster to retrieve.

HTTP Response Elements

Name Type Description
autoScaling document

Information on whether disk auto-scaling is enabled. The document contains diskGBEnabled field set to:

  • true if enabled.
  • false if disabled.

Default is true.

biConnector document

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

The BI Connector for Atlas is only available for M10+ clusters.

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.
name string The name of the cluster as it appears in Atlas.
groupId string ID of the project the cluster belongs to.
id string ID of the cluster.
mongoDBVersion string The version of MongoDB the cluster runs, in <major version>.<minor version> format.
mongoDBMajorVersion string

The major version of MongoDB the cluster runs:

  • 3.2 [1]
  • 3.4
  • 3.6
mongoURI string

The base connection string for the cluster. Include the following query parameters to use the mongoURI for connecting to the Atlas cluster

  • replicaSet=<replica set name> (replica set clusters only)
  • ssl=true
  • authSource=admin

Include a username and password for a MongoDB user associated to the Atlas project directly after the mongodb:// protocol portion of the mongoURI. To review the connection string format, see the connection string format documentation. To add MongoDB users to a Atlas project, see Add MongoDB Users.

You cannot connect to a Atlas cluster using mongoURI without all the specified query parameters and the user authentication information.

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

The 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.

Include a username and password for a MongoDB user associated to the Atlas project directly after the mongodb:// protocol portion of the mongoURI. To review the connection string format, see the connection string format documentation. To add MongoDB users to a Atlas project, see Add MongoDB Users.

You cannot connect to a Atlas cluster using mongoURIWithOptions without the user authentication information.

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

numShards integer

Selects whether the cluster is a sharded cluster or a replica set and specifies the number of shards for a sharded cluster.

If this is set to 1, the cluster is a replica set. For more information on MongoDB replica sets, see Replication in the MongoDB manual.

If this is set to 2 or higher, the cluster is a sharded cluster with the number of shards specified. For more information on sharded clusters, see Sharding in the MongoDB manual.

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

The possible values are 1 through 12.

paused boolean A flag that indicates whether the cluster is paused or not.
providerSettings document The configuration for the provisioned servers on which MongoDB runs. The available options are specific to the cloud service provider.
providerSettings.providerName string

The 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

The 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

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

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 VPC Peering Connection for for complete documentation on VPC peering connections.

Important

AWS does not support cross-region VPC peering. Multi-region clusters require one VPC peering connection per region. Only those MongoDB nodes in that region can use the peering connection to communicate with the peered VPC.

Provider Regions
AWS
  • US_EAST_1
  • US_EAST_2
  • US_WEST_1
  • US_WEST_2
  • CA_CENTRAL_1
  • EU_WEST_1
  • EU_WEST_2
  • EU_CENTRAL_1
  • AP_NORTHEAST_1
  • AP_NORTHEAST_2
  • AP_SOUTHEAST_1
  • AP_SOUTHEAST_2
  • AP_SOUTH_1
  • SA_EAST_1
GCP

Note

EASTERN_US corresponds to the GCP us_east_1 region.

  • EASTERN_US
  • US_EAST_4
  • CENTRAL_US
  • WESTERN_US
  • SOUTH_AMERICA_EAST_1
  • WESTERN_EUROPE
  • EUROPE_WEST_2
  • EUROPE_WEST_3
  • EASTERN_ASIA_PACIFIC
  • NORTHEASTERN_ASIA_PACIFIC
  • SOUTHEASTERN_ASIA_PACIFIC
  • ASIA_SOUTH_1
  • AUSTRALIA_SOUTHEAST_1
Azure
  • US_CENTRAL
  • US_EAST
  • US_EAST_2
  • US_NORTH_CENTRAL
  • US_WEST
  • US_SOUTH_CENTRAL
  • EUROPE_NORTH
  • EUROPE_WEST
  • US_WEST_2
  • CANADA_EAST
  • CANADA_CENTRAL
  • BRAZIL_SOUTH
  • AUSTRALIA_EAST
  • AUSTRALIA_SOUTH_EAST
  • UK_SOUTH
  • UK_WEST
  • INDIA_CENTRAL
  • INDIA_WEST
  • INDIA_SOUTH
  • ASIA_EAST
  • JAPAN_EAST
  • JAPAN_WEST
  • ASIA_SOUTH_EAST
  • KOREA_CENTRAL
  • KOREA_SOUTH
providerSettings.instanceSizeName string

The name of the instance size used for the Atlas cluster.

  • M0
  • M2
  • M5
  • M10 ( GCP and AWS only )
  • M20
  • M30
  • M40
  • R40 ( AWS only )
  • M50
  • R40 ( AWS only )
  • M60
  • R60 ( AWS only )
  • M80 ( GCP only )
  • R80 ( AWS only )
  • M90 ( Azure only )
  • M100 ( AWS only )
  • M140 ( AWS only )
  • M200 ( AWS only )
  • M300 ( AWS only )
  • R400 ( AWS only )

See Microsoft Azure, Google Cloud Platform, or Amazon Web Services for complete documentation of each instance size and its default resources for a given cloud service provider.

providerSettings.diskIOPS integer The 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 instances

2 Default for M40+ Azure instances

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 instance.
replicationFactor number

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

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 The configuration of each region in the cluster. Each element in this document represents a region where Atlas deploys your cluster.
replicationSpec.<region> document

The 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 The number of electable nodes in the region. Electable nodes can become the primary and can facilitate local reads.
replicationSpec.<region>.priority integer

The 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 The number of read-only nodes in the region. Read-only nodes can never become the primary, but can facilitate local-reads.
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 instance size 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.

backupEnabled Boolean true if you enabled continuous backups for the cluster.
stateName string

The current state of the cluster. The possible states are:

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

Example

Request

curl -i -u "username:apiKey" --digest "https://cloud.mongodb.com/api/atlas/v1.0/groups/5356823b3794de37132bb7b/clusters/LogData"

Response

HTTP/1.1 200 OK

{
  "autoScaling":{"diskGBEnabled":true},
  "backupEnabled" : true,
  "diskSizeGB" : 80,
  "groupId" : "5356823b3794de37132bb7b",
  "mongoDBVersion" : "3.4.9",
  "mongoURI" : "mongodb://mongo-shard-00-00.mongodb.net:27017,mongo-shard-00-01.mongodb.net:27017,mongo-shard-00-02.mongodb.net:27017",
  "mongoURIUpdated" : "2017-10-23T21:26:17Z",
  "mongoURIWithOptions" : "mongodb://mongo-shard-00-00.mongodb.net:27017,mongo-shard-00-01.mongodb.net:27017,mongo-shard-00-02.mongodb.net:27017/?ssl=true&authSource=admin&replicaSet=mongo-shard-0",
  "name" : "LogData",
  "numShards" : 2,
  "paused" : false,
  "providerSettings" : {
    "providerName" : "AWS",
    "diskIOPS" : 240,
    "encryptEBSVolume" : false,
    "instanceSizeName" : "M40",
    "regionName" : "US_EAST_1"
  },
  "replicationFactor" : 3,
  "replicationSpec": {
      "US_EAST_1": {
          "electableNodes": 3,
          "priority": 7,
          "readOnlyNodes": 0
      }
  },
  "stateName" : "IDLE"
}
[1]

MongoDB Server 3.2 is planned for End of Life on September 2018. Atlas deprecated support for deploying clusters with MongoDB 3.2 in March, 2018.

Atlas will automatically upgrade any clusters running MongoDB 3.2 to MongoDB 3.4 in September 2018. Project Owners can upgrade their MongoDB 3.2 clusters at any time before then.

See I have a cluster running MongoDB 3.2. How does the upcoming End of Life affect me? for guidance on how to manage Atlas clusters currently running MongoDB 3.2.