All Products
Search

This Product

    ApsaraDB for MongoDB:DescribeBackups

    Document Center

    ApsaraDB for MongoDB:DescribeBackups

    Last Updated:Sep 23, 2026

    Queries the backup list of an ApsaraDB for MongoDB instance.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    dds:DescribeBackups

    get

    *Instance

    acs:dds:{#regionId}:{#accountId}:dbinstance/{#dbinstanceId}

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    DBInstanceId

    string

    Yes

    The instance ID.

    Note

    If you set this parameter to the ID of a sharded cluster instance, you must also specify the NodeId parameter.

    dds-bp1a7009eb24****
    NodeId

    string

    No

    Instance ID of the shard node in the sharded cluster instance.

    Note

    This parameter is required if you set the DBInstanceId parameter to instance ID of a sharded cluster instance.

    d-bp128a003436****
    BackupId

    string

    No

    The instance ID.

    If you set the DBInstanceId parameter to the ID of a sharded cluster instance, the number of instance IDs is the same as the number of shard nodes. Separate multiple instance IDs with commas (,).

    2072****,2072****,2072****
    PageNumber

    integer

    No

    The page number. The value must be a positive integer that does not exceed the maximum value of the Integer data type. Default value: 1.

    1
    PageSize

    integer

    No

    The number of entries per page. Valid values:

    • 30 (default)

    • 50

    • 100

    Valid values:

    • 30 :

      30 entries per page.

    • 50 :

      50 entries per page.

    • 100 :

      100 entries per page.

    30
    StartTime

    string

    No

    The beginning of the time range to query. Specify the time in the yyyy-MM-ddTHH:mmZ format (UTC).

    Note

    This parameter is invalid if BackupId is specified.

    2022-01-13T13:00Z
    EndTime

    string

    No

    The end of the time range to query. The end time must be later than the start time. Specify the time in the yyyy-MM-ddTHH:mmZ format (UTC).

    Note

    This parameter is invalid if BackupId is specified.

    2022-01-14T13:00Z
    SrcRegion

    string

    No

    The region where the instance resides.

    Note

    • This parameter is required to restore a deleted instance.

    • This parameter is required for geo-redundancy backups.

    cn-beijing
    DestRegion

    string

    No

    The region where the backup resides.

    Note

    This parameter is required for geo-redundancy backups.

    cn-hangzhou
    ResourceGroupId

    string

    No

    The resource group ID.

    rg-xxxx
    BackupJobId

    string

    No

    The backup task ID.

    775051

    Response elements

    Element

    Type

    Description

    Example

    object

    The backup information of the instance.

    TotalCount

    integer

    The total number of backups.

    1
    RequestId

    string

    The request ID.

    275D43C3-F12F-5224-B375-************
    PageSize

    integer

    The number of entries per page. Valid values:

    • 30 (default)

    • 50

    • 100

    30
    PageNumber

    integer

    The page number.

    1
    Backups

    object

    Backup

    array<object>

    The list of backup file details.

    object

    The list of backup file details.

    BackupStatus

    string

    The backup status. Valid values:

    • Success: The backup is successful.

    • Failed: The backup failed.

    Success
    BackupType

    string

    The backup type. Valid values:

    • FullBackup: full backup.

    • IncrementalBackup: incremental backup.

    FullBackup
    BackupStartTime

    string

    The start time of the backup. The time is in the yyyy-MM-ddTHH:mm:ssZ format (UTC).

    2022-01-14T03:56:17Z
    BackupIntranetDownloadURL

    string

    The internal download URL of the backup file.

    Note

    You can use this URL to download the backup file from an ECS instance that is in the same network as the ApsaraDB for MongoDB instance.

    http://rdsbak-hz-v3.oss-cn-hangzhou-internal.aliyuncs.com/custins5559*****/hins1936****_data_2022052504****_qp.xb?Expires=165361****&OSSAccessKeyId=***********************&Signature=******************************&Region=cn-hangzhou
    BackupSize

    integer

    The size of the backup file. Unit: bytes.

    6168576
    BackupDownloadURL

    string

    The public download URL of the backup file. An empty string is returned if the backup file is currently unavailable for download.

    http://rdsbak-hz-v3.oss-cn-hangzhou.aliyuncs.com/custins5559****/hins1936****_data_2022052504****_qp.xb?Expires=165361****&OSSAccessKeyId=************************&Signature=******************************&Region=cn-hangzhou
    BackupMode

    string

    The backup mode. Valid values:

    • Automated: automatic backup.

    • Manual: manual backup.

    Automated
    BackupEndTime

    string

    The end time of the backup. The time is in the yyyy-MM-ddTHH:mm:ssZ format (UTC).

    2022-01-14T03:57:34Z
    BackupId

    string

    The backup ID.

    32102****
    BackupDBNames

    string

    The name of the backed-up database.

    database
    BackupMethod

    string

    The backup method. Valid values:

    • Snapshot: snapshot backup.

    • Physical: physical backup.

    • Logical: logical backup.

    Physical
    BackupJobId

    string

    The backup task ID.

    1123xxxx
    BackupName

    string

    The backup set name. This parameter is currently invalid.

    12345678.tar.gz
    BackupScale

    string

    The backup granularity. This parameter is currently invalid.

    DBInstance
    IsAvail

    boolean

    Indicates whether the backup set is available. Valid values:

    • 0: unavailable.

    • 1: available.

    1
    EngineVersion

    string

    The database engine version of the instance when the backup was created. Valid values:

    • 7.0

    • 6.0

    • 5.0

    • 4.4

    • 4.2

    • 4.0

    • 3.4

    4.2
    BackupExpireTime

    string

    The time when the backup expires. The time is in the yyyy-MM-ddTHH:mm:ssZ format (UTC).

    Important "9999-01-01T00:00:00Z" indicates long-term retention (LTR).

    2025-08-30T09:49:11Z

    Examples

    Success response

    JSON format

    {
  "TotalCount": 1,
  "RequestId": "275D43C3-F12F-5224-B375-************",
  "PageSize": 30,
  "PageNumber": 1,
  "Backups": {
    "Backup": [
      {
        "BackupStatus": "Success",
        "BackupType": "FullBackup",
        "BackupStartTime": "2022-01-14T03:56:17Z",
        "BackupIntranetDownloadURL": "http://rdsbak-hz-v3.oss-cn-hangzhou-internal.aliyuncs.com/custins5559*****/hins1936****_data_2022052504****_qp.xb?Expires=165361****&OSSAccessKeyId=***********************&Signature=******************************&Region=cn-hangzhou",
        "BackupSize": 6168576,
        "BackupDownloadURL": "http://rdsbak-hz-v3.oss-cn-hangzhou.aliyuncs.com/custins5559****/hins1936****_data_2022052504****_qp.xb?Expires=165361****&OSSAccessKeyId=************************&Signature=******************************&Region=cn-hangzhou",
        "BackupMode": "Automated",
        "BackupEndTime": "2022-01-14T03:57:34Z",
        "BackupId": "32102****",
        "BackupDBNames": "database",
        "BackupMethod": "Physical",
        "BackupJobId": "1123xxxx",
        "BackupName": "12345678.tar.gz",
        "BackupScale": "DBInstance",
        "IsAvail": true,
        "EngineVersion": "4.2",
        "BackupExpireTime": "2025-08-30T09:49:11Z"
      }
    ]
  }
}

    Error codes

    HTTP status code

    Error code

    Error message

    Description
    400 InvalidStartTime.Malformed The Specified parameter StartTime is not valid.
    400 InvalidEndTime.Malformed The Specified parameter EndTime is not valid.
    400 InvalidStartTimeAndEndTime.Malformed The Specified parameter StartTime or EndTime is not valid.
    400 InvalidPageSize.Malformed The specified parameter PageSize is not valid.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.