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

Using list to get record IDs and not the associated data is a cheap and fast way to check upserts.

The list operation is supported only for serverless indexes.

​
List 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:

from pinecone import Pinecone

pc = Pinecone(api_key='YOUR_API_KEY')
index = pc.Index("pinecone-index")

for ids in index.list(namespace='ns1'):
    print(ids)

# Response:
# ['doc1#chunk1', 'doc1#chunk2', 'doc1#chunk3']

​
List the IDs of records with a common prefix

ID prefixes enable you to query segments of content. Use the list operation to list all of the records with the common prefix. For more details, see Use ID prefixes.

​
Paginate through results

The list operation returns up to 100 IDs per page at a time by default. If the limit parameter is passed, list returns up to that number of IDs per page instead. For example, if limit=3, up to 3 IDs be returned per page. Whenever there are additional IDs to return, the response also includes a pagination_token for fetching the next page of IDs.

​
Implicit pagination

When using the Python client, list paginates automatically.

Python
from pinecone import Pinecone

pc = Pinecone(api_key='YOUR_API_KEY')
index = pc.Index("pinecone-index")

for ids in index.list(namespace='ns1'):
    print(ids)

# Response:
# ['doc1#chunk1', 'doc1#chunk2', 'doc1#chunk3']
# ['doc1#chunk4', 'doc1#chunk5', 'doc1#chunk6']
# ...

​
Manual pagination

To manually fetch each page of results yourself, first use the list_paginated() (Python), listPaginated (Node.js), or the REST API directly:

from pinecone import Pinecone

pc = Pinecone(api_key='YOUR_API_KEY')
index = pc.Index("pinecone-index")

namespace = 'ns1'

# For manual control over pagination
results = index.list_paginated(
    prefix='pref',
    limit=3,
    namespace='ns1'
)
print(results.namespace)
print([v.id for v in results.vectors])
print(results.pagination.next)
print(results.usage)

# Results:
# ['10103-0', '10103-1', '10103-10']
# eyJza2lwX3Bhc3QiOiIxMDEwMy0=
# {'read_units': 1}

Then, to get the next batch of IDs, use the returned pagination_token:

from pinecone import Pinecone

pc = Pinecone(api_key='YOUR_API_KEY')
index = pc.Index("pinecone-index")

namespace = 'ns1'

results = index.list_paginated(
    prefix='pref',
    limit=3,
    namespace='ns1',
    pagination_token='eyJza2lwX3Bhc3QiOiIxMDEwMy0='
)
print(results.namespace)
print([v.id for v in results.vectors])
print(results.pagination.next)
print(results.usage)

# Response:
# ['10103-0', '10103-1', '10103-10']
# xndlsInByZWZpeCI6IjEwMTAzIn0==
# {'read_units': 1}

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

from pinecone import Pinecone

pc = Pinecone(api_key='YOUR_API_KEY')
index = pc.Index("pinecone-index")

namespace = 'ns1'

results = index.list_paginated(
    prefix='10103',
    limit=3,
    pagination_token='xndlsInByZWZpeCI6IjEwMTAzIn0=='
)

print(results.namespace)
print([v.id for v in results.vectors])
print(results.pagination.next)
print(results.usage)

# Response:
# ['10103-4', '10103-5', '10103-6']
# {'read_units': 1}

Was this page helpful?

Delete dataGet an index endpoint