Get record IDs

This page shows you how to use the list operation to get the IDs of records in an index namespace. You can get the IDs of all records in a namespace or just the records with a common ID prefix.

ℹ️

Note

The list operation is supported only for serverless indexes and only via the REST API.

Get the IDs of all records in a namespace

To list the IDs of all records in the namespace of a serverless index, pass only the namespace parameter:

# The `GET` request below uses the unique endpoint for an index.
# See https://docs.pinecone.io/docs/get-index-endpoint for details.
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"

curl -X GET "https://$INDEX_HOST/vectors/list?namespace=ns1" \
  -H "Api-Key: $PINECONE_API_KEY"

# Response:
# {
#   "vectors": [
#     { "id": "doc1#chunk1" },
#     { "id": "doc1#chunk2" },
#     { "id": "doc1#chunk3" },
#     { "id": "doc1#chunk4" },
    ...
#   ],
#   "pagination": {
#     "next": "c2Vjb25kY2FsbA=="
#   },
#   "namespace": "ns1",
#   "usage": {
#     "readUnits": 1
#   }
# }

Get the IDs of records with a common prefix

When you have multiple records representing chunks of a single document, you can use a common ID prefix to reference the document. In such cases, you can use the list operation to list all of the records with the common prefix. For more details, see List all record IDs for a parent document.

Paginate through results

The /list operation returns up to 100 IDs at a time by default. If the limit parameter is passed, /list returns up to that number of IDs instead. Whenever there are additional IDs to return, the response also includes a pagination_token that you can use to get the next batch of IDs.

PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"

curl -X GET "https://$INDEX_HOST/vectors/list?namespace=ns1" \
  -H "Api-Key: $PINECONE_API_KEY"

# Response:
# {
#   "vectors": [
#     { "id": "doc1#chunk1" },
#     { "id": "doc1#chunk2" },
#     { "id": "doc1#chunk3" },
#     { "id": "doc1#chunk4" },
    ...
#   ],
#   "pagination": {
#     "next": "c2Vjb25kY2FsbA=="
#   },
#   "namespace": "ns1",
#   "usage": {
#     "readUnits": 1
#   }
# }

To get the next batch of IDs, add the pagination_token to the query string:

PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"

curl -X GET "https://$INDEX_HOST/vectors/list?namespace=ns1&paginationToken=c2Vjb25kY2FsbA%3D%3D" \
  -H "Api-Key: $PINECONE_API_KEY"

# Response:
# {
#   "vectors": [
#     { "id": "doc2#chunk1" },
#     { "id": "doc2#chunk1" },
#     { "id": "doc2#chunk1" },
#     { "id": "doc2#chunk1" },
    ...
#   ],
#   "pagination": {
#     "next": "mn23b4jB3Y9jpsS1"
#   },
#   "namespace": "ns1",
#   "usage": {
#     "readUnits": 1
#   }
# }

When there are no more IDs to return, the response does not includes a pagination_token:

PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"

curl -X GET "https://$INDEX_HOST/vectors/list?namespace=ns1&paginationToken=mn23b4jB3Y9jpsS1" \
  -H "Api-Key: $PINECONE_API_KEY"

# Response:
# {
#   "vectors": [
#     { "id": "doc3#chunk1" },
#     { "id": "doc5#chunk2" },
#     { "id": "doc5#chunk3" },
#     { "id": "doc5#chunk4" },
    ...
#   ],
#   "namespace": "ns1",
#   "usage": {
#     "readUnits": 1
#   }
# }