ListSmartClusters-Object Storage Service(OSS)-阿里云帮助中心

Lists all SmartClusters in a specified Dataset. You can filter the results by cluster type and rule type. This operation supports pagination.

Usage notes

By default, an Alibaba Cloud account can list SmartClusters. If you call this operation as a RAM user, make sure that the RAM user has the oss:MetaQuery permission.
To use this operation, you must first configure a RouteRule for routing across multiple Datasets by calling the OpenMetaQuery operation.
This operation returns up to 200 items per call, with a default of 100. If more items are available, use the NextToken from the response to retrieve the next page of results.
For best results, specify the clusterType parameter. Otherwise, clusters of a certain type might not be included in the response.
By default, each item in the list includes all fields, including Rules. You do not need to call the GetSmartCluster operation to retrieve the details.

Request syntax

POST /?metaQuery&action=listSmartClusters&datasetName=DatasetName HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Request headers

This operation uses only common request headers. For more information, see Common Request Headers.

Request parameters

Parameter	Type	Required	Example	Description
datasetName	string	Yes	photos-2026	The Dataset that contains the SmartClusters to list.
maxResults	integer	No	50	The maximum number of items to return per request. Valid values: 1–200. Default: 100.
nextToken	string	No	MTIzNDU2	The pagination token from a previous response. Use this token to retrieve the next page of results. Omit this parameter for the first request.
clusterType	string	No	figure	The type of cluster to return. Valid values: figure: face clustering knowledge: keyword semantic clustering
ruleTypes	string	No	face	The type of rule to filter by. Separate multiple values with a comma (`,`). Valid values: face: A face clustering rule based on reference face images. keywords: A semantic clustering rule based on keywords.

Response headers

This operation uses only common response headers. For more information, see Common Response Headers.

Response parameters

Parameter	Type	Required	Example	Description
ListSmartClustersResponse	container	Yes	N/A	The root node of the response. Child nodes: `SmartClusters`, `NextToken`
SmartClusters	container	Yes	N/A	A container for the list of SmartClusters. Child node: `SmartCluster` Parent node: `ListSmartClustersResponse`
SmartCluster	container	No	N/A	A container for the details of a single SmartCluster. For the full set of fields, see SmartCluster data structure. Parent node: `SmartClusters`
NextToken	string	No	MTIzNDU2	The pagination token for the next page of results. This node is included only when there are more results to retrieve. Parent node: `ListSmartClustersResponse`

Examples

Request examples

Initial request:

POST /?metaQuery&action=listSmartClusters&datasetName=photos-2026&maxResults=50 HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 20 May 2026 13:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260520/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Request to retrieve the next page:

POST /?metaQuery&action=listSmartClusters&datasetName=photos-2026&maxResults=50&nextToken=MTIzNDU2 HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 20 May 2026 13:00:10 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260520/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Request to filter by cluster type and rule type (this example lists figure clusters that use the face rule):

POST /?metaQuery&action=listSmartClusters&datasetName=photos-2026&clusterType=figure&ruleTypes=face&maxResults=50 HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 20 May 2026 13:00:20 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260520/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Response example

HTTP/1.1 200 OK
x-oss-request-id: 64C8B6F4E7C5A3A8B9D6E7FA
Date: Wed, 20 May 2026 13:00:01 GMT
Content-Type: application/xml
Server: AliyunOSS

<?xml version="1.0" encoding="UTF-8"?>
<ListSmartClustersResponse>
  <SmartClusters>
    <SmartCluster>
      <ObjectId>cluster-abc123def456</ObjectId>
      <ClusterType>figure</ClusterType>
      <Name>face-cluster-alice</Name>
      <Description>Cluster faces matching Alice</Description>
      <Rules>
        <Rule>
          <RuleType>face</RuleType>
          <BaseURIs>oss://examplebucket/refs/alice.jpg</BaseURIs>
        </Rule>
      </Rules>
      <CreateTime>2026-05-20T11:00:00.000+08:00</CreateTime>
      <UpdateTime>2026-05-20T11:08:00.000+08:00</UpdateTime>
    </SmartCluster>
    <SmartCluster>
      <ObjectId>cluster-xyz789</ObjectId>
      <ClusterType>knowledge</ClusterType>
      <Name>keyword-cluster-vehicles</Name>
      <Rules>
        <Rule>
          <RuleType>keywords</RuleType>
          <Keywords>car</Keywords>
          <Keywords>truck</Keywords>
        </Rule>
      </Rules>
      <CreateTime>2026-05-20T12:00:00.000+08:00</CreateTime>
      <UpdateTime>2026-05-20T12:00:00.000+08:00</UpdateTime>
    </SmartCluster>
  </SmartClusters>
  <NextToken>MTIzNDU2</NextToken>
</ListSmartClustersResponse>