Take One On-Demand Snapshot

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.

Take one on-demand snapshot. Atlas takes on-demand snapshots immediately, unlike scheduled snapshots which occur at regular intervals. If there is already an on-demand snapshot with a status of queued or inProgress, you must wait until Atlas has completed the on-demand snapshot before taking another.

You must grant your API Key either the Project Owner role to successfully call this endpoint.

All requests to this endpoint must originate from an IP address in the organization's API access list.

Bulb IconTip
See Also:

Base URL:

POST /groups/{GROUP-ID}/clusters/{CLUSTER-NAME}/backup/snapshots
Path ElementTypeNecessityDescription
PROJECT-IDstringRequiredUnique identifier of the project for the Atlas cluster.
CLUSTER-NAMEstringRequiredName of the Atlas cluster that contains the snapshots you want to retrieve.

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

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

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
Path ElementTypeNecessityDescription
descriptionstringRequiredDescription of the on-demand snapshot.
retentionInDaysnumberRequiredNumber of days that Atlas should retain the on-demand snapshot. Must be at least 1 .
cloudProviderstringCloud provider that stores this snapshot. Atlas returns this parameter when "type": "replicaSet".
createdAtstringTimestamp in ISO 8601 date and time format in UTC when Atlas took the snapshot.
descriptionstringDescription of the snapshot. Atlas returns this parameter when "status": "onDemand".
expiresAtstringTimestamp in ISO 8601 date and time format in UTC when Atlas deletes the snapshot.
idstringUnique identifier of the snapshot.
linksarrayOne or more links to sub-resources and/or related resources. The relations between URL s are explained in the Web Linking Specification
masterKeyUUIDstringUnique identifier of the AWS KMS Customer Master Key used to encrypt the snapshot. Atlas returns this value for clusters using Encryption at Rest via Customer KMS.
membersarray of objectsList of snapshots and the cloud provider where the snapshots are stored. Atlas returns this parameter when "type": "shardedCluster".
stringCloud provider that stores this snapshot.
members[n].idstringUnique identifier for the sharded cluster snapshot.
members[n].replicaSetNamestringLabel given to a shard or config server from which Atlas took this snapshot.
mongodVersionstringVersion of the MongoDB server.
replicaSetNamestringLabel given to the replica set from which Atlas took this snapshot. Atlas returns this parameter when "type": "replicaSet".
snapshotIdsarray of stringsUnique identifiers of the snapshots created for the shards and config server for a sharded cluster. Atlas returns this parameter when "type": "shardedCluster". These identifiers should match those given in the members[n].id parameters. This allows you to map a snapshot to its shard or config server name.
snapshotTypestringType of snapshot. Atlas can return onDemand or scheduled.

Current status of the snapshot. Atlas can return one of the following values:

  • queued
  • inProgress
  • completed
  • failed
storageSizeBytesintegerSize of the snapshot in bytes.
typestringType of cluster. Atlas can return replicaSet or shardedCluster.
1curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" \
2 --digest --include \
3 --header "Accept: application/json" \
4 --header "Content-Type: application/json" \
5 --request POST "{PROJECT-ID}/clusters/{CLUSTER-NAME}/backup/snapshots?pretty=true" \
6 --data '{
7 "description": "On Demand Snapshot",
8 "retentionInDays": 5
9 }'
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}
2 "cloudProvider" : "AZURE",
3 "createdAt" : "2020-09-24T03:50:43Z",
4 "description" : "On Demand Snapshot",
5 "expiresAt" : "2020-09-29T03:50:43Z",
6 "id" : "{SNAPSHOT-ID}",
7 "links" : [ {
8 "href" : "{PROJECT-ID}/clusters/{CLUSTER-NAME}/backup/snapshots/{SNAPSHOT-ID}",
9 "rel" : "self"
10 }, {
11 "href" : "{PROJECT-ID}/clusters/{CLUSTER-NAME}",
12 "rel" : ""
13 } ],
14 "mongodVersion" : "4.0.20",
15 "replicaSetName" : "newCluster",
16 "snapshotType" : "onDemand",
17 "status" : "queued",
18 "storageSizeBytes" : 0,
19 "type" : "replicaSet"
Give Feedback