Tenant Cloud Storage Cloud Object Storage API References Querying All Inventory Tasks

Querying All Inventory Tasks

Last Updated At: 2025-10-21 09:10:00

Description

The List Bucket Inventory Configurations API is used to query all inventory tasks in a bucket. You can configure up to 1,000 inventory tasks in a bucket.
This request supports pagination, returning up to 100 inventory tasks per page. Please check the value of the IsTruncated node in the request.

If IsTruncated is false, all inventory tasks in the bucket are listed.
If IsTruncated is true and there is a parameter value in the NextContinuationToken node, you can pass the value of the NextContinuationToken node to the continuation-token node to obtain information about inventory tasks on the next page.
For detailed inventory features, see Inventory Feature Overview.

Note

To call this API, ensure that you have the necessary permission for inventory tasks in the bucket. The bucket owner has this permission by default. If you do not have it, you should apply for it from the bucket owner first.

Authorization Description

In the authorization policy, action is set to cos:GetBucketInventory.

Request

Request Example

GET /?inventory HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: GMT Date
Authorization: Auth String

Description

Authorization: Auth String (For details, refer to Request Signature).

Request Parameters

The following table describes the request parameter format.

Parameter	Description	Type	Required
continuation-token	If IsTruncated in the COS response body is true and there is a parameter value in the NextContinuationToken node, you can use this parameter as the value of the continuation-token node to obtain information about inventory tasks on the next page. Default value: None	String	No

Request Header

This API only uses common request headers. For details, see Common Request Headers documentation.

Request Body

The request body of this request is empty.

Response

Response Headers

This API only returns the public response header. For details, see Common Response Headers documentation.

Response Body

The response body returns application/xml data. The following contains all the nodes:

<ListInventoryConfigurationResult>
    <InventoryConfiguration>
        <Id>list1</Id>
        <IsEnabled>True</IsEnabled>
        <Destination>
            <COSBucketDestination>
                <Format>CSV</Format>
                <AccountId>1250000000</AccountId>
                <Bucket>qcs::cos:city::examplebucket-1250000000</Bucket>
                <Prefix>list1</Prefix>
                <SSE-COS></SSE-COS>
            </COSBucketDestination>
        </Destination>
        <Schedule>
            <Frequency>Daily</Frequency>
        </Schedule>
        <Filter>
            <Prefix>myPrefix</Prefix>
        </Filter>
        <IncludedObjectVersions>All</IncludedObjectVersions>
        <OptionalFields>
            <Field>Size</Field>
            <Field>LastModifiedDate</Field>
            <Field>ETag</Field>
            <Field>StorageClass</Field>
            <Field>IsMultipartUpload</Field>
            <Field>ReplicationStatus</Field>
        </OptionalFields>
    </InventoryConfiguration>
    <InventoryConfiguration>
        <Id>list2</Id>
        <IsEnabled>True</IsEnabled>
        <Destination>
            <COSBucketDestination>
                <Format>CSV</Format>
                <AccountId>1250000000</AccountId>
                <Bucket>qcs::cos:city::examplebucket-1250000000</Bucket>
                <Prefix>list2</Prefix>
                <SSE-COS></SSE-COS>
            </COSBucketDestination>
        </Destination>
        <Schedule>
            <Frequency>Weekly</Frequency>
        </Schedule>
        <Filter>
            <Prefix>myPrefix2</Prefix>
        </Filter>
        <IncludedObjectVersions>All</IncludedObjectVersions>
        <OptionalFields>
            <Field>Size</Field>
            <Field>LastModifiedDate</Field>
            <Field>ETag</Field>
            <Field>StorageClass</Field>
        </OptionalFields>
    </InventoryConfiguration>
    <IsTruncated>false</IsTruncated>
    ------If ContinuationToken was provided in the request---
    <ContinuationToken>...</ContinuationToken>
    <IsTruncated>true</IsTruncated>
    <NextContinuationToken>1ueSDFASDF1Tr/XDAFdadEADadf2J/wm36Hy4vbOwM=</NextContinuationToken>
</ListInventoryConfigurationResult>

Specific node descriptions are as follows:

Node Name	Parent Node	Description	Type
ListInventoryConfigurationResult	No	Information about all inventory jobs of the bucket.	Container
InventoryConfiguration	ListInventoryConfigurationResult	Detailed information about the inventory task. For its XML structure, see GET Bucket Inventory.	Container
IsTruncated	ListInventoryConfigurationResult	Indicates whether all inventory task information is listed. If all inventory task information is displayed, it is false. Otherwise, it is true.	Boolean
ContinuationToken	ListInventoryConfigurationResult	Identifier of the current inventory list page, which can be understood as the page number. This identifier corresponds to the continuation-token parameter in the request.	String
NextContinuationToken	ListInventoryConfigurationResult	Identifier of the next inventory list page. If this parameter has a value, you can use this value as the continuation-token parameter and send a GET request to obtain information about inventory tasks on the next page.	String

Error Code

This API follows unified error response and error codes. For details, please refer to the Error Codes document.

Practical Case

Request

The following example queries the list1 inventory job configuration of the examplebucket-1250000000 bucket

GET /?inventory HTTP/1.1
Date: Mon, 28 Aug 2018 02:53:38 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&q-sign-time=1503895278;1503895638&q-key-time=1503895278;1503895638&q-header-list=host&q-url-param-list=inventory&q-signature=f77900be432072b16afd8222b4b349aabd837cb9
Host: examplebucket-1250000000.cos.city.yfm4.fsphere.cn

Response

After receiving the request, COS returns the following response, indicating that the inventory tasks list1 and list2 exist in the bucket.
Inventory task list1

The inventory task analyzes objects with the prefix myPrefix in the bucket examplebucket-1250000000 and all their versions.
The analysis frequency is once per day.
Analysis dimensions include Size, LastModifiedDate, StorageClass, ETag, IsMultipartUploaded, and ReplicationStatus.
The analysis results are stored as a CSV file in the bucket inventorybucket-1250000000. The file has the prefix list1 and is encrypted by using SSE-COS.
Inventory task list2
The inventory task analyzes objects with the prefix myPrefix2, and object tag {age:18} in the bucket examplebucket-1250000000 and all their versions.
The analysis frequency is once per day. Analysis dimensions include Size, LastModifiedDate, StorageClass, ETag, and Tag.
The analysis results are stored as a CSV file in the bucket inventorybucket-1250000000.
If there are 100 inventory tasks on a page and IsTruncated is true, COS returns NextContinuationToken, and the value of which can be used as the continuation-token parameter in the GET request to obtain information on the next page.

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 331
Date: Mon, 28 Aug 2018 02:53:39 GMT
x-cos-request-id: NTlhMzg1ZWVfMjQ4OGY3MGFfMWE1NF8****
<?xml version = "1.0" encoding = "UTF-8">
<ListInventoryConfigurationResult xmlns = "http://....">
    <InventoryConfiguration>
        <Id>list1</Id>
        <IsEnabled>True</IsEnabled>
        <Destination>
            <COSBucketDestination>
                <Format>CSV</Format>
                <AccountId>1250000000</AccountId>
                <Bucket>qcs::cos:city::inventorybucket-1250000000</Bucket>
                <Prefix>list1</Prefix>
                <SSE-COS></SSE-COS>
            </COSBucketDestination>
        </Destination>
        <Schedule>
            <Frequency>Daily</Frequency>
        </Schedule>
        <Filter>
            <Prefix>myPrefix</Prefix>
        </Filter>
        <IncludedObjectVersions>All</IncludedObjectVersions>
        <OptionalFields>
            <Field>Size</Field>
            <Field>LastModifiedDate</Field>
            <Field>ETag</Field>
            <Field>StorageClass</Field>
            <Field>IsMultipartUpload</Field>
            <Field>ReplicationStatus</Field>
        </OptionalFields>
    </InventoryConfiguration>
    <InventoryConfiguration>
        <Id>list2</Id>
        <IsEnabled>True</IsEnabled>
        <Destination>
            <COSBucketDestination>
                <Format>CSV</Format>
                <AccountId>1250000000</AccountId>
                <Bucket>qcs::cos:city::inventorybucket-1250000000</Bucket>
            </COSBucketDestination>
        </Destination>
        <Schedule>
            <Frequency>Weekly</Frequency>
        </Schedule>
        <Filter>
            <And>
                <Prefix>myPrefix2</Prefix>
                <Tag>
                    <Key>age</Key>
                    <Value>18</Value>
                </Tag>
            </And>
        </Filter>
        <IncludedObjectVersions>All</IncludedObjectVersions>
        <OptionalFields>
            <Field>Size</Field>
            <Field>LastModifiedDate</Field>
            <Field>StorageClass</Field>
            <Field>ETag</Field>
            <Field>Tag</Field>
        </OptionalFields>
    </InventoryConfiguration>
    <IsTruncated>false</IsTruncated>
    ------If ContinuationToken was provided in the request---
    <ContinuationToken>...</ContinuationToken>
    <IsTruncated>true</IsTruncated>
    <NextContinuationToken>1ueSDFASDF1Tr/XDAFdadEADadf2J/wm36Hy4vbOwM=</NextContinuationToken>
</ListInventoryConfigurationResult>