Help Center/ Object Storage Migration Service/ API Reference/ APIs V2 (Recommended)/ Operations on Buckets/ Listing Objects in a Bucket
Updated on 2025-12-04 GMT+08:00
View PDF

Listing Objects in a Bucket

Function

This API is used to list objects in a bucket.

Calling Method

For details, see Calling APIs.

URI

POST /v2/{project_id}/objectstorage/buckets/objects

Table 1 Path parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

The project ID.

Minimum length: 1 character

Maximum length: 1,024 characters

Request

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

The token used for IAM authentication. Ensure that the project ID in the token matches the project ID in the request URI.

Minimum length: 1 character

Maximum length: 16,384 characters
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

cloud_type

Yes

String

The cloud service provider.

AWS

Aliyun: Alibaba Cloud

Qiniu: Qiniu Cloud

QingCloud

Tencent: Tencent Cloud

Baidu: Baidu Cloud

KingsoftCloud

Azure: Microsoft Azure

UCloud

HuaweiCloud: Huawei Cloud

Google: Google Cloud

URLSource: URL data sources

HEC: HEC

Minimum length: 0 characters

Maximum length: 100 characters

file_path

Yes

String

The path of object files to be queried in the destination bucket, which must end with a slash (/).

Minimum length: 0 characters

Maximum length: 1,023 characters

ak

No

String

The AK for accessing the source bucket. Enter a maximum of 100 characters.

Minimum length: 0 characters

Maximum length: 100 characters

sk

No

String

The SK for accessing the source bucket. Enter a maximum of 100 characters.

Minimum length: 0 characters

Maximum length: 100 characters

connection_string

No

String

The connection string, which is used for Microsoft Azure Blob authentication.

Minimum length: 0 characters

Maximum length: 2,048 characters

json_auth_file

No

String

The file used for Google Cloud Storage authentication.

Minimum length: 0 characters

Maximum length: 65,535 characters

data_center

Yes

String

The data center region.

Minimum length: 0 characters

Maximum length: 100 characters

page_size

Yes

Integer

The page size.

Minimum value: 0

Maximum value: 100

behind_filename

Yes

String

The name of the last object on the current page (offset).

Minimum length: 0 characters

Maximum length: 1,024 characters

app_id

No

String

This parameter is returned when cloud_type is Tencent.

Minimum length: 0 characters

Maximum length: 255 characters

bucket_name

Yes

String

The bucket name.

Minimum length: 0 characters

Maximum length: 100 characters

Response

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

next_page

Boolean

Whether there is a next page.

next_marker

String

The marker required for querying the next page (object name at the end of the current page, offset)

Minimum length: 0 characters

Maximum length: 1,024 characters

records

Array of ShowBucketRecord objects

The queried object information.

Array length: 0 to 100
Table 5 ShowBucketRecord

Parameter

Type

Description

name

String

The object name.

Minimum length: 0 characters

Maximum length: 1,024 characters

size

String

The object size. If the object does not have the size attribute, "--" is returned.

Minimum length: 0 characters

Maximum length: 100 characters

Status code: 400

Table 6 Response body parameters

Parameter

Type

Description

error_msg

String

The error message.

error_code

String

The error code.

Example Request

This example lists objects in a specified bucket and returns the object information on multiple pages.

POST https://{endpoint}/v2/{project_id}/objectstorage/buckets/objects

{
  "page_size" : 100,
  "behind_filename" : "",
  "file_path" : "A/",
  "cloud_type" : "HuaweiCloud",
  "bucket_name" : "xxx",
  "ak" : "xxxxxak",
  "sk" : "xxxxxsk",
  "data_center" : "cn-north-x"
}

Example Response

Status code: 200

Object information returned

{
  "next_page" : false,
  "next_marker" : null,
  "records" : [ {
    "name" : "xxxx",
    "size" : "--"
  }, {
    "name" : "xxxx",
    "size" : "73.59 MB"
  } ]
}

Status Codes

Status Code

Description

200

Object information returned

400

Standard error response

Error Codes

For details, see Error Codes.

Parent Topic: Operations on Buckets