Help Center/ Document Database Service/ API Reference/ APIs V3.0 (Recommended)/ Backup and Restoration/ Querying the Backup List
Updated on 2025-10-24 GMT+08:00
View PDF

Querying the Backup List

Function

This API is used to query backups based on specified conditions.

URI

  • URI format

    GET /v3/{project_id}/backups

  • URI example

    https://dds.ap-southeast-1.myhuaweicloud.com/v3/97b026aa9cc4417888c14c84a1ad9860/backups?instance_id=c0c9f155c7b7423a9d30f0175998b63bin01&offset=0&limit=10&begin_time=2018-08-06 10:41:14&end_time=2018-08-16 10:41:14

Table 1 Parameter description

Name

Mandatory

Type

Description

project_id

Yes

string

Definition

Project ID of a tenant in a region. To obtain the project ID, see Obtaining a Project ID.

Constraints

N/A

Range

N/A

Default Value

N/A

instance_id

No

string

Definition

Instance ID, which can be obtained by calling the API described in Querying Instances and Details. If you do not have an instance, call the API described in Creating a DB Instance to create one.

Constraints

N/A

Range

N/A

Default Value

N/A

backup_id

No

string

Definition

The backup ID.

Constraints

If the backup ID belongs to an automated incremental backup, the instance ID must be specified.

Range

N/A

Default Value

N/A

backup_type

No

string

Definition

The backup type.

Constraints

When the value of this field is Incremental, the instance ID must be transferred.

Range

  • Auto: automated full backup
  • Manual: manual full backup
  • Incremental: automated incremental backup
  • If this parameter is not transferred, all full backups, including automated and manual full backups, are queried by default.

Default Value

N/A

offset

No

Integer

Definition

The index position. The query starts from the next instance creation time indexed by this parameter under a specified project. If offset is set to N, the resource query starts from the N+1 piece of data.

Constraints

N/A

Range

The value must be greater than or equal to 0.

Default Value

0: The query starts from the latest backup created.

limit

No

Integer

Definition

The maximum allowed number of backups to be queried.

Constraints

N/A

Range

1–100

Default Value

100 If this parameter is not transferred, the first 100 DB instances are queried by default.

begin_time

No

string

Definition

The start time of the query. The format is yyyy-mm-dd hh:mm:ss. The value is in UTC format.

Constraints

When end_time is not empty, begin_time is mandatory.

Range

N/A

Default Value

N/A

end_time

No

string

Definition

The end time of the query. The format is "yyyy-mm-dd hh:mm:ss". The value is in UTC format.

Constraints

When begin_time is not empty, end_time is mandatory.

Range

N/A

Default Value

N/A

mode

No

string

Definition

The DB instance mode.

Constraints

N/A

Range

  • Sharding
  • ReplicaSet
  • Single

Default Value

N/A

Request Parameters

Table 2 Request header parameters

Name

Mandatory

Type

Description

X-Auth-Token

Yes

string

Definition

User token obtained from IAM. For details, see Authentication.

Constraints

N/A

Range

N/A

Default Value

N/A

Response Parameters

Table 3 Response body parameters

Name

Mandatory

Type

Description

backups

Yes

Array of objects

Definition

The backup list. For more information, see Table 4.

Range

N/A

total_count

Yes

Integer

Definition

The total number of queried records.

Range

N/A
Table 4 Data structure description of the backups field

Name

Mandatory

Type

Description

id

Yes

String

Definition

The backup ID.

Range

N/A

name

Yes

String

Definition

The backup name.

Range

N/A

instance_id

Yes

String

Definition

The ID of the DB instance from which the backup was created. You can obtain the ID by calling the API for querying DB instances. If you do not have an instance, you can call the API used for creating an instance.

Range

N/A

instance_name

Yes

String

Definition

The name of the DB instance for which the backup is created.

Range

N/A

datastore

Yes

Object

Definition

The database version. For more information, see Table 5.

Range

N/A

type

Yes

String

Definition

The backup type.

Range

  • Auto: automated full backup
  • Manual: manual full backup
  • Incremental: automated incremental backup

begin_time

Yes

String

Definition

The backup start time. The format of the start time is yyyy-mm-dd hh:mm:ss. The value is in UTC format.

Range

N/A

end_time

Yes

String

Definition

The backup end time. The format of the end time is yyyy-mm-dd hh:mm:ss. The value is in UTC format.

Range

N/A

status

Yes

String

Definition

The backup status.

Range

  • BUILDING: Backup in progress
  • COMPLETED: Backup completed
  • FAILED: Backup failed
  • DISABLED: Backup being deleted

size

Yes

Long

Definition

The backup size in KB.

Range

N/A

description

Yes

String

Definition

The backup description.

Range

N/A
Table 5 Data structure description of the datastore field

Name

Mandatory

Type

Description

type

Yes

String

Definition

The DB engine.

Range

DDS-Community

version

Yes

String

Definition

The database version. Versions 5.0, 4.4, 4.2, 4.0, and 3.4 are supported.

Range

The value can be 5.0, 4.4, 4.2, 4.0, or 3.4.

Example Requests

GET https://{endpoint}/v3/054e292c9880d4992f02c0196d3ea468/backups?instance_id=a48e43ff268f4c0e879652d65e63d0fbin02

Example Responses

{ 
 "backups": [ 
    { 
        "id": "43e4feaab48f11e89039fa163ebaa7e4br01", 
        "name": "backup-test", 
        "instance_id": "43e4feaab48f11e89039fa163ebaa7e4br01", 
        "instance_name": "cluster-test",
        "datastore" : {  
               "type" : "DDS-Community",  
               "version" : "3.4" 
        }, 
        "type": "auto", 
        "begin_time": "2018-08-06 12:41:14", 
        "end_time": "2018-08-06 12:43:14",
        "status": "COMPLETED", 
        "size": 2803,
        "description": "backup description"
     } 
   ], 
   "total_count":1 
}

Status Code

For more information, see Status Code.

Error Code

For more information, see Error Code.

Parent topic: Backup and Restoration