Use the ListVectors operation to list vector data from a vector index - Object Storage Service

The ListVectors operation lists all vector data in a vector index.

Permissions

By default, Alibaba Cloud accounts have full permissions. By default, Resource Access Management (RAM) users and RAM roles under an Alibaba Cloud account have no permissions. An Alibaba Cloud account or an administrator must grant permissions using a RAM policy or a bucket policy.

API	Action	Description
ListVectors	`oss:ListVectors`	Lists vector data.

Request syntax

POST /?listVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou.oss-vectors.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
Content-type: application/json

{
   "indexName": "string",
   "maxResults": int,
   "nextToken": "string",
   "returnData": boolean,
   "returnMetadata": boolean,
   "segmentCount": int,
   "segmentIndex": int
}

Request headers

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

Request parameters

Name	Data type	Required	Example	Description
indexName	String	Yes	vectorindex1	The name of the index.
maxResults	value	No	500	The maximum number of results to return in each call. The default value is 500. The maximum value is 1000.
nextToken	String	No	CAESCG15aC1xxxxx	The query token. Set this parameter to the value of nextToken that is returned in the last call. For the first call, leave this parameter empty. The token can be 1 to 2,048 bytes in length.
returnData	Boolean	No	false	Specifies whether to return vector data. Valid values: true false (default)
returnMetadata	Boolean	No	false	Specifies whether to return metadata. Valid values: true false (default)
segmentCount	Value	No	1	For parallel ListVectors calls, specify the degree of parallelism. The maximum value is 16. For serial calls, set this parameter to 1.
segmentIndex	value	No	0	For parallel ListVectors calls, the index of the segment must be less than segmentCount.

Response headers

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

Response elements

Name	Data type	Example	Description
nextToken	String	CAESCG15aC2xxxxx	The token for the next page of results. If this parameter is empty, all results have been returned.
vectors	Array of objects	N/A	The list of returned vectors.
key	String	doc-001	The primary key of the vector. Parent node: vectors
data	Object	N/A	The vector data. This element is returned only when returnData is set to true. Parent node: vectors
metadata	Object	N/A	The metadata. This element is returned only when returnMetadata is set to true. Parent node: vectors

Examples

Request example

POST /?listVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou.oss-vectors.aliyuncs.com
Date: Thu, 17 Apr 2025 01:33:47 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218
Content-type: application/json

{
   "indexName": "vectorindex1",
   "maxResults": 10,
   "returnData": true,
   "returnMetadata": true
}

Response example

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 01:33:47 GMT
Connection: keep-alive
Server: AliyunOSS
Content-type: application/json

{
   "nextToken": "CAESCG15aC2xxxxx",
   "vectors": [ 
      { 
         "data": {
            "float32": [0.1, 0.2, 0.3, 0.4, 0.5]
         },
         "key": "doc-001",
         "metadata": {
             "category": ["technology", "ai"],
             "title": "Introduction to Vector Search"
         }
      },
      { 
         "data": {
            "float32": [0.2, 0.3, 0.4, 0.5, 0.6]
         },
         "key": "doc-002",
         "metadata": {
             "category": ["science"],
             "title": "Advanced Vector Operations"
         }
      }
   ]
}

SDK

The ListVectors operation is supported by the following software development kits (SDKs):

ossutil command-line interface

For the ossutil command that corresponds to the ListVectors operation, see list-vectors.

Error codes

Error code	HTTP status code	Description
VectorIndexParameterInvalid	400	The vector index parameter provided in the request is invalid.
MalformedJson	400	The JSON format of the request body is invalid.
AccessDenied	403	This error is returned for the following reasons: User authentication information is not included in the request. You do not have the required permissions for the operation.
NoSuchVectorIndex	404	The specified vector index does not exist.
QpsLimitExceeded	503	QPS (Queries Per Second) throttling limits the request rate.