All Products
Search

This Product

    Data Management:DescribeBackupPlanList

    Document Center

    Data Management:DescribeBackupPlanList

    Last Updated:Mar 30, 2026

    Queries DBS backup plans.

    Operation description

    Before you use this operation, ensure that Object Storage Service (OSS) is enabled. For more information, see Object Storage Service.

    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

    dbs:DescribeBackupPlanList

    get

    *BackupPlan

    acs:dbs:{#regionId}:{#accountId}:backupplan/{#BackupPlanId}

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    BackupPlanId

    string

    No

    Backup plan ID. To list multiple backup plans, separate IDs with commas.

    dbstooi01exXXXX
    Region

    string

    No

    DBS region. Call DescribeRegions to view supported regions.

    cn-hangzhou
    PageSize

    integer

    No

    Number of records per page. Valid values: 1 to 100.

    Note

    Default value: 30.

    30
    PageNum

    integer

    No

    Page number. Valid values: integers greater than or equal to 0 and less than or equal to the maximum integer value. Default value: 0.

    1
    BackupPlanName

    string

    No

    Backup plan name.

    test123
    BackupPlanStatus

    string

    No

    Backup plan status. Valid values:

    • wait: Not configured.

    • init: Not started (precheck failed).

    • running: Running.

    • stop: Failed.

    • pause: Paused.

    • locked: Locked.

    • check_pass: Precheck passed.

    wait
    ClientToken

    string

    No

    A client token used to ensure idempotence and prevent duplicate requests.

    ASDASDASDSADASFCZXVZ
    ResourceGroupId

    string

    No

    Resource group ID.

    rg-aekzecovzti****

    Response elements

    Element

    Type

    Description

    Example

    object

    Response parameters are described below.

    HttpStatusCode

    integer

    HTTP status code.

    200
    PageNum

    integer

    Page number.

    1
    RequestId

    string

    Request ID.

    4F1888AC-1138-4995-B9FE-D2734F61C058
    ErrCode

    string

    Error code.

    InvalidParameterValid
    Success

    boolean

    Indicates whether the request succeeded.

    true
    ErrMessage

    string

    Error message.

    The specified parameter %s value is not valid.

    TotalPages

    integer

    Total number of pages.

    4
    TotalElements

    integer

    Total number of backup plans.

    100
    PageSize

    integer

    Number of records per page.

    30
    Items

    object

    BackupPlanDetail

    array<object>

    Backup plan details.

    object

    Response value.

    CrossRoleName

    string

    RAM role name for cross-account backups.

    test123
    SourceEndpointInstanceType

    string

    Database location. Valid values:

    • rds

    • ecs

    • express: Database connected through a leased line, VPN Gateway, or Smart Access Gateway.

    • agent: Database connected through a backup gateway.

    • dds: ApsaraDB for MongoDB.

    • other: Database connected directly by IP address and port.

    rds
    BackupSetDownloadDir

    string

    Server directory for downloading backup sets.

    */test/test123
    SourceEndpointIpPort

    string

    Database endpoint.

    100.*.*.10:33204
    CrossAliyunId

    string

    User ID for cross-account backups.

    2xxx7778xxxxxxxxxx
    DuplicationArchivePeriod

    integer

    The number of days to retain backups in archive cold storage.

    365
    BackupPlanId

    string

    Backup plan ID.

    dbstooi01eXXXX
    EndTimestampForRestore

    integer

    End timestamp of the time range during which you can restore the database.

    1554560477000
    BackupPlanStatus

    string

    Backup plan status. Valid values:

    • wait: Not configured.

    • init: Not started (precheck failed).

    • running: Running.

    • stop: Failed.

    • pause: Paused.

    • locked: Locked.

    • check_pass: Precheck passed.

    init
    BackupSetDownloadFullDataFormat

    string

    Full data format for downloaded backup sets. Valid values:

    • Native

    • SQL

    • CSV

    • JSON

    SQL
    BackupRetentionPeriod

    integer

    Number of days to retain backup data. Valid values: 0 to 1825.

    365
    OSSBucketRegion

    string

    OSS bucket region.

    cn-hangzhou
    SourceEndpointOracleSID

    string

    Oracle system ID (SID) name.

    test
    BackupStorageType

    string

    Built-in storage type. Valid values:

    • Empty (default): Backup data is stored in your OSS bucket.

    • system: Backup data is stored in DBS's built-in OSS bucket.

    system
    BackupMethod

    string

    Backup method. Valid values:

    • logical: Logical backup.

    • physical: Physical backup.

    • duplication: Duplicate backup.

    logical
    SourceEndpointRegion

    string

    Database region.

    cn-hangzhou
    BackupPeriod

    string

    Full backup schedule. Valid values:

    • Monday

    • Tuesday

    • Wednesday

    • Thursday

    • Friday

    • Saturday

    • Sunday

    Monday
    SourceEndpointDatabaseName

    string

    Database name.

    test
    BackupSetDownloadGatewayId

    integer

    Backup gateway ID for downloading backup sets.

    123123
    BackupPlanCreateTime

    integer

    Backup plan creation timestamp.

    1582527713000
    InstanceClass

    string

    Instance specification. Valid values:

    • micro: Entry-level.

    • small: Low-spec.

    • medium: Medium-spec.

    • large: High-spec.

    • xlarge: High-spec (no traffic limit).

    micro
    BackupSetDownloadTargetType

    string

    Target type for downloading backup sets.

    Note

    Only valid value: agent. Indicates that a backup gateway is installed.

    agent
    DuplicationInfrequentAccessPeriod

    integer

    Number of days before backups move to Infrequent Access storage.

    180
    BackupStartTime

    string

    Start time for full backups. Format: HH:mm.

    14:22
    ErrMessage

    string

    Precheck error message.

    can not connect to oracle instance orcl with user dbs
    BackupObjects

    string

    Backup objects.

    [ { \"DBName\":\"database_name\", \"SchemaName\":\"schema_name\", \"TableIncludes\":[{ \"TableName\":\"table_name\" }], \"TableExcludes\":[{ \"TableName\":\"excluded_table_name\" }] } ]
    BeginTimestampForRestore

    integer

    Start timestamp of the time range during which you can restore the database.

    1554560477000
    SourceEndpointInstanceID

    string

    Database instance ID.

    test
    OpenBackupSetAutoDownload

    boolean

    Indicates whether automatic backup set download is enabled.

    true
    BackupPlanName

    string

    Backup plan name.

    dbstooi01e****
    OSSBucketName

    string

    OSS bucket name.

    dbs-backup-1857XXXXX489
    BackupGatewayId

    integer

    Backup gateway ID.

    827362187368736
    SourceEndpointUserName

    string

    Database account.

    test
    BackupSetDownloadIncrementDataFormat

    string

    Incremental data format for downloaded backup sets. Valid values:

    • Native

    • SQL

    • CSV

    • JSON

    SQL
    EnableBackupLog

    boolean

    Indicates whether incremental log backup is enabled. Valid values:

    • true: Enabled.

    • false: Disabled.

    true
    ResourceGroupId

    string

    Resource group ID.

    rg-aekzecovzti****
    DatabaseType

    string

    Database type.

    MySQL
    BackupPlanRegion

    string

    cn-beijing
    SourceEndpointHost

    string

    127.0.0.1
    InstanceChargeType

    string

    PREPAY
    InstanceExpiredTimestamp

    integer

    1764051253000
    SourceEndpointEnableSsl

    string

    true
    StorageEncryptMethod

    string

    encrypted
    SourceEndpointPort

    string

    3306
    IncrementBackupRetentionPeriod

    string

    365
    IncrementDuplicationInfrequentAccessPeriod

    string

    365
    IncrementDuplicationArchivePeriod

    string

    365
    LogBackupRetentionPeriod

    string

    365
    LogDuplicationInfrequentAccessPeriod

    string

    365
    LogDuplicationArchivePeriod

    string

    365
    BackupGatewayIdentifier

    string

    TESTGATEWAY
    EnableMysqlPhysicalBackupBinLog

    boolean

    Examples

    Success response

    JSON format

    {
  "HttpStatusCode": 200,
  "PageNum": 1,
  "RequestId": "4F1888AC-1138-4995-B9FE-D2734F61C058",
  "ErrCode": "InvalidParameterValid",
  "Success": true,
  "ErrMessage": "The specified parameter %s value is not valid.     ",
  "TotalPages": 4,
  "TotalElements": 100,
  "PageSize": 30,
  "Items": {
    "BackupPlanDetail": [
      {
        "CrossRoleName": "test123",
        "SourceEndpointInstanceType": "rds",
        "BackupSetDownloadDir": "*/test/test123",
        "SourceEndpointIpPort": "100.*.*.10:33204",
        "CrossAliyunId": "2xxx7778xxxxxxxxxx",
        "DuplicationArchivePeriod": 365,
        "BackupPlanId": "dbstooi01eXXXX",
        "EndTimestampForRestore": 1554560477000,
        "BackupPlanStatus": "init",
        "BackupSetDownloadFullDataFormat": "SQL",
        "BackupRetentionPeriod": 365,
        "OSSBucketRegion": "cn-hangzhou",
        "SourceEndpointOracleSID": "test",
        "BackupStorageType": "system",
        "BackupMethod": "logical",
        "SourceEndpointRegion": "cn-hangzhou",
        "BackupPeriod": "Monday",
        "SourceEndpointDatabaseName": "test",
        "BackupSetDownloadGatewayId": 123123,
        "BackupPlanCreateTime": 1582527713000,
        "InstanceClass": "micro",
        "BackupSetDownloadTargetType": "agent",
        "DuplicationInfrequentAccessPeriod": 180,
        "BackupStartTime": "14:22",
        "ErrMessage": "  can not connect to oracle instance orcl with user dbs",
        "BackupObjects": "[     {         \\\"DBName\\\":\\\"database_name\\\",         \\\"SchemaName\\\":\\\"schema_name\\\",         \\\"TableIncludes\\\":[{             \\\"TableName\\\":\\\"table_name\\\"         }],         \\\"TableExcludes\\\":[{             \\\"TableName\\\":\\\"excluded_table_name\\\"         }]     } ]",
        "BeginTimestampForRestore": 1554560477000,
        "SourceEndpointInstanceID": "test",
        "OpenBackupSetAutoDownload": true,
        "BackupPlanName": "dbstooi01e****",
        "OSSBucketName": "dbs-backup-1857XXXXX489",
        "BackupGatewayId": 827362187368736,
        "SourceEndpointUserName": "test",
        "BackupSetDownloadIncrementDataFormat": "SQL",
        "EnableBackupLog": true,
        "ResourceGroupId": "rg-aekzecovzti****",
        "DatabaseType": "MySQL",
        "BackupPlanRegion": "cn-beijing",
        "SourceEndpointHost": "127.0.0.1",
        "InstanceChargeType": "PREPAY",
        "InstanceExpiredTimestamp": 1764051253000,
        "SourceEndpointEnableSsl": "true",
        "StorageEncryptMethod": "encrypted",
        "SourceEndpointPort": "3306",
        "IncrementBackupRetentionPeriod": "365",
        "IncrementDuplicationInfrequentAccessPeriod": "365",
        "IncrementDuplicationArchivePeriod": "365",
        "LogBackupRetentionPeriod": "365",
        "LogDuplicationInfrequentAccessPeriod": "365",
        "LogDuplicationArchivePeriod": "365",
        "BackupGatewayIdentifier": "TESTGATEWAY",
        "EnableMysqlPhysicalBackupBinLog": false
      }
    ]
  }
}

    Error codes

    HTTP status code

    Error code

    Error message

    Description
    403 Request.Forbidden Have no Permissions

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.