Updated on 2025-08-20 GMT+08:00

Querying Details About All Snapshots

Function

This API is used to query details about all snapshots. Standard snapshots are available only in some regions. To check the supported regions, see the region information shown under "EVS Snapshots" in Function Overview.

Calling Method

For details, see Calling APIs.

URI

GET /v5/{project_id}/snapshots/detail

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

The project ID.

Constraints

N/A

Range

For details, see Obtaining a Project ID.

Default Value

N/A

Table 2 Query Parameters

Parameter

Mandatory

Type

Description

marker

No

String

Definition

The ID of the resource from which the pagination query starts. It is the ID of the last resource on the previous page.

Constraints

N/A

Range

N/A

Default Value

N/A

volume_id

No

String

Definition

The ID of the snapshot's source disk.

You can obtain it on the disk list page of the EVS console.

Constraints

N/A

Range

N/A

Default Value

N/A

availability_zone

No

String

Definition

The AZ of the snapshot's source disk.

Constraints

N/A

Range

N/A

Default Value

N/A

limit

No

String

Definition

The maximum number of query results that can be returned.

If the tenant has more than 50 snapshots in total, you are advised to use this parameter and set its value to 50 to improve the query efficiency. Examples:

Querying 1–50 snapshots: GET /v2/xxx/snapshots/detail?limit=50; Querying 51–100 snapshots: GET /v2/xxx/snapshots/detail?offset=50&limit=50

Constraints

N/A

Range

The value ranges from 1 to 1000, and the default value is 1000. The returned value cannot exceed this limit.

Default Value

N/A

name

No

String

Definition

The snapshot name.

You can obtain it on the snapshot list page of the EVS console.

Constraints

N/A

Range

It can contain a maximum of 255 characters.

Default Value

N/A

offset

No

String

Definition

The offset.

This parameter is used together with the limit parameter to query snapshots by page.

Assume that there are 30 snapshots. If you set offset to 11 and limit to 10, the query starts from the twelfth snapshot.

A maximum of 10 snapshots can be queried at a time.

Constraints

Must be used together with limit.

Range

N/A

Default Value

N/A

status

No

String

Definition

The snapshot status.

Constraints

N/A

Range

For details, see EVS Snapshot Status.

Default Value

N/A

sort_key

No

String

Definition

The keyword based on which the returned results are sorted.

Constraints

N/A

Range

The keywords include id, status, and created_at.

Default Value

created_at

sort_dir

No

String

Definition

The result sorting order. The default value is desc.

Constraints

N/A

Range

  • desc: descending order

  • asc: ascending order

Default Value

desc

id

No

String

Definition

The snapshot ID.

You can obtain it on the snapshot list page of the EVS console.

Constraints

N/A

Range

N/A

Default Value

N/A

ids

No

String

Definition

The snapshot IDs, which are separated with commas (,). The value is in the ids=id1,id2,...,idx format. Only snapshot information corresponding to valid IDs is returned. Invalid IDs will be ignored.

You can obtain the IDs on the snapshot list page of the EVS console.

Constraints

A maximum of 60 IDs can be specified at a time. If both id and ids are specified in the request, id will be ignored.

Range

N/A

Default Value

N/A

snapshot_type

No

String

Definition

The snapshot creation source.

Constraints

N/A

Range

N/A

Default Value

N/A

enterprise_project_id

No

String

Definition

The ID of the enterprise project to which the snapshot belongs.

For more information about enterprise projects and how to obtain enterprise project IDs, see Enterprise Management User Guide.

Constraints

N/A

Range

N/A

Default Value

N/A

tag_key

No

String

Definition

The snapshot tag key.

Constraints

N/A

Range

N/A

Default Value

N/A

tags

No

String

Definition

The snapshot's key-value pairs, for example, {"key1":"value1"}.

Constraints

N/A

Range

N/A

Default Value

N/A

snapshot_chain_id

No

String

Definition

The snapshot chain ID.

Constraints

N/A

Range

N/A

Default Value

N/A

snapshot_group_id

No

String

Definition

The snapshot consistency group ID.

Constraints

N/A

Range

N/A

Default Value

N/A

Request Parameters

Table 3 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

Definition

The user token.

It can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.

Constraints

N/A

Range

N/A

Default Value

N/A

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

snapshots

Array of SnapshotDetailV5 objects

Definition

The snapshot Information.

Range

N/A

Table 5 SnapshotDetailV5

Parameter

Type

Description

id

String

Definition

The snapshot ID.

Range

N/A

name

String

Definition

The snapshot name.

Snapshots whose names started with the autobk_snapshot_ prefix are automatically created by the system during backup creation. Such snapshots cannot be deleted or used to roll back data.

Range

N/A

description

String

Definition

The snapshot description.

Range

N/A

created_at

String

Definition

The time when the snapshot was created.

Time format: UTC YYYY-MM-DDTHH:MM:SS.XXXXXX

Range

N/A

updated_at

String

The time when the snapshot was updated.

volume_id

String

Definition

The ID of the snapshot's source disk.

Range

N/A

size

String

Definition

The snapshot size, in GiB.

Range

N/A

status

String

Definition

The snapshot status.

Range

For details, see EVS Snapshot Status.

project_id

String

The tenant ID. The tenant ID is the same as the project ID.

enterprise_project_id

String

The ID of the enterprise project to which the snapshot belongs.

encrypted

Boolean

Whether the snapshot is encrypted.

cmk_id

String

The ID of the key used by the snapshot's source disk.

category

String

The snapshot type, which can be standard or flash.

availability_zone

String

The AZ to which the snapshot belongs.

tags

Map<String,String>

The snapshot tags.

instant_access

Boolean

Definition

Whether Instant Snapshot Restore is enabled.

Range

true: enabled. Only SSD-backed disks support this function.

false: disabled. Snapshots with Instant Snapshot Restore disabled are standard snapshots.

retention_at

String

The snapshot retention duration.

instant_access_retention_at

String

Definition

The retention duration of Instant Snapshot Restore. After the retention duration ends, Instant Snapshot Restore is automatically disabled for snapshots.

Range

By default, the value of this parameter is the same as that of retention_at.

incremental

Boolean

Whether the snapshot is an incremental snapshot.

snapshot_type

String

Definition

The snapshot creation source.

Range

auto: automatically created

user: manually created

copy: replicated

progress

String

Definition

The snapshot creation progress, in percentage.

Range

N/A

encrypt_algorithm

String

The snapshot encryption algorithm.

snapshot_chains

Array of SnapshotChains objects

The snapshot chain to which the snapshot belongs.

snapshot_group_id

String

The ID of the snapshot consistency group to which the snapshot belongs.

Table 6 SnapshotChains

Parameter

Type

Description

id

String

Definition

The snapshot chain ID.

Range

N/A

availability_zone

String

Definition

The AZ of the disk that the snapshot chain belongs to.

Range

N/A

snapshot_count

Integer

The number of snapshots on the snapshot chain.

capacity

Integer

Definition

The snapshot chain storage usage.

Range

The value is greater than or equal to 0.

project_id

String

Definition

The project ID.

Range

N/A

volume_id

String

Definition

The ID of the disk that the snapshot chain belongs to.

Range

N/A

category

String

Definition

The snapshot chain type.

Range

N/A

created_at

String

Definition

The creation time.

Range

N/A

updated_at

String

Definition

The update time.

Range

N/A

Status code: 400

Table 7 Response body parameters

Parameter

Type

Description

error

Error object

Definition

The error information returned if an error occurs.

Range

N/A

Table 8 Error

Parameter

Type

Description

code

String

Definition

The error code returned if an error occurs.

Range

For details about the error codes and their meanings, see Error Codes.

message

String

Definition

The error message returned if an error occurs.

Range

N/A

Example Requests

GET https://{endpoint}/v5/{project_id}/snapshots/detail

Example Responses

Status code: 200

OK

  {
  "snapshots": [
    {
      "status": "available",
      "os-extended-snapshot-attributes:progress": "100%",
      "description": null,
      "created_at": "2013-06-19T07:15:29.000000",
      "metadata": {},
      "volume_id": "ae11e59c-bd56-434a-a00c-04757e1c066d",
      "os-extended-snapshot-attributes:project_id": "d6c277ba8820452e83df36f33c9fa561",
      "size": 5,
      "id": "6cd26877-3ca3-4f4e-ae2a-38cc3d6183fa",
      "name": "name_xx2-snap",
      "updated_at": null,
	  "category": "flash"
	  "enterprise_project_id": "0",
	  "encrypted": false,
	  "availability_zone": "az1.dc1",
	  "tags": {}
    },
    {
      "status": "available",
      "os-extended-snapshot-attributes:progress": "100%",
      "description": null,
      "created_at": "2013-06-19T09:08:08.000000",
      "metadata": {},
      "volume_id": "ae11e59c-bd56-434a-a00c-04757e1c066d",
      "os-extended-snapshot-attributes:project_id": "d6c277ba8820452e83df36f33c9fa561",
      "size": 5,
      "id": "b3253e26-5c37-48dd-8bf2-8795dd1e848f",
      "name": "name_xx2-snap",
      "updated_at": null,
	  "category": "flash"
	  "enterprise_project_id": "0",
	  "encrypted": false,
	  "availability_zone": "az1.dc1",
	  "tags": {}
    }
  ]
}

Status code: 400

Bad Request

{
  "error" : {
    "message" : "XXXX",
    "code" : "EVS.XXX"
  }
}

Status Codes

Status Code

Description

200

OK

400

Bad Request

Error Codes

See Error Codes.