Docs

Torch Object Storage

Basic configurations

Bucket inventory

You can use the bucket inventory feature to create inventory lists on a schedule that you define, for either a given bucket, or objects that share a prefix. You can also save these lists to a designated bucket. Inventory lists include object size, storage type, last update date, ETag, shard upload status, and encrypted state. This topic introduces the use cases and steps involved in using the feature.

Permissions required

By default, the owner of an account has full permissions. Identity and Access Management (IAM) users have no permissions by default. If an IAM user needs to perform any of the following operations, the account owner must grant the user the appropriate permissions using an IAM or bucket policy.

Create bucket inventory rules: tos:PutBucketInventory

View bucket inventory configurations: tos:GetBucketInventory

Delete bucket inventory rules: tos:DeleteBucketInventory

Before configuring a bucket inventory rule for the first time, you must use IAM to grant TOS permission to read all objects from the source bucket and write objects to the destination bucket. We recommend granting these permissions via the console. After successful authorization, IAM will automatically generate the TosArchiveTOSInventory role. You can log in to the IAM console to view this role.

warning

If you have configured bucket or IAM policies for your business, make sure that the following actions relating to the generation of bucket inventory lists are not explicitly denied, since doing so may cause the generation to fail: PutObject, CreateMultipartUpload, UploadPart, CompleteMultipartUpload, HeadObject, ListObjects, and SetObjectMeta.

By default, the TosArchiveTOSInventory role does not have permission to access Key Management Service (KMS) keys. If your bucket is encrypted with SSE-KMS, you must authorize the KMSCryptoUserAccess role before creating a bucket inventory rule. Otherwise, the generation will fail.

Notes

Category	Description
Number of bucket inventory rules	You can configure each bucket with up to ten bucket inventory rules.
Configuring bucket inventory rules	The inventory files can be generated and stored in different buckets, but these buckets must be in the same region and under the same account. Currently, the bucket inventory feature only supports creating lists of all objects or objects with a shared prefix within a given bucket. If you have created multiple inventory rules within a single bucket, the filtering scope of each rule must not overlap with that of any other rule. TOS automatically validates the filtering scope. If any overlaps are detected, the filtering scope of any existing rules must first be deleted or modified. Otherwise, creation of a new rule will fail.
Generation time	The first time you configure a bucket inventory rule, TOS will load the rules within 24 hours for FNS buckets and within 48 hours for HNS buckets. If there are fewer than 10 billion objects in a bucket, an inventory report is usually generated within 24 hours of the rule being loaded. If the number exceeds 10 billion, the generation time increases accordingly. tip If you need to execute an inventory rule for an FNS bucket immediately, see Execute a bucket inventory rule immediately under Other operations.
Object quantity	TOS supports daily or weekly exports of inventory files. We recommend setting the export frequency according to the number of objects. Number of objects < 10 billion: Daily or weekly exports are acceptable. Number of objects between 10 billion and 50 billion: Weekly exports are recommended. Number of objects > 50 billion: We recommend specifying object prefixes and exporting files in batches.
Editing a bucket inventory rule	If you edit a bucket inventory rule while it is being executed, the changes may appear in inventory files generated on or after the day the rule was edited. For this reason, we recommend using inventory files generated one day after the rule was modified.
Deleting a bucket inventory rule	If you delete a bucket inventory rule while it is being executed, some inventory files may remain in the directory and the generation of new files may stop.
Others	Exporting inventory files uses bandwidth. If your bucket has limited bandwidth, you can choose a different one to store your inventory files and avoid using the source bucket's bandwidth. No inventory file will be generated if the source bucket contains no files or if the configured inventory rules do not match any objects. During the export process, if objects are written to or updated in the bucket, the corresponding information may not be captured in the inventory file. To reduce storage costs, delete any unnecessary inventory files. Similarly, if you no longer require periodic inventory reports, you can delete the configured bucket inventory rules.

Billing notes

The bucket inventory feature is free. However, the following associated costs apply:

Billable item	Description
Storage cost	Generated inventory reports occupy storage space in the destination bucket, resulting in storage costs.
API requests	Configuring and retrieving inventory rules incur PUT and GET request costs. Writing inventory reports to the destination bucket incurs PUT request costs. Downloading and reading inventory reports incur GET request costs.
Outbound traffic over the public network	Downloading and reading inventory reports via the public endpoint incurs cost for outbound traffic over the public network.

For more information about billable items, see Billing overview.

Delete unnecessary inventory rules promptly to avoid unnecessary costs. For rules that need to be kept, set up lifecycle rules to automatically delete expired inventory reports.

Steps

In the left navigation pane, click Buckets.

In the top menu bar, select the project of the bucket you want to manage.

On the Buckets page, click the name of the bucket.

In the left navigation pane, select Basic configurations > Bucket inventory.

On the Bucket inventory page, click Create inventory.

On the Create bucket inventory page, set the following parameters:

Parameter	Description
Status	Select whether to activate the bucket inventory rule. The options are Enabled and Disabled.
Rule name	Specify the name of the bucket inventory rule. Rule names must: Be between 1 and 64 characters. Contain only numbers, hyphens (-), letters, underscores (_) and periods (.). Start and end with a number or letter.
Target bucket	Select the bucket in which the inventory file will be stored. warning If you have given all users permission to read and write the bucket, there is a risk of inventory files being leaked. The bucket must be in the same region as the source bucket. You cannot store inventory files in a bucket whose storage type is Archive, Cold Archive, or Deep Cold Archive.
Inventory report prefix	Specify the path prefix for storing inventory files in the destination bucket. If no prefix is defined, the default prefix tos_bucket_inventory will be used. Naming rules: Resource paths can contain Chinese characters, letters, numbers, and common symbols. Prefixes cannot start with a forward slash (/) or backslash (\). Consecutive forward slashes (/) are not allowed. .. cannot be used as a directory name.
Report output format	Use the following options to configure the inventory report output format: Compressed (Default): The inventory report is stored in the csv.gz format, which can reduce storage costs. Uncompressed: The inventory report is stored in the destination bucket in csv format.
Report export cycle	Select a cycle for report export. You can choose weekly, daily, or one-off. tip One-off report exports run only once. If you need to include a large number of objects, we recommend exporting the reports on a weekly basis.
Object version	Select the object versions to be exported. You can choose either Current version or All versions. tip This parameter only applies to buckets that have versioning enabled.
Filter settings	Configure the scope of objects and information to be included in inventory reports: Match by prefix: Use a prefix to filter objects. If no prefix is specified, inventory reports will include all objects in the bucket. Conditional filtering: Set conditions to filter objects. Supported conditions include Object size, Creation time, Modification time, Filter tag, Storage type, and Object type. List content information: Select the information to be included in inventory reports. The following options are available: Object size, Storage type, Intelligent Tiering: Access Layer, Last update date, ETag, Shard upload status, Encrypted state, CRC64, Replication state, Tag, Retention mode, and Retention expiration time. For more information, see fileSchema. tip Exporting last access time is currently in closed beta. Please contact your account manager for access.

Once you have finished configuring, click Create.

Inventory files

Path structure

Once a bucket inventory rule has been created, TOS will generate inventory list files based on the configured parameters. The following example illustrates the path structure of the inventory list files.

The parameters are described below:

Parameter	Description
destinationPrefix/	Specifies the path prefix for storing inventory reports in the destination bucket. If no prefix is defined, the default prefix tos_bucket_inventory will be used.
sourceBucketName/	Specifies the bucket from which the inventory file was generated.
inventoryId/	Specifies the name of the bucket inventory rule.
YYYY-MM-DDTHH-MMZ/	Specifies the time when scanning of the stored objects began during the generation of the inventory file, in UTC time and formatted as YYYY-MM-DDTHH-MMZ. tip Objects uploaded after this time will not be recorded in the inventory file. For bucket inventory rules created before July 15, 2025 and left unchanged, the timestamp format is YYYY-MM-DDTHH:MMZ. For more information, see Notice Regarding Adjusting TOS Bucket Inventory File Path.
files/	Specifies the directory in which the inventory file is stored. The default is files/. Inventory files are formatted as UUID.csv.gz, with the default format being .csv.gz. tip For more information, see fileSchema. If a substantial amount of data is exported, TOS automatically splits the inventory file into smaller segments to make processing easier. These files are named in sequential order, for example UUID_0, UUID_1 and so on. The files directory may contain non-unique UUIDs. For example, multiple files such as UUIDA_0, UUIDB_0 and UUIDB_1 may coexist.
manifest.json	A file that stores the metadata and other information of the inventory file. For more information, see manifest.json.
manifest.checksum	Specifies the MD5 checksum of the manifest.json file, for example 79b1e0cbe3af7fdf127b91af601b****.

manifest.json

The following example illustrates a manifest.json file, together with its description.

Parameter			Description
creationTimestamp			A Unix timestamp in seconds showing when scanning of the source bucket began.
sourceBucket			Specifies the bucket from which the inventory file was generated.
destinationBucket			Specifies the bucket in which the inventory file is stored.
fileFormat			Specifies the format of the inventory file. The default is CSV.
fileSchema			Specifies the object details included in the inventory file. For more information, see fileSchema.
version			Specifies the version number of the inventory file.
files	Key	Specifies the full path and filename of the inventory file.
		Size	Specifies the size of the inventory file in bytes.
		MD5checksum	Specifies the MD5 checksum of the inventory file.
		InventoriedRecord	Specifies the number of records in the inventory file.

fileSchema

Here is a screenshot of a fileSchema file.

FileSchema files do not include parameter names. The parameter names shown in the screenshot are for reference purposes only. The detailed descriptions of the parameters are as follows:

Parameter	Required	Description
BucketName	Yes	Specifies the name of the source bucket.
ObjKey	Yes	Specifies the name of the object. tip Object names are URL-encoded and must be decoded before use.
VersionId	Yes	Specifies the version ID of the object. tip This parameter only appears when versioning is enabled for the bucket and the Object version is set to All versions.
IsLatest	Yes	Specifies whether the object version is the latest version. The fields are described as follows: TRUE: The object is the latest version. FALSE: The object is a historical version. tip This parameter only appears when versioning is enabled for the bucket and the Object version is set to All versions.
IsDeleteMarker	Yes	Specifies whether the object version is a deletion mark. The fields are described as follows: TRUE: The object version is a deletion mark. FALSE: The object version is not a deletion mark. tip This parameter only appears when versioning is enabled for the bucket and the Object version is set to All versions.
Size	No	Specifies the size of the object in bytes.
ETag	No	Specifies the ETag of the object.
StorageClass	No	Specifies the storage type of the object. The fields are described as follows: STANDARD: Standard Storage IA: Infrequent Access Storage. INTELLIGENT_TIERING: Intelligent Tiering. ARCHIVE_FR: Flashback Archive. ARCHIVE: Archive. COLD_ARCHIVE: Cold Archive. DEEP_COLD_ARCHIVE: Deep Cold Archive.
IntelligentTieringAccessTier	No	Specifies the Intelligent Tiering access tier in which the object is stored. The fields are described as follows: Frequent access tier: FREQUENT Infrequent access tier: INFREQUENT Flashback archive tier: ARCHIVEFR
LastModifiedDate	No	Specifies the date on which the object was last modified. This is written in Unix timestamp format and is measured in seconds.
IsMultipartUploaded	No	Specifies whether the object was uploaded via multipart upload. The fields are described as follows: TRUE: The object was uploaded via multipart upload. FALSE: The object was not uploaded via multipart upload.
EncryptionStatus	No	Specifies whether the object is encrypted. The fields are described as follows: TRUE: The object is encrypted. FALSE: The object is not encrypted.
CRC64	No	Specifies the CRC64 value of the object, which is commonly used to verify data integrity. For more information, see Checking data integrity.
ReplicationStatus	No	Specifies the cross-region or same-region replication status of the object: If the object is the source for cross-region or same-region replication, the replication status values are: COMPLETE: Replication completed. PENDING: Replication in progress. FAILED: Replication failed. tip The feature that allows you to view the replication status of source objects is currently in closed beta. Contact your account manager for access. If the object is a target for cross-region or same-region replication, the value REPLICA is displayed to indicate that it is a replicated object. If the object is neither a source nor a target for replication, this field will be empty.
Tag	No	Specifies the tag(s) assigned to the object. The format is key1#value1;key2#value2;. tip Object tag keys and values are URL-encoded and must be decoded before use.
RetentionMode	No	Specifies the retention policy mode of the object. The fields are described as follows: COMPLIANCE: Compliance mode. NONE: No retention policy is set for the object.
RetainUntilTimestamp	No	Specifies the time at which the object's retention period expires. This is written in Unix timestamp format and is measured in seconds.
LastAccessTime	No	Specifies when the object was last accessed. tip The LastAccessTime parameter is currently in closed beta. Please contact your account manager for access. The last access time of objects is updated only when the Access monitor feature is enabled. To view the last access time, enable the Access monitor option on the Lifecycle page. For instructions, see Enable access monitor. TOS calculates the last access time of objects from the day access monitor is enabled. The access time of an object is updated only when at least 24 hours have passed since the last access request for that object. For example, downloading an object at 8:00 a.m. on January 1 records the access time as 8:00 a.m. on January 1. Any download requests made before 8:00 a.m. on January 2 will not update the access time. The access time will update only if you download the object again after 8:00 a.m. on January 2. For more information, see Which operations update an object's last access time?. The last access time of an object may not always be accurate. For example, if the server is busy, the last access time of some objects may not update after they are accessed. Therefore, do not rely on this information for data cleanup.

Other operations

Edit a bucket inventory rule: Click Edit in the Actions column of the rule you want to modify.

Delete a bucket inventory rule: Click Delete in the Actions column of the rule you want to remove, and confirm the deletion by clicking Delete in the box that appears.

Execute a bucket inventory rule immediately: Click Execute immediately in the Actions column of the rule you want to execute. Then, click OK in the box that appears to Create Instant Inventory.

tip

This operation is only available for FNS buckets.

Preview a bucket inventory rule: Click Preview List in the Actions column of the rule you want to check. Then, view the list directory names and list results in the box that appears. You can filter the list results by date. To view list results, click View List Results. The following information is available: Source bucket, Target bucket, Total number of objects, Total object size, Manifest file format, The version number of the manifest file, Inventory file, and Size. To download list results, click Download in the Actions column.

FAQ

How do I know if the inventory file has been generated?

The inventory file has not yet been generated – why is that?

What factors might affect the speed at which the inventory file is exported?

Last updated: 2026.10.09 14:42:34