The ListVectors API lists all vector data in a vector index.
Permissions
An Alibaba Cloud account has all permissions by default. Resource Access Management (RAM) users or RAM roles under an Alibaba Cloud account have no permissions by default. The Alibaba Cloud account or an administrator must grant operation permissions through a RAM policy or a bucket policy.
API | Action | Description |
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 API uses only common request headers. For more information, see Common HTTP headers.
Request parameters
Name | Data type | Required | Example | Description |
indexName | string | Yes | vectorindex1 | The name of the index. |
maxResults | Number | No | 500 | The maximum number of results to return per request. The default value is 500. The maximum value is 1000. |
nextToken | string | No | CAESCG15aC-xxxxx | The query token. Set this parameter to the nextToken value returned from the previous API call. For the first call, leave this parameter empty. The parameter can be 1 to 2,048 bytes in length. |
returnData | Boolean | No | false | Specifies whether to return vector data. Valid values:
|
returnMetadata | Boolean | No | false | Specifies whether to return metadata. Valid values:
|
segmentCount | Number | No | 1 | For parallel ListVectors calls, specifies the degree of parallelism. The maximum value is 16. For serial calls, set this to 1. |
segmentIndex | Number | No | 0 | For parallel ListVectors calls, the segment index must be less than segmentCount. |
Response headers
This API uses only common response headers. For more information, see Common HTTP 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 listed. |
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 is returned only when returnData is true. Parent node: vectors |
metadata | object | N/A | The metadata. This is returned only when returnMetadata is true. Parent node: vectors |
Examples
Sample request
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
}Sample response
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": "CAESCG15aC2-xxxxx",
"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"
}
}
]
}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 in the request body is invalid. |
AccessDenied | 403 | Possible causes for this error:
|
NoSuchVectorIndex | 404 | The specified vector index does not exist. |
QpsLimitExceeded | 503 | Request rate limiting based on queries per second (QPS). |