All Products
Search

This Product

    Data Management:CreateDownload

    Document Center

    Data Management:CreateDownload

    Last Updated:Dec 26, 2025

    Creates an Advanced Download task.

    Operation description

    Applicable engines

    • RDS MySQL (with cloud disks)

    • RDS PostgreSQL

    • PolarDB for MySQL

    • MongoDB

    Related documents

    For eligible instances, you can create an Advanced Download task for a point in time or a specific backup set. You can download the data to a URL or write it directly to your Object Storage Service (OSS) bucket for data analytics and offline archiving.

    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:CreateDownload

    create

    *DBInstance

    acs:rds:{#regionId}:{#accountId}:dbinstance/{#DbInstanceId}

    None

    None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example

    RegionCode

    string

    Yes

    The ID of the region where the instance resides. You can call the DescribeDBInstanceAttribute operation for an RDS instance or the DescribeDBClusterAttribute operation for a PolarDB cluster to query the region ID.

    cn-beijing

    InstanceName

    string

    Yes

    The instance ID.

    rm-wz994c1t1****

    BakSetType

    string

    No

    The type of the download task. Valid values:

    • full: downloads a full backup set.

    • pitr: downloads data at a specific point in time.

    full

    BakSetId

    string

    No

    The ID of the backup set. You can call the DescribeBackups operation for an RDS instance or the DescribeBackups operation for a PolarDB cluster to query this parameter.

    Note

    This parameter is required when BakSetType is set to full.

    146005****

    DownloadPointInTime

    string

    No

    The point in time to which you want to download data. Specify a UNIX timestamp of the long data type. Unit: milliseconds.

    Note

    This parameter is required when BakSetType is set to pitr.

    1661331864000

    BakSetSize

    string

    No

    The size of the full backup set. You can call the DescribeBackups operation for an RDS instance or the DescribeBackups operation for a PolarDB cluster to query the size. Unit: bytes.

    216****

    FormatType

    string

    No

    The format to which you want to convert the downloaded data. Valid values:

    • CSV

    • SQL

    • Parquet

    Note

    This parameter is required.

    CSV

    TargetType

    string

    No

    The destination type for the download. Valid values:

    • OSS

    • URL

    OSS

    TargetBucket

    string

    No

    The name of the OSS bucket.

    • This parameter is required when TargetType is set to OSS.

    • Make sure that your account has the AliyunDBSDefaultRole permission. For more information about how to grant permissions, see Grant permissions to a RAM role. You can also go to the console to grant permissions as prompted.

    test123

    TargetPath

    string

    No

    The destination path to which the data is downloaded.

    Note

    This parameter is required when TargetType is set to OSS.

    test_db/path

    TargetOssRegion

    string

    No

    The region where the OSS bucket resides.

    Note

    This parameter is required when TargetType is set to OSS.

    cn-beijing

    PrimaryKeyTypeOnly

    string

    No

    This field is required only for MongoDB instances. It indicates whether the primary key type in the database and table is unique. Valid values: true and false.

    false

    IsCluster

    string

    No

    This field is required only for MongoDB instances. It indicates whether the current instance is a sharded cluster. If the instance is a sharded cluster, set the value to true. Otherwise, set the value to false.

    false

    AdminDatabase

    string

    No

    This field is required only for MongoDB instances. It specifies the name of the authentication database. The default value is admin.

    admin

    UseZstd

    string

    No

    Indicates whether the zstd compression algorithm is used for the compressed package. The default value is false.

    false

    ClusterName

    string

    No

    This field is required only for MongoDB sharded clusters. It specifies the ID of the sharded cluster.

    dds-0xid8e5336******

    IsPhysical

    boolean

    No

    Response elements

    Element

    Type

    Description

    Example

    object

    The return values.

    RequestId

    string

    The request ID.

    A08F908D-2C35-583F-93C1-ED80753F****

    ErrCode

    string

    The error code.

    DBS.ParamIsInValid

    Success

    string

    Indicates whether the request was successful. Valid values:

    • true: The request was successful.

    • false: The request failed.

    true

    ErrMessage

    string

    The error message.

    formatType can not be empty

    Code

    string

    The status code.

    DBS.ParamIsInValid

    Message

    string

    The error message.

    formatType can not be empty

    Data

    object

    The returned data.

    BakSetId

    string

    The ID of the full backup set.

    146005****

    DownloadStatus

    string

    The status of the download task. Valid values:

    • initializing: The task is being initialized.

    • queueing: The task is in a queue.

    • running: The task is running.

    • failed: The task failed.

    • finished: The task is complete.

    • expired: The task has expired.

    Note

    A task whose destination is a URL expires three days after it is complete.

    initializing

    Progress

    string

    The number of downloaded tables/The total number of tables.

    Note

    If the task is in the preparation stage, 0/0 is returned.

    0/0

    BackupSetTime

    integer

    The point in time of the point-in-time download task. The value is a UNIX timestamp.

    1661373070000

    RegionCode

    string

    The region ID.

    cn-beijing

    TargetPath

    string

    The destination path for the download.

    Note

    This parameter is returned when TargetType is set to OSS.

    test_db/path

    DbList

    string

    If the download task is for specific databases and tables, this field returns information about these databases and tables.

    testdb

    ExportDataSize

    integer

    The volume of exported data. Unit: bytes.

    0

    ImportDataSize

    integer

    The volume of processed data. Unit: bytes.

    0

    GmtCreate

    integer

    The time when the task was created. The value is a UNIX timestamp.

    1661940917570

    TaskId

    string

    The ID of the download task.

    dt-qxnsfq5s****

    Format

    string

    The format to which the data is converted.

    CSV

    TargetType

    string

    The destination type for the download.

    URL

    Examples

    Success response

    JSON format

    {
  "RequestId": "A08F908D-2C35-583F-93C1-ED80753F****",
  "ErrCode": "DBS.ParamIsInValid",
  "Success": "true",
  "ErrMessage": "formatType can not be empty",
  "Code": "DBS.ParamIsInValid",
  "Message": "formatType can not be empty",
  "Data": {
    "BakSetId": "146005****",
    "DownloadStatus": "initializing",
    "Progress": "0/0",
    "BackupSetTime": 1661373070000,
    "RegionCode": "cn-beijing",
    "TargetPath": "test_db/path",
    "DbList": "testdb",
    "ExportDataSize": 0,
    "ImportDataSize": 0,
    "GmtCreate": 1661940917570,
    "TaskId": "dt-qxnsfq5s****",
    "Format": "CSV",
    "TargetType": "URL"
  }
}

    Error codes

    HTTP status code

    Error code

    Error message

    Description

    200

    DBS.DownloadTask.CannotFind

    Can not find download task.

    Can not find download task.

    200

    DBS.DownloadTask.JobAlreadyExist

    Job already submit in recent days, please check it.

    Job already submit in recent days, please check it.

    200

    DBS.DownloadTask.OnlyOneRunningOrFailedTask

    There can be only one running or failed task for the instance.

    The current instance can only have one running/failed task at the same time.

    200

    DBS.DownloadTask.OssForbid

    OSS is forbidden to access. Please check your OSS bucket.

    OSS is forbidden to access. Please check your OSS bucket.

    200

    DBS.DownloadTask.OssStorageTypeInvalid

    Unsupported bucket storage. Please make sure that your OSS bucket's storgae type is standard.

    Unsupported bucket storage. Please make sure that your OSS bucket's storgae type is standard.

    200

    Forbidden.InstanceNotFound

    instance not found

    The instance does not exist.

    403

    Request.Forbidden

    Have no Permissions

    403

    DBS.NoPermissionException

    Rejected by ValidationChecker.

    404

    DBS.NotExists

    data source do not existed.

    DBS.NotExists

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.