Updated on 2025-07-29 GMT+08:00

Querying Full Backups

Function

This API is used to query backups according to search criteria. Before calling this API:

URI

GET /v3/{project_id}/backups

Table 1 URI parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

Project ID of a tenant in a region.

To obtain this value, see Obtaining a Project ID.

Constraints

N/A

Range

The value can contain 32 characters. Only letters and digits are allowed.

Default Value

N/A

Table 2 Query parameters

Parameter

Mandatory

Type

Description

instance_id

No

String

Definition

Instance ID, which uniquely identifies an instance.

Constraints

N/A

Range

The value contains 36 characters with a suffix of in07. Only letters and digits are allowed.

Default Value

N/A

backup_id

No

String

Definition

Backup ID, which uniquely identifies a backup.

Constraints

N/A

Range

The value contains 36 characters with a suffix of br07. Only letters and digits are allowed.

Default Value

N/A

backup_type

No

String

Definition

Backup type.

Constraints

N/A

Range

  • auto: automated full backup
  • manual: manual full backup

Default Value

N/A

offset

No

String

Definition

Index offset. The query starts from the next piece of data indexed by this parameter.

Constraints

The value must be an integer and cannot be a negative number.

Range

≥0

Default Value

0

limit

No

String

Definition

Number of records to be queried.

Constraints

The value must be an integer and cannot be a negative number.

Range

1–100

Default Value

100

begin_time

No

String

Definition

Query start time in the "yyyy-mm-ddThh:mm:ssZ" format.

T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. For example, if the time zone offset is one hour, the value of Z is +0100.

Constraints

N/A

Range

The time is earlier than the current time.

Default Value

N/A

end_time

No

String

Definition

Query end time in the "yyyy-mm-ddThh:mm:ssZ" format.

T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. For example, if the time zone offset is one hour, the value of Z is +0100.

Constraints

N/A

Range

The time is earlier than the current time and later than the start time.

Default Value

N/A

name

No

String

Definition

Backup name.

Constraints

N/A

Range

The name must start with a letter and consist of 4 to 64 characters. Only letters (case-sensitive), digits, hyphens (-), and underscores (_) are allowed.

Default Value

N/A

instance_name

No

String

Definition

Instance name.

Constraints

N/A

Range

The name must start with a letter and consist of 4 to 64 characters. Only letters (case-sensitive), digits, hyphens (-), and underscores (_) are allowed.

Default Value

N/A

Request Parameters

Table 3 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

Definition

User token.

To obtain this value, call the IAM API for obtaining a user token.

The value of X-Subject-Token in the response header is the token value.

Constraints

N/A

Range

N/A

Default Value

N/A

X-Language

No

String

Definition

Request language type.

Constraints

N/A

Range

  • en-us
  • zh-cn

Default Value

en-us

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

backups

Array of backups objects

Definition

Backup information.

Range

N/A

total_count

Long

Definition

Total number of backup files.

Range

≥0

Table 5 backups

Parameter

Type

Description

id

String

Definition

Backup ID.

Range

The value contains 36 characters with a suffix of br07. Only letters and digits are allowed.

name

String

Definition

Backup name.

Range

The name must start with a letter and consist of 4 to 64 characters. Only letters (case-sensitive), digits, hyphens (-), and underscores (_) are allowed.

begin_time

String

Definition

Backup start time in the "yyyy-mm-ddThh:mm:ssZ" format.

T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. For example, if the time zone offset is one hour, the value of Z is +0100.

Range

N/A

end_time

String

Definition

Backup end time in the "yyyy-mm-ddThh:mm:ssZ" format.

T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. For example, if the time zone offset is one hour, the value of Z is +0100.

Range

N/A

status

String

Definition

Backup status.

Range

  • BUILDING: backup in progress
  • COMPLETED: backup completed
  • FAILED: backup failed
  • AVAILABLE: backup available

take_up_time

Integer

Definition

Backup duration in minutes.

Range

≥ 0

type

String

Definition

Backup type.

Range

  • auto: automated full backup
  • manual: manual full backup

size

Long

Definition

Backup size in MB.

Range

≥0

datastore

MysqlDatastore object

Definition

Database information.

instance_id

String

Definition

Instance ID, which uniquely identifies an instance.

Range

The value contains 36 characters with a suffix of in07. Only letters and digits are allowed.

instance_name

String

Definition

Instance name.

Range

The name must start with a letter and consist of 4 to 64 characters. Only letters (case-sensitive), digits, hyphens (-), and underscores (_) are allowed.

backup_level

String

Definition

Backup level. This parameter is returned when level-1 backup is enabled.

Range

  • 0: Backup being created or creation failed
  • 1: level-1 backup
  • 2: level-2 backup

description

String

Definition

Description of the backup file.

Range

N/A

Table 6 MysqlDatastore

Parameter

Type

Description

type

String

Definition

DB engine.

Range

gaussdb-mysql

version

String

Definition

DB version.

Range

8.0

Status code: 400

Table 7 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Status code: 500

Table 8 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Example Request

Querying automated backups generated from July 6, 2020 to July 16, 2020

GET https://{endpoint}/v3/97b026aa9cc4417888c14c84a1ad9860/backups?instance_id=43e4feaab48f11e89039fa163ebaa7e4br01&backup_id=c0c9f155c7b7423a9d30f0175998b63bbr01&backup_type=auto&offset=0&limit=10&begin_time=2020-07-06T10:41:14+0800&end_time=2020-07-16T10:41:14+0800

Example Response

Status code: 200

Success.

{
  "backups" : [ {
    "id" : "1fe4feaab48f11e6654hfa163eba87e4b66u",
    "name" : "TaurusDB-gauss-e747-20200705185048266",
    "begin_time" : "2018-08-06T12:41:14+0800",
    "end_time" : "2018-08-06T12:45:14+0800",
    "take_up_time" : 2,
    "status" : "COMPLETED",
    "type" : "auto",
    "size" : 2803,
    "datastore" : {
      "type" : "GaussDB(for MySQL)",
      "version" : "8.0"
    },
    "instance_id" : "43e4feaab48f11e89039fa163ebaa7e4br01",
    "instance_name" : "TaurusDB-gauss-e747",
    "backup_level" : "2"
  } ],
  "total_count" : 1
}

Status Code

For details, see Status Codes.

Error Code

For details, see Error Codes.