List Objects in a Bucket
Updated at：2025-11-03
API description
This API retrieves the list of object information in a specified bucket.
Notes
Delimiter can be used to implement folder logic:
- If the prefix is set to a folder name, all files starting with that prefix are listed, including all files and subfolders recursively within the folder.
- If the delimiter is set to "/", the response lists only the files in the folder. Subfolder names are returned in CommonPrefixes, but files within these subfolders are not displayed. For example, if a bucket contains three objects—fun/test.jpg, fun/movie/001.avi, and fun/movie/007.avi—and the prefix is set to "fun/", all three objects will be returned. If the delimiter "/" is also specified, only the file "fun/test.jpg" and the prefix "fun/movie/" will be returned.
Online debugging
Request URI
GET /v1/{bucketName}
| Parameter name | Parameter type | Required or not | Description | Example value | Parameter location |
|---|---|---|---|---|---|
| bucketName | String | Yes | BucketName | "bucketName_example" | Path |
| delimiter | String | No | The delimiter is primarily used to implement folder listing logic. When specified in a request, BOS truncates matching object names according to certain rules (from the prefix to the first delimiter), deduplicates the truncated strings, and returns them as CommonPrefixes data. The delimiter length is limited to one character. | "delimiter_example" | Query |
| marker | String | No | Objects are listed in alphabetical order, and returned from the first one after the marker | "marker_example" | Query |
| maxKeys | Integer | No | The maximum length of the returned object list is 1,000, defaulting to 1,000. If the specified value is greater than 1,000, it will be treated as 1,000 | 56 | Query |
| prefix | String | No | Key prefix, which must be included in the returned object keys with limits | "prefix_example" | Query |
Parameters of request body
Description of the data structure of request body fields
Response body parameters
Description of the data structure of response body fields
| Parameter name | Parameter type | Description | Example value |
|---|---|---|---|
| name | String | Bucket name | bucket |
| prefix | String | Query prefix | |
| delimiter | String | Query terminator | / |
| marker | String | Starting point of this query | |
| maxKeys | Integer | Maximum number of requests returned | 1000 |
| isTruncated | Boolean | Indicate whether the query is fully returned; false - all results are returned this time; true - not all results are returned this time | false |
| contents | List |
A list of objects returned |
Description of Contents field data structure
| Parameter name | Parameter type | Description | Example value |
|---|---|---|---|
| key | String | Object name | my-image1.jpg |
| lastModified | String | Last modification time of the object | 2009-10-12T17:51:30Z |
| eTag | String | The HTTP protocol entity tag of object | 0cce7caecc8309864f663d78d1293f98 |
| size | Integer | The size of the object content (in bytes) | 124231 |
| storageClass | String | Object storage classes: STANDARD_IA for infrequent access, COLD for cold storage, ARCHIVE for archive storage, and STANDARD for standard storage. | COLD |
| owner | Owner | User information of object uploader |
Description of Owner field data structure
| Parameter name | Parameter type | Description | Example value |
|---|---|---|---|
| id | String | User ID of object uploader | 168bf6fd8fa74d9789f35a283a1f15e2 |
| displayName | String | Name of object uploader | mtd |
Request example
JSON
1GET /v1/bucketName_example?delimiter=delimiter_example&marker=marker_example&maxKeys=56&prefix=prefix_example
2 <Common request headers>
3{ }Response example
JSON
1HTTP/1.1 200 OK
2 <Common response headers>
3{
4 "isTruncated" : false,
5 "maxKeys" : 1000,
6 "contents" : [ {
7 "owner" : {
8 "displayName" : "mtd",
9 "id" : "168bf6fd8fa74d9789f35a283a1f15e2"
10 },
11 "storageClass" : "COLD",
12 "size" : 124231,
13 "eTag" : "0cce7caecc8309864f663d78d1293f98",
14 "lastModified" : "2009-10-12T17:51:30Z",
15 "key" : "my-image1.jpg"
16 }, {
17 "owner" : {
18 "displayName" : "mtd",
19 "id" : "168bf6fd8fa74d9789f35a283a1f15e2"
20 },
21 "storageClass" : "COLD",
22 "size" : 124231,
23 "eTag" : "0cce7caecc8309864f663d78d1293f98",
24 "lastModified" : "2009-10-12T17:51:30Z",
25 "key" : "my-image1.jpg"
26 } ],
27 "prefix" : "prefix",
28 "delimiter" : "/",
29 "marker" : "marker",
30 "name" : "bucket"
31}Error code
Please refer to the general error codes