On OBS Console, when you open a bucket's object list page, objects are listed in lexicographical order by default. You can also sort objects by size or last modification time.
How It Works
In OBS object listing, all parameters (as defined by the API) work together based on the following logic to achieve precise and controllable data retrieval.
prefix defines the search scope. The system returns only object names that start with the specified prefix. As shown in Figure 1, when prefix is set to test/, the listing result includes objects whose names start with that prefix, such as test/a, test/b, and test/c.
Figure 1 How object listing works when prefix is specified 
marker specifies the starting point for listing objects. The system returns only objects whose names are lexicographically greater than the specified marker value, enabling resumable data transfer. As shown in Figure 2, when marker is set to test/b, objects such as test/c and logs/2026 that follow test/b are returned.
Figure 2 How object listing works when marker is specified 
delimiter, usually a slash (/), determines how folders are displayed.
- If delimiter is not specified, the system recursively expands all levels of subfolders.
- When prefix is not specified and only delimiter=/ is specified, the system groups the characters from the start of each object name up to the first slash (/) into a single CommonPrefixes entry, as shown in Figure 3. When both prefix=t and delimiter=/ are specified, the system groups the characters from the starting prefix t to the first slash (/) into one CommonPrefixes entry, as shown in Figure 4.
Figure 3 How object listing works when delimiter is specified 
Figure 4 How object listing works when both prefix and delimiter are specified 
max-keys is a hard limit that caps the number of items returned in a single request (maximum: 1,000). When the number of matching objects exceeds this limit, the response sets IsTruncated=true and provides NextMarker, which indicates where the next request should resume, thereby completing pagination. As shown in Figure 5, when max-keys is set to 2, the objects returned in a single request are test/a and test/b.
Figure 5 How object listing works when max-keys is specified 
For details about the definition, usage constraints, and response examples of each parameter, see Using SDKs.
Access Control
Only the bucket owner and users granted the obs:bucket:ListBucket (versioning disabled) or obs:bucket:ListBucketVersions (versioning enabled or suspended) permission can list objects. The permissions can be granted through IAM or bucket policies. For details, see Creating a Custom Policy or Creating a Custom Bucket Policy.
Constraints
- Listing objects by specifying a page number is not allowed.
- OBS does not support listing objects by upload time. You can search for objects by prefix.
- The size and last modification time in the object list only sort objects within the current page.
Ways to List Objects
You can use OBS Console, APIs, SDKs, or obsutil to list objects.
Using OBS Console
- In the navigation pane of OBS Console, choose Buckets.
- In the bucket list, click the desired bucket. The Objects page is displayed.
- View the listed objects. All objects in the bucket will be listed on different pages, with each page displaying 50 objects by default.
- (Optional) If versioning is enabled for the bucket, enable or disable Historical Versions above the object list to control whether to display historical versions of objects.
- Switch enabled: The object list shows both the current version and historical versions (including deleted objects).
- Switch disabled: The object list shows only the current version of each object.
Using the CLI Tool - obsutil
Command Line Structure
- Windows
obsutil ls obs://bucket[/prefix] [-s] [-fs] [-d] [-v] [-du] [-marker=xxx] [-versionIdMarker=xxx] [-bf=xxx] [-limit=1] [-format=default] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
- macOS or Linux
./obsutil ls obs://bucket[/prefix] [-s] [-fs] [-d] [-v] [-du] [-marker=xxx] [-versionIdMarker=xxx] [-bf=xxx] [-limit=1] [-format=default] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
Examples
- Example 2: In Windows, run obsutil ls obs://bucket-test2 to list all objects in the bucket.
obsutil ls obs://bucket-test2
Start at 2024-09-30 08:21:06.6300221 +0000 UTC
Listing objects .
Object list:
key LastModified Size StorageClass ETag
obs://bucket-test2/123 2022-03-29T09:17:51Z 0B standard "d41d8cd98f00b204e9800998ecf8427e"
obs://bucket-test2/1_2-3.txt 2022-03-29T09:17:51Z 0B standard "d41d8cd98f00b204e9800998ecf8427e"
obs://bucket-test2/1_2-3_33.txt 2022-03-29T09:17:51Z 200B standard "dcf204c11d791255adc63e61763c2426"
obs://bucket-test2/New text file.txt
2022-03-29T09:17:51Z 0B standard "d41d8cd98f00b204e9800998ecf8427e"
Total size of bucket: 200B
Folder number: 0
File number: 4 - Example 3: In Windows, run obsutil ls obs://bucket-test2/prefix to list objects whose name prefix is prefix in the bucket.
obsutil ls obs://bucket-test2/prefix
Start at 2024-09-30 08:24:36.7057148 +0000 UTC
Listing objects .
Object list:
key LastModified Size StorageClass ETag
obs://bucket-test2/prefix 2022-03-29T09:17:51Z 0B standard "d41d8cd98f00b204e9800998ecf8427e"
obs://bucket-test2/prefix2 2022-03-29T09:17:51Z 0B standard "d41d8cd98f00b204e9800998ecf8427e"
Total size of prefix [prefix]:: 0B
Folder number: 0
File number: 2
- For more examples, see Common Examples.
Parameter Description
| Parameter | Optional or Mandatory | Description |
| bucket | Mandatory | The bucket name |
| prefix | Optional | The prefix of the object name for listing objects NOTE: If this parameter is left blank, all objects in the bucket are listed. |
| s | Optional (additional parameter) | Displays simplified query result. NOTE: In the simplified format, the returned result contains only the object name. |
| d | Optional (additional parameter) | Lists only objects and subdirectories in the current directory, instead of recursively listing all objects and subdirectories. In big data scenarios, parallel file systems usually have deep directory levels and each directory has a large number of files. In such case, you are advised to use this parameter to limit the scope to list. NOTE: According to the naming conventions in OBS, a slash (/) is used as the directory separator. |
| v | Optional (additional parameter) | Lists versions of an object in a bucket. The result contains the latest version and historical versions (if any) of the object. |
| marker | Optional (additional parameter) | The start position for listing objects in a bucket. The objects following this start position are sorted in lexicographical order by object name. NOTE: For details about how to use this parameter, see Listing. |
| versionIdMarker | Optional (additional parameter). It must be used together with the v and marker parameters. | The start position for listing object versions in a bucket. The object versions following this start position are sorted in lexicographical order by object name. NOTE: If the value of versionIdMarker is not a version ID specified by marker, versionIdMarker is invalid. |
| bf | Optional (additional parameter) | The display formats of bytes in the listing result. The value can be: NOTE: If this parameter is not configured, the display format of bytes in the result is determined by the humanReadableFormat parameter in the configuration file. |
| du | Optional (additional parameter) | Quickly returns the total size of listed objects, without displaying detailed object information. This parameter can be used together with other parameters. NOTE: If there are too many objects listed, wait for a while. CAUTION: This parameter is only supported by obsutil 5.4.6 and later. |
| fs | Optional (additional parameter) | Whether the method of listing parallel file systems is applied. If you are listing parallel file systems, you are recommended to add this parameter. CAUTION: - With this method, the listing time required varies largely depending on the directory structures.
- After this parameter is enabled, marker and limit will be ignored. Then, the size of the bucket, parallel file system, or directory will be calculated.
- This parameter is only supported by obsutil 5.5.12 and later.
|
| limit | Optional (additional parameter) | The maximum number of objects that can be listed. If the value is less than or equal to 0, all objects are listed. If it is left blank, 1,000 objects are listed by default. NOTE: If there are a large number of objects in a bucket, you are advised to set this parameter to limit the number of objects to be listed each time. If not all objects are listed, marker and versionIdMarker of the next request will be returned in the result, which you can use to list the remaining objects. |
| format | Optional (additional parameter) | Prints a listing result in the user-defined format. Currently, the value can only be default, indicating that the listing result is displayed in one row. |
| bucket-cname | Optional (additional parameter) | The user-defined domain name bound to the bucket NOTE: This parameter is only supported by obsutil 5.7.9 and later. |
| config | Optional (additional parameter) | The user-defined configuration file for executing the current command. For details about parameters that can be configured, see Configuration Parameters. |
| e | Optional (additional parameter) | The endpoint |
| i | Optional (additional parameter) | The user's AK |
| k | Optional (additional parameter) | The user's SK |
| t | Optional (additional parameter) | The user's security token |
Response
Table 1 Object list and Versioning Object list response parameters (for common objects and object versions) | Field | Description |
| Key | The object name |
| VersionId | The object version ID. If versioning is enabled or suspended for a bucket, this parameter is displayed in the response when you list object versions in the bucket. |
| LastModified | The time when the last modification was made to the object |
| Size | The object size |
| StorageClass | The storage class of an object. The value can be: - standard: Standard storage class. It features low access latency and high throughput, and is suitable for storing frequently accessed data (multiple accesses per month) or data that is smaller than 1 MB.
- warm: Infrequent Access storage class. It is ideal for storing infrequently accessed data (fewer than 12 times a year), but when needed, the access has to be fast.
- cold: Archive storage class. It provides secure, durable, and inexpensive storage for rarely-accessed data (once a year).
- deep-archive: Deep Archive storage class. It is ideal for storing data that is hardly ever accessed (once every few years). This storage class costs less than the Archive storage class, but takes longer (usually several hours) to restore data.
|
| ETag | The ETag of an object, which is a Base64-encoded 128-bit MD5 digest. The ETag can be used to check whether the object content has changed, but it cannot be used as the unique identifier of the object. For example, if the ETag value is A when an object is uploaded, but this value has changed to B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the object content, rather than the object metadata. An uploaded object or copied object has a unique ETag. |
Best Practices
Performance optimization
- Page size: When network conditions are good, set the maximum number of objects displayed on a single page in a bucket to the upper limit (1,000 by default). This reduces round-trip requests and improves listing efficiency. However, you should evaluate the client's memory capacity to avoid memory issues caused by returning too much data at once.
- Directory caching: For objects that rarely change, cache the listing results to avoid repeated API calls, reducing request costs and latency.
Cost control
If you need to periodically generate a full object inventory, use bucket inventories. Bucket inventories are more cost-effective than real-time listing and support scheduled output, making them better suited for full analysis and auditing.
Logging and Monitoring
OBS provides logging and monitoring features that help you detect and handle object listing operations promptly. You can configure CTS to trace listObjects events or use Cloud Eye to monitor object-listing operations in a bucket (API ID: LIST.BUCKET.OBJECTS). You can also enable logging for the REST.GET.BUCKET operation so the system records detailed logs for auditing or further analysis. For details, see Using Logging to Record OBS Logs.
