Models

All public model types returned by SDK methods. Every model is an immutable msgspec.Struct subclass — fields are accessed as plain attributes (e.g. idx.name).

Index Models

class pinecone.models.indexes.index.IndexModel(*, name, metric, host, status, spec, vector_type='dense', dimension=None, deletion_protection='disabled', tags=None, embed=None, created_at=None)[source]

Bases: Struct

Response model for a Pinecone index.

Variables:

  • name (str) – The name of the index.

  • metric (str) – Distance metric used for similarity search (e.g. "cosine", "euclidean", "dotproduct").

  • host (str) – The hostname where this index is served.

  • status (pinecone.models.indexes.index.IndexStatus) – Current status of the index.

  • spec (pinecone.models.indexes.index.IndexSpec) – Deployment specification containing either serverless, pod, or byoc configuration.

  • vector_type (str) – Type of vectors stored (default: "dense").

  • dimension (int | None) – Dimensionality of vectors in the index, or None for indexes that infer dimension from the first upsert.

  • deletion_protection (str) – Whether deletion protection is enabled ("enabled" or "disabled").

  • tags (dict[str, str] | None) – User-defined key-value tags attached to the index, or None if no tags are set.

  • embed (pinecone.models.indexes.index.ModelIndexEmbed | None) – Embedding configuration for model-backed (integrated) indexes, populated for indexes created with integrated inference and None otherwise. See ModelIndexEmbed.

  • created_at (str | None) – ISO-8601 timestamp of when the index was created, or None if the server response did not include it. Stored as a string; parse with datetime.fromisoformat if you need a datetime object.

Parameters:
created_at: str | None
deletion_protection: str
dimension: int | None
embed: ModelIndexEmbed | None
host: str
metric: str
name: str
spec: IndexSpec
status: IndexStatus
tags: dict[str, str] | None
to_dict()[source]

Return a plain dict representation, recursively converting nested fields.

Returns:

Dictionary with all top-level fields, where nested spec, status, and embed structs are also converted to plain dicts recursively. Optional fields (dimension, tags, embed) that are None are included in the output with their None values.

Return type:

dict[str, Any]

Examples

>>> from pinecone.models.indexes.index import (
...     IndexModel, IndexSpec, IndexStatus, ServerlessSpecInfo
... )
>>> index = IndexModel(
...     name="my-index",
...     metric="cosine",
...     host="my-index-xyz.svc.pinecone.io",
...     status=IndexStatus(ready=True, state="Ready"),
...     spec=IndexSpec(serverless=ServerlessSpecInfo(cloud="aws", region="us-east-1")),
... )
>>> d = index.to_dict()
>>> d["name"]
'my-index'
>>> type(d["spec"])
<class 'dict'>
>>> d["spec"]["serverless"]
{'cloud': 'aws', 'region': 'us-east-1'}
vector_type: str
class pinecone.models.indexes.list.IndexList(indexes)[source]

Bases: object

Wrapper around a list of IndexModel with convenience methods.

Parameters:

indexes (list[IndexModel])

__init__(indexes)[source]
Parameters:

indexes (list[IndexModel])

Return type:

None

property indexes: list[IndexModel]

Return the list of indexes.

names()[source]

Return a list of index names.

Return type:

list[str]

to_dict()[source]

Return the list as a serializable dict.

Returns:

A dict with a "data" key containing a list of index dicts, each produced by IndexModel.to_dict().

Return type:

dict[str, Any]

Examples

>>> from pinecone import Pinecone
>>> pc = Pinecone(api_key="your-api-key")
>>> indexes = pc.list_indexes()
>>> indexes.to_dict()
{'data': [{'name': 'movie-recommendations', ...}, {'name': 'product-search', ...}]}
class pinecone.models.indexes.index.IndexSpec(*, serverless=None, pod=None, byoc=None)[source]

Bases: StructDictMixin, Struct

Deployment specification for an index.

Exactly one of serverless, pod, or byoc will be set.

Variables:
Parameters:
byoc: ByocSpecInfo | None
pod: PodSpecInfo | None
serverless: ServerlessSpecInfo | None
class pinecone.models.indexes.specs.ServerlessSpec(*, cloud, region, read_capacity=None, schema=None)[source]

Bases: StructDictMixin, Struct

Serverless index deployment spec.

Variables:

  • cloud (str) – Cloud provider (e.g. "aws", "gcp", "azure").

  • region (str) – Cloud region (e.g. "us-east-1", "eu-west-1").

  • read_capacity (dict[str, Any] | None) – Optional read capacity configuration (OnDemand or Dedicated), or None to use the default.

  • schema (dict[str, Any] | None) – Optional metadata schema configuration mapping field names to their config, or None for no schema.

Parameters:
asdict()[source]

Return a dict with spec data nested under a "serverless" key.

Return type:

dict[str, Any]

cloud: str
read_capacity: dict[str, Any] | None
region: str
schema: dict[str, Any] | None
class pinecone.models.indexes.specs.PodSpec(*, environment, pod_type='p1.x1', replicas=1, shards=1, pods=1, metadata_config=None, source_collection=None)[source]

Bases: StructDictMixin, Struct

Pod-based index deployment spec.

Variables:

  • environment (str) – Deployment environment (e.g. "us-east-1-aws").

  • pod_type (str) – Pod type and size (default: "p1.x1").

  • replicas (int) – Number of replicas (default: 1).

  • shards (int) – Number of shards (default: 1).

  • pods (int) – Total number of pods (default: 1).

  • metadata_config (dict[str, Any] | None) – Configuration for metadata indexing, or None to use the default configuration.

  • source_collection (str | None) – Name of a collection to create the index from, or None if creating an empty index.

Parameters:

  • environment (str)

  • pod_type (str)

  • replicas (int)

  • shards (int)

  • pods (int)

  • metadata_config (dict[str, Any] | None)

  • source_collection (str | None)

asdict()[source]

Return a dict with spec data nested under a "pod" key.

Return type:

dict[str, Any]

environment: str
metadata_config: dict[str, Any] | None
pod_type: str
pods: int
replicas: int
shards: int
source_collection: str | None
class pinecone.models.indexes.specs.ByocSpec(*, environment, read_capacity=None, schema=None)[source]

Bases: StructDictMixin, Struct

Bring-your-own-cloud index deployment spec.

Variables:

  • environment (str) – BYOC environment identifier (e.g. "aws-us-east-1-b921").

  • read_capacity (dict[str, Any] | None) – Optional read capacity configuration (OnDemand or Dedicated).

  • schema (dict[str, Any] | None) – Optional metadata schema configuration.

Parameters:
asdict()[source]

Return a dict with spec data nested under a "byoc" key.

Return type:

dict[str, Any]

environment: str
read_capacity: dict[str, Any] | None
schema: dict[str, Any] | None
class pinecone.models.indexes.specs.IntegratedSpec(*, cloud, region, embed)[source]

Bases: StructDictMixin, Struct

Integrated (model-backed) index deployment spec.

Wraps cloud/region and embed config into a single convenience object. On the wire the embed config is sent at the top level alongside the serverless spec — serialization handles the split.

Variables:
Parameters:
cloud: str
embed: EmbedConfig
region: str
class pinecone.models.indexes.specs.EmbedConfig(*, model, field_map, metric=None, read_parameters=None, write_parameters=None)[source]

Bases: Struct

Configuration for integrated (model-backed) embedding.

Variables:

  • model (str) – Name of the embedding model (e.g. "multilingual-e5-large").

  • field_map (dict[str, str]) – Maps document field names to embedding inputs (e.g. {"text": "my_text_field"}).

  • metric (str | None) – Similarity metric override, or None to use the model default.

  • read_parameters (dict[str, Any] | None) – Optional read-time model parameters.

  • write_parameters (dict[str, Any] | None) – Optional write-time model parameters.

Parameters:
field_map: dict[str, str]
metric: str | None
model: str
read_parameters: dict[str, Any] | None
to_dict()[source]

Serialize to a plain dictionary.

Read and write parameters default to empty dicts when not set.

Return type:

dict[str, Any]

write_parameters: dict[str, Any] | None
class pinecone.models.indexes.index.ServerlessSpecInfo(*, cloud, region, read_capacity=None, source_collection=None, schema=None)[source]

Bases: StructDictMixin, Struct

Response-side serverless deployment configuration.

Variables:

  • cloud (str) – Cloud provider (e.g. "aws", "gcp", "azure").

  • region (str) – Cloud region (e.g. "us-east-1").

  • read_capacity (dict[str, Any] | None) – Read capacity configuration (OnDemand or Dedicated), or None if the server response omits it. When set, contains a "mode" key plus mode-specific fields.

  • source_collection (str | None) – Source collection name if the index was created from a collection, or None.

  • schema (dict[str, Any] | None) – Metadata indexing schema, or None if all metadata fields are indexed (the default).

Parameters:
cloud: str
read_capacity: dict[str, Any] | None
region: str
schema: dict[str, Any] | None
source_collection: str | None
class pinecone.models.indexes.index.PodSpecInfo(*, environment, pod_type, replicas, shards, pods, metadata_config=None, source_collection=None)[source]

Bases: StructDictMixin, Struct

Response-side pod deployment configuration.

Variables:

  • environment (str) – Deployment environment (e.g. "us-east1-gcp").

  • pod_type (str) – Pod type (e.g. "p1.x1").

  • replicas (int) – Number of replicas.

  • shards (int) – Number of shards.

  • pods (int) – Total number of pods.

  • metadata_config (dict[str, list[str]] | None) – Metadata indexing configuration, or None.

  • source_collection (str | None) – Source collection name, or None.

Parameters:
environment: str
metadata_config: dict[str, list[str]] | None
pod_type: str
pods: int
replicas: int
shards: int
source_collection: str | None
class pinecone.models.indexes.index.ByocSpecInfo(*, environment, read_capacity=None)[source]

Bases: StructDictMixin, Struct

Response-side BYOC (bring your own cloud) deployment configuration.

Variables:

  • environment (str) – BYOC environment identifier.

  • read_capacity (dict[str, Any] | None) – Read capacity configuration, or None.

Parameters:
environment: str
read_capacity: dict[str, Any] | None
class pinecone.models.indexes.index.ModelIndexEmbed(*, model, metric=None, dimension=None, vector_type=None, field_map=None, read_parameters=None, write_parameters=None)[source]

Bases: StructDictMixin, Struct

Embedding configuration for a model-backed (integrated) index.

Variables:

  • model (str) – The name of the embedding model used by this index.

  • metric (str | None) – Distance metric, or None if inferred from the model.

  • dimension (int | None) – Vector dimension, or None if inferred from the model.

  • vector_type (str | None) – Vector type ("dense" or "sparse"), or None.

  • field_map (dict[str, str] | None) – Mapping of document field names to embedding input roles, or None.

  • read_parameters (dict[str, Any] | None) – Model-specific parameters for read (query) operations, or None.

  • write_parameters (dict[str, Any] | None) – Model-specific parameters for write (upsert) operations, or None.

Parameters:
dimension: int | None
field_map: dict[str, str] | None
metric: str | None
model: str
read_parameters: dict[str, Any] | None
vector_type: str | None
write_parameters: dict[str, Any] | None

Vector Models

class pinecone.models.vectors.vector.Vector(id, values=<factory>, sparse_values=None, metadata=None)[source]

Bases: DictLikeStruct, Struct

A stored vector with optional sparse values and metadata.

Variables:

  • id (str) – Unique identifier for the vector.

  • values (list[float]) – Dense vector values as a list of floats.

  • sparse_values (SparseValues | None) – Sparse vector component, or None if the vector has no sparse values.

  • metadata (dict[str, Any] | None) – User-defined metadata key-value pairs, or None if no metadata is attached.

Parameters:
static from_dict(vector_dict)[source]

Construct a Vector from a plain dict representation.

Parameters:

vector_dict (dict[str, Any])

Return type:

Vector

id: str
metadata: dict[str, Any] | None
sparse_values: SparseValues | None
values: list[float]
class pinecone.models.vectors.sparse.SparseValues(indices, values)[source]

Bases: DictLikeStruct, Struct

Sparse vector representation with indices and values.

Variables:

  • indices (list[int]) – Non-zero dimension indices of the sparse vector.

  • values (list[float]) – Values corresponding to each index in indices.

Parameters:
static from_dict(sparse_values_dict)[source]

Construct a SparseValues from a plain dict representation.

Parameters:

sparse_values_dict (dict[str, Any])

Return type:

SparseValues

indices: list[int]
values: list[float]
class pinecone.models.vectors.responses.QueryResponse(*, matches=<factory>, namespace='', usage=None, response_info=None)[source]

Bases: DictLikeStruct, Struct

Response from a query operation.

Variables:

  • matches (list[ScoredVector]) – List of scored vectors as returned by the API (ordered from most similar to least similar).

  • namespace (str) – Namespace that was queried. Defaults to "" (the default namespace).

  • usage (Usage | None) – Read unit usage for this query, or None if not reported.

  • response_info (ResponseInfo | None) – HTTP response metadata (request ID, LSN values), or None if not populated.

Parameters:

  • matches (list[ScoredVector])

  • namespace (str | None)

  • usage (Usage | None)

  • response_info (ResponseInfo | None)

matches: list[ScoredVector]
namespace: str | None
response_info: ResponseInfo | None
usage: Usage | None
class pinecone.models.vectors.responses.FetchResponse(*, vectors=<factory>, namespace='', usage=None, response_info=None)[source]

Bases: DictLikeStruct, Struct

Response from a fetch operation.

Variables:

  • vectors (dict[str, Vector]) – Mapping of vector ID to Vector for each fetched vector.

  • namespace (str) – Namespace the vectors were fetched from.

  • usage (Usage | None) – Read unit usage for this fetch, or None if not reported.

  • response_info (ResponseInfo | None) – HTTP response metadata (request ID, LSN values), or None if not populated.

Parameters:
namespace: str
response_info: ResponseInfo | None
usage: Usage | None
vectors: dict[str, Vector]
class pinecone.models.vectors.responses.FetchByMetadataResponse(*, vectors=<factory>, namespace='', usage=None, pagination=None, response_info=None)[source]

Bases: DictLikeStruct, Struct

Response from a fetch-by-metadata operation.

Variables:

  • vectors (dict[str, Vector]) – Mapping of vector ID to Vector for each fetched vector.

  • namespace (str) – Namespace the vectors were fetched from.

  • usage (Usage | None) – Read unit usage, or None if not reported.

  • pagination (Pagination | None) – Pagination token for the next page, or None if this is the last page.

  • response_info (ResponseInfo | None) – HTTP response metadata (request ID, LSN values), or None if not populated.

Parameters:
namespace: str
pagination: Pagination | None
response_info: ResponseInfo | None
usage: Usage | None
vectors: dict[str, Vector]
class pinecone.models.vectors.responses.UpsertResponse(*, upserted_count, response_info=None, total_item_count=0, failed_item_count=0, total_batch_count=0, successful_batch_count=0, failed_batch_count=0, errors=<factory>)[source]

Bases: DictLikeStruct, Struct

Response from an upsert operation.

Variables:

  • upserted_count (int) – Number of vectors successfully upserted. For non-batched calls this equals total_item_count.

  • response_info (ResponseInfo | None) – HTTP response metadata (request ID, LSN values), or None if not populated.

  • total_item_count (int) – Total number of items submitted. Defaults to 0 for non-batched calls.

  • failed_item_count (int) – Number of items in failed batches. Defaults to 0.

  • total_batch_count (int) – Total number of batches executed. Defaults to 0 for non-batched calls.

  • successful_batch_count (int) – Number of batches that succeeded. Defaults to 0.

  • failed_batch_count (int) – Number of batches that failed. Defaults to 0.

  • errors (list[BatchError]) – Per-batch error details. Empty for non-batched calls or when all batches succeed.

Parameters:

  • upserted_count (int)

  • response_info (ResponseInfo | None)

  • total_item_count (int)

  • failed_item_count (int)

  • total_batch_count (int)

  • successful_batch_count (int)

  • failed_batch_count (int)

  • errors (list[BatchError])

For non-batched calls, all counter fields default to 0 and errors defaults to []; the only meaningful field is upserted_count.

For batched calls (batch_size set on the upsert method), the caller can use the partial-success API:

>>> response = idx.upsert(vectors=[...], batch_size=100)
>>> response.upserted_count
900
>>> response.has_errors
True
>>> response.failed_item_count
100
>>> retry = idx.upsert(vectors=response.failed_items, batch_size=100)
property error_count: int

Alias for failed_item_count (matches BatchResult).

errors: list[BatchError]
failed_batch_count: int
failed_item_count: int
property failed_items: list[dict[str, Any]]

All items from failed batches, flattened for retry.

property has_errors: bool

Whether any batches failed.

response_info: ResponseInfo | None
property success_count: int

Alias for upserted_count (matches BatchResult.successful_item_count).

successful_batch_count: int
property successful_item_count: int

Alias for upserted_count (matches BatchResult field name).

total_batch_count: int
total_item_count: int
upserted_count: int
class pinecone.models.vectors.responses.UpdateResponse(*, matched_records=None, response_info=None)[source]

Bases: DictLikeStruct, Struct

Response from an update operation.

Variables:

  • matched_records (int | None) – Number of records matched by the update, or None if not reported by the server.

  • response_info (ResponseInfo | None) – HTTP response metadata (request ID, LSN values), or None if not populated.

Parameters:
matched_records: int | None
response_info: ResponseInfo | None
class pinecone.models.vectors.responses.ListResponse(*, vectors=<factory>, pagination=None, namespace='', usage=None, response_info=None)[source]

Bases: StructDictMixin, Struct

Response from a list vectors operation.

Variables:

  • vectors (list[ListItem]) – List of vector ID entries in this page.

  • pagination (Pagination | None) – Pagination token for fetching the next page, or None if there are no more results.

  • namespace (str) – Namespace the vectors were listed from.

  • usage (Usage | None) – Read unit usage for this list call, or None if not reported.

  • response_info (ResponseInfo | None) – HTTP response metadata (request ID, LSN values), or None if not populated.

Parameters:

  • vectors (list[ListItem])

  • pagination (Pagination | None)

  • namespace (str)

  • usage (Usage | None)

  • response_info (ResponseInfo | None)

namespace: str
pagination: Pagination | None
response_info: ResponseInfo | None
usage: Usage | None
vectors: list[ListItem]
class pinecone.models.vectors.responses.DescribeIndexStatsResponse(*, namespaces=<factory>, dimension=None, index_fullness=0.0, total_vector_count=0, metric=None, vector_type=None, memory_fullness=None, storage_fullness=None, response_info=None)[source]

Bases: StructDictMixin, Struct

Response from a describe index stats operation.

Variables:

  • namespaces (dict[str, NamespaceSummary]) – Mapping of namespace name to NamespaceSummary for each namespace in the index.

  • dimension (int | None) – Dimensionality of vectors in the index, or None if not yet determined.

  • index_fullness (float) – Fraction of the index capacity used, from 0.0 to 1.0.

  • total_vector_count (int) – Total number of vectors across all namespaces.

  • metric (str | None) – Distance metric of the index (e.g. "cosine"), or None if not reported.

  • vector_type (str | None) – Type of vectors stored (e.g. "dense"), or None if not reported.

  • memory_fullness (float | None) – Fraction of memory capacity used, or None if not reported.

  • storage_fullness (float | None) – Fraction of storage capacity used, or None if not reported.

  • response_info (ResponseInfo | None) – HTTP response metadata (request ID, LSN values), or None if not populated.

Parameters:

  • namespaces (dict[str, NamespaceSummary])

  • dimension (int | None)

  • index_fullness (float)

  • total_vector_count (int)

  • metric (str | None)

  • vector_type (str | None)

  • memory_fullness (float | None)

  • storage_fullness (float | None)

  • response_info (ResponseInfo | None)

dimension: int | None
index_fullness: float
memory_fullness: float | None
metric: str | None
namespaces: dict[str, NamespaceSummary]
response_info: ResponseInfo | None
storage_fullness: float | None
total_vector_count: int
vector_type: str | None
class pinecone.models.vectors.responses.UpsertRecordsResponse(*, record_count, response_info=None)[source]

Bases: StructDictMixin, Struct

Response from an upsert_records operation.

Variables:

  • record_count (int) – Number of records submitted by the caller. This is a client-side count, not a server-confirmed count.

  • response_info (ResponseInfo | None) – HTTP response metadata (request ID, LSN values), or None if not populated.

Parameters:
record_count: int
response_info: ResponseInfo | None
class pinecone.models.response_info.BatchResponseInfo(*, lsn_reconciled=None, lsn_committed=None)[source]

Bases: StructDictMixin, Struct

Aggregate durability signal across a multi-request batch operation.

A batch operation fans out into N underlying HTTP requests, each with its own response headers. BatchResponseInfo collapses the reconciliation signal across those requests into a single object that mirrors the read-your-writes API surface of ResponseInfo.

Does not carry raw_headers or request_id — there is no single source HTTP response to point at. Individual sub-request diagnostics are available via BatchError.error for failed batches.

Variables:

  • lsn_reconciled (int | None) – Maximum lsn_reconciled observed across successful sub-batches, or None when no successful batch reported this header. Use is_reconciled() for durability checks.

  • lsn_committed (int | None) – Maximum lsn_committed observed across successful sub-batches, or None when no successful batch reported this header.

Parameters:

  • lsn_reconciled (int | None)

  • lsn_committed (int | None)

Examples

from pinecone import Pinecone

pc = Pinecone(api_key="your-api-key")
index = pc.preview.index(name="articles-en-preview")
documents = [
    {"_id": f"article-{i:05d}", "content": f"Article {i}"}
    for i in range(500)
]
result = index.documents.batch_upsert(
    namespace="articles-en",
    documents=documents,
)
if result.response_info is not None:
    target_lsn = result.response_info.lsn_committed
    if result.response_info.is_reconciled(target_lsn):
        pass  # all writes durable through target_lsn
is_reconciled(target)[source]

Return True when the aggregate reconciled LSN meets or exceeds target.

Parameters:

target (int)

Return type:

bool

lsn_committed: int | None
lsn_reconciled: int | None
class pinecone.models.response_info.ResponseInfo(*, raw_headers=<factory>)[source]

Bases: StructDictMixin, Struct

HTTP response metadata carrier.

Stores every HTTP response header returned by the server (keys lowercased) plus typed convenience properties for the headers the SDK promotes to first-class fields.

Variables:

  • raw_headers (dict[str, str]) – All HTTP response headers, keys normalized to lowercase. Defaults to an empty dict. Use this to read any header the server returns, including headers not surfaced by the typed properties below. Prefer the typed properties when available — wire header names may change, but property semantics are stable.

  • request_id (str | None) – Server-assigned request identifier read from x-pinecone-request-id, or None if not present.

  • lsn_reconciled (int | None) – Log sequence number indicating how far the index has reconciled, parsed from x-pinecone-lsn-reconciled. None when absent or when the header value is not a valid integer.

  • lsn_committed (int | None) – Log sequence number of the last committed write, parsed from x-pinecone-lsn-committed. None when absent or non-integer.

Parameters:

raw_headers (dict[str, str])

is_reconciled(target)[source]

Return True when the reconciled LSN meets or exceeds target.

Use this for read-your-writes consistency checks: pass the LSN from a previous write response to verify that the index has caught up to that write before issuing a query.

Parameters:

target (int) – The LSN threshold to check against. Typically the lsn_committed value returned by a prior upsert or delete response.

Returns:

True if lsn_reconciled is not None and is greater than or equal to target; False otherwise.

Return type:

bool

Examples

from pinecone import Pinecone

pc = Pinecone(api_key="your-api-key")
index = pc.index(host="product-search.svc.pinecone.io")
upsert_resp = index.upsert_records(
    namespace="electronics",
    records=[{"id": "prod-42", "_text": "wireless headphones"}],
)
committed_lsn = upsert_resp.response_info.lsn_committed
query_resp = index.search(
    namespace="electronics",
    inputs={"text": "headphones"},
)
query_resp.result.response_info.is_reconciled(committed_lsn)
property lsn_committed: int | None

Log sequence number of the last committed write.

Parsed from the x-pinecone-lsn-committed response header.

Returns:

int LSN, or None when the header is absent or its value is not a valid integer.

property lsn_reconciled: int | None

Log sequence number indicating how far the index has reconciled.

Parsed from the x-pinecone-lsn-reconciled response header.

Returns:

int LSN, or None when the header is absent or its value is not a valid integer.

raw_headers: dict[str, str]
property request_id: str | None

Server-assigned request identifier from x-pinecone-request-id.

Returns:

str with the request ID, or None when the header is absent.

Search Models

class pinecone.models.vectors.search.Hit(*, id_, score_, fields=<factory>)[source]

Bases: StructDictMixin, Struct

A single search result hit.

The API returns _id and _score as field names. These are mapped to id_ and score_ internally (to avoid Python name mangling), with convenience properties id and score for clean access.

Variables:

  • id (str) – The record identifier (wire name _id).

  • score (float) – The similarity score (wire name _score).

  • fields (dict[str, Any]) – Record fields included in the result.

Parameters:
fields: dict[str, Any]
property id: str

Alias for id_ to provide a cleaner API.

id_: str
property score: float

Alias for score_ to provide a cleaner API.

score_: float
class pinecone.models.vectors.search.SearchResult(*, hits=<factory>)[source]

Bases: StructDictMixin, Struct

The result wrapper containing hits.

Variables:

hits (list[Hit]) – List of search result hits.

Parameters:

hits (list[Hit])

hits: list[Hit]
class pinecone.models.vectors.search.SearchRecordsResponse(*, result, usage, response_info=None)[source]

Bases: StructDictMixin, Struct

Response from a search records operation.

Variables:

  • result (SearchResult) – Wrapper containing the list of hits.

  • usage (SearchUsage) – Usage statistics for the search operation.

  • response_info (ResponseInfo | None) – HTTP response metadata (request ID, LSN values), or None if not populated.

Parameters:
response_info: ResponseInfo | None
result: SearchResult
usage: SearchUsage
class pinecone.models.vectors.search.SearchInputs[source]

Bases: dict

Typed configuration for the inputs parameter of search().

Required keys: text.

Variables:

text (str) – Text to embed server-side for the search query.

text: str
class pinecone.models.vectors.search.SearchUsage(*, read_units, embed_total_tokens=None, rerank_units=None)[source]

Bases: StructDictMixin, Struct

Usage statistics for a search operation.

Variables:

  • read_units (int) – Number of read units consumed.

  • embed_total_tokens (int | None) – Total tokens used for embedding, or None if the search did not use integrated embedding.

  • rerank_units (int | None) – Number of rerank units consumed, or None if the search did not use reranking.

Parameters:

  • read_units (int)

  • embed_total_tokens (int | None)

  • rerank_units (int | None)

embed_total_tokens: int | None
read_units: int
rerank_units: int | None
class pinecone.models.vectors.search.RerankConfig[source]

Bases: dict

Typed configuration for the rerank parameter of search().

Required keys: model, rank_fields. All other keys are optional.

Variables:

  • model (str) – Reranking model name (e.g. "bge-reranker-v2-m3").

  • rank_fields (list[str]) – Record fields to rank on (e.g. ["text"]).

  • top_n (int) – Number of top results to return after reranking. Defaults to the value of top_k when omitted.

  • parameters (dict[str, Any]) – Model-specific parameters forwarded to the reranker. See the model documentation for supported keys.

  • query (str) – Override query text used for reranking. When omitted the query is inferred from the search inputs.

model: str
parameters: dict[str, Any]
query: str
rank_fields: list[str]
top_n: int
class pinecone.models.vectors.query_aggregator.QueryNamespacesResults(*, matches=<factory>, usage=<factory>, ns_usage=<factory>)[source]

Bases: StructDictMixin, Struct

Aggregated results from querying multiple namespaces.

Variables:

  • matches (list[ScoredVector]) – Combined top-k results across all namespaces, sorted by relevance according to the metric used.

  • usage (Usage) – Total aggregated read unit usage across all namespaces.

  • ns_usage (dict[str, Usage]) – Per-namespace read unit usage keyed by namespace name.

Parameters:

  • matches (list[ScoredVector])

  • usage (Usage)

  • ns_usage (dict[str, Usage])

matches: list[ScoredVector]
ns_usage: dict[str, Usage]
usage: Usage
class pinecone.models.vectors.query_aggregator.QueryResultsAggregator(*, metric, top_k=10)[source]

Bases: object

Merges per-namespace QueryResponse objects into a single combined result.

Uses a heap-based algorithm to efficiently merge scored vectors from multiple namespaces. For cosine/dotproduct metrics, higher scores rank first. For euclidean, lower scores rank first. Ties are broken by insertion order.

Parameters:

  • metric (str) – Distance metric — one of "cosine", "euclidean", or "dotproduct".

  • top_k (int) – Maximum number of results to return. Defaults to 10.

Raises:

ValueError – If metric is not a recognized value or top_k < 1.

__init__(*, metric, top_k=10)[source]
Parameters:
Return type:

None

add_results(namespace, response)[source]

Add results from a single namespace query.

Parameters:

  • namespace (str) – Namespace that was queried.

  • response (QueryResponse) – Query response from that namespace.

Raises:

ValueError – If called after get_results().

Return type:

None

get_results()[source]

Finalize and return the aggregated results.

After calling this method, no more results can be added.

Returns:

Aggregated query results with the top-k matches across all namespaces.

Return type:

QueryNamespacesResults

Inference Models

class pinecone.models.inference.embed.DenseEmbedding(*, values, vector_type='dense')[source]

Bases: DictLikeStruct, Struct

A dense embedding vector.

Variables:

  • values (list[float]) – The embedding values as a list of floats.

  • vector_type (str) – The type of embedding, always "dense".

Parameters:
values: list[float]
vector_type: str
class pinecone.models.inference.embed.SparseEmbedding(*, sparse_values, sparse_indices, sparse_tokens=None, vector_type='sparse')[source]

Bases: StructDictMixin, Struct

A sparse embedding vector.

Variables:

  • sparse_values (list[float]) – The non-zero values of the sparse embedding.

  • sparse_indices (list[int]) – The indices of the non-zero values.

  • sparse_tokens (list[str] | None) – Optional token strings corresponding to each index.

  • vector_type (str) – The type of embedding, always "sparse".

Parameters:
sparse_indices: list[int]
sparse_tokens: list[str] | None
sparse_values: list[float]
vector_type: str
class pinecone.models.inference.embed.EmbeddingsList(*, model, vector_type, data, usage)[source]

Bases: Struct

Response from the embed endpoint.

Supports integer indexing, iteration, and len() over the embedded data items, as well as bracket access for field names.

Variables:
Parameters:
data: list[DenseEmbedding] | list[SparseEmbedding]
model: str
to_dict()[source]

Return a plain dict representation of this object.

Return type:

dict[str, Any]

usage: EmbedUsage
vector_type: str
class pinecone.models.inference.rerank.RerankResult(*, model, data, usage)[source]

Bases: Struct

Response from the rerank endpoint.

Variables:
Parameters:
data: list[RankedDocument]
model: str
to_dict()[source]

Return a plain dict representation of this object.

Return type:

dict[str, Any]

usage: RerankUsage
class pinecone.models.inference.rerank.RankedDocument(*, index, score, document=None)[source]

Bases: StructDictMixin, Struct

A document with its relevance score from a rerank operation.

Variables:

  • index (int) – The original index of the document in the input list.

  • score (float) – The relevance score assigned by the reranker.

  • document (dict[str, Any] | None) – The original document content, if requested.

Parameters:
document: dict[str, Any] | None
index: int
score: float
class pinecone.models.inference.models.ModelInfo(*, model, short_description, type, supported_parameters, vector_type=None, default_dimension=None, supported_dimensions=None, modality=None, max_sequence_length=None, max_batch_size=None, provider_name=None, supported_metrics=None)[source]

Bases: Struct

Information about an inference model.

Variables:

  • model (str) – The model identifier (also accessible as name).

  • short_description (str) – A brief description of the model (also accessible as description).

  • type (str) – The model type (e.g. "embed", "rerank").

  • supported_parameters (list[pinecone.models.inference.models.ModelInfoSupportedParameter]) – Parameters accepted by the model.

  • vector_type (str | None) – The type of vectors produced (for embed models).

  • default_dimension (int | None) – Default output dimension (for embed models).

  • supported_dimensions (list[int] | None) – Available output dimensions (for embed models).

  • modality (str | None) – The input modality (e.g. "text").

  • max_sequence_length (int | None) – Maximum input sequence length.

  • max_batch_size (int | None) – Maximum batch size for requests.

  • provider_name (str | None) – The model provider.

  • supported_metrics (list[str] | None) – Supported similarity metrics.

Parameters:

  • model (str)

  • short_description (str)

  • type (str)

  • supported_parameters (list[ModelInfoSupportedParameter])

  • vector_type (str | None)

  • default_dimension (int | None)

  • supported_dimensions (list[int] | None)

  • modality (str | None)

  • max_sequence_length (int | None)

  • max_batch_size (int | None)

  • provider_name (str | None)

  • supported_metrics (list[str] | None)

default_dimension: int | None
property description: str

Alias for short_description — a brief description of the model.

max_batch_size: int | None
max_sequence_length: int | None
modality: str | None
model: str
property name: str

Alias for model — the model identifier.

provider_name: str | None
short_description: str
supported_dimensions: list[int] | None
supported_metrics: list[str] | None
supported_parameters: list[ModelInfoSupportedParameter]
to_dict()[source]

Return a plain dict representation of this object.

Return type:

dict[str, Any]

type: str
vector_type: str | None
class pinecone.models.inference.model_list.ModelInfoList(models)[source]

Bases: object

Wrapper around a list of ModelInfo with convenience methods.

Supports integer indexing, string key access (["models"]), iteration, len(), and a .names() convenience method.

Variables:

models – The underlying list of ModelInfo instances.

Parameters:

models (list[ModelInfo])

__init__(models)[source]

Initialize a ModelInfoList.

Parameters:

models (list[ModelInfo]) – List of ModelInfo instances.

Return type:

None

property models: list[ModelInfo]

Return the underlying list of models.

names()[source]

Return a list of model identifiers.

Returns:

Model identifiers from each ModelInfo.

Return type:

list[str]

Examples

>>> from pinecone import Pinecone
>>> pc = Pinecone(api_key="your-api-key")
>>> models = pc.inference.list_models()
>>> models.names()
['multilingual-e5-large', 'pinecone-sparse-english-v0']
to_dict()[source]

Return a plain dict representation of this list.

Return type:

dict[str, Any]

class pinecone.inference.models.index_embed.IndexEmbed(model, field_map, metric=None, read_parameters=<factory>, write_parameters=<factory>)[source]

Bases: object

Configuration for an integrated (model-backed) embedding index.

Describes the embedding model and field mapping used for an integrated index. Legacy class preserved for backwards compatibility.

Parameters:
__init__(model, field_map, metric=None, read_parameters=<factory>, write_parameters=<factory>)
Parameters:
Return type:

None

as_dict()[source]

Return the instance’s field values as a plain dictionary.

Return type:

dict[str, Any]

field_map: dict[str, Any]
metric: str | None = None
model: str
read_parameters: dict[str, Any]
write_parameters: dict[str, Any]

Import Models

class pinecone.models.imports.model.ImportModel(*, id, uri, status, created_at, finished_at=None, percent_complete=None, records_imported=None, error=None)[source]

Bases: StructDictMixin, Struct

Response model for a bulk import operation.

Variables:

  • id (str) – Unique identifier for the import operation.

  • uri (str) – Source URI for the import data.

  • status (str) – Current status of the import (Pending, InProgress, Failed, Completed, Cancelled).

  • created_at (str) – Timestamp when the import was created.

  • finished_at (str | None) – Timestamp when the import finished.

  • percent_complete (float | None) – Percentage of the import that has completed.

  • records_imported (int | None) – Number of records imported so far.

  • error (str | None) – Error message if the import failed.

Parameters:

  • id (str)

  • uri (str)

  • status (str)

  • created_at (str)

  • finished_at (str | None)

  • percent_complete (float | None)

  • records_imported (int | None)

  • error (str | None)

created_at: str
error: str | None
finished_at: str | None
id: str
percent_complete: float | None
records_imported: int | None
status: str
uri: str
class pinecone.models.imports.list.ImportList(imports, *, pagination=None)[source]

Bases: object

Wrapper around a list of ImportModel with convenience methods.

Parameters:
__init__(imports, *, pagination=None)[source]

Initialize an ImportList.

Parameters:

  • imports (list[ImportModel]) – List of ImportModel instances representing bulk import operations.

  • pagination (Pagination | None) – Optional Pagination token for fetching additional pages of results.

Return type:

None

to_dict()[source]

Return the list as a serializable dict.

Returns:

A dict with a "data" key containing a list of import dicts, each produced by ImportModel.to_dict(). When the wrapper has a pagination token, the dict also includes a "pagination" key with the token for fetching the next page.

Return type:

dict[str, Any]

Examples

>>> from pinecone import Pinecone
>>> pc = Pinecone(api_key="your-api-key")
>>> index = pc.Index("product-search")
>>> imports = index.list_imports_paginated()
>>> imports.to_dict()
{'data': [{'id': 'import-abc123', ...}, {'id': 'import-def456', ...}]}
class pinecone.models.imports.model.StartImportResponse(*, id)[source]

Bases: StructDictMixin, Struct

Response model for starting a bulk import operation.

Variables:

id (str) – Unique identifier for the created import operation.

Parameters:

id (str)

id: str
class pinecone.models.imports.error_mode.ImportErrorMode(value)[source]

Bases: str, Enum

Behaviour when an individual record fails during a bulk import.

Variables:

  • CONTINUE – Skip the failed record and continue importing remaining records.

  • ABORT – Abort the entire import when any record fails.

ABORT = 'abort'
CONTINUE = 'continue'

Collection Models

class pinecone.models.collections.model.CollectionModel(*, name, status, environment, size=None, dimension=None, vector_count=None)[source]

Bases: StructDictMixin, Struct

Response model for a Pinecone collection.

Variables:

  • name (str) – The name of the collection.

  • status (str) – Current status of the collection (e.g. "Ready", "Initializing", "Terminating").

  • environment (str) – Deployment environment where the collection is hosted.

  • size (int | None) – Size of the collection in bytes, or None if not yet available.

  • dimension (int | None) – Dimensionality of vectors in the collection, or None if not yet available.

  • vector_count (int | None) – Number of vectors in the collection, or None if not yet available.

Parameters:

  • name (str)

  • status (str)

  • environment (str)

  • size (int | None)

  • dimension (int | None)

  • vector_count (int | None)

dimension: int | None
environment: str
name: str
size: int | None
status: str
vector_count: int | None
class pinecone.models.collections.list.CollectionList(collections)[source]

Bases: object

Wrapper around a list of CollectionModel with convenience methods.

Parameters:

collections (list[CollectionModel])

__init__(collections)[source]
Parameters:

collections (list[CollectionModel])

Return type:

None

names()[source]

Return a list of collection names.

Return type:

list[str]

to_dict()[source]

Return the list as a serializable dict.

Returns:

A dict with a "data" key containing a list of collection dicts, each produced by CollectionModel.to_dict().

Return type:

dict[str, Any]

Examples

>>> from pinecone import Pinecone
>>> pc = Pinecone(api_key="your-api-key")
>>> collections = pc.list_collections()
>>> collections.to_dict()
{'data': [{'name': 'movie-embeddings-v1', ...}, {'name': 'product-snapshot', ...}]}
class pinecone.db_control.models.collection_description.CollectionDescription(name, source)[source]

Bases: NamedTuple

Basic metadata describing a collection.

Variables:

  • name (str) – The name of the collection.

  • source (str) – The source index used to create the collection.

Parameters:
name: str

Alias for field number 0

source: str

Alias for field number 1

Backup and Restore Models

class pinecone.models.backups.model.BackupModel(*, backup_id, source_index_name, source_index_id, status, cloud, region, name=None, description=None, dimension=None, metric=None, record_count=None, namespace_count=None, size_bytes=None, tags=None, created_at=None)[source]

Bases: Struct

Response model for a Pinecone backup.

Variables:

  • backup_id (str) – Unique identifier for the backup.

  • source_index_name (str) – Name of the index that was backed up.

  • source_index_id (str) – Unique identifier of the source index.

  • status (str) – Current status of the backup.

  • cloud (str) – Cloud provider where the backup is stored.

  • region (str) – Region where the backup is stored.

  • name (str | None) – User-provided name for the backup.

  • description (str | None) – User-provided description for the backup.

  • dimension (int | None) – Dimensionality of vectors in the backup.

  • metric (str | None) – Distance metric of the backed-up index.

  • record_count (int | None) – Number of records in the backup.

  • namespace_count (int | None) – Number of namespaces in the backup.

  • size_bytes (int | None) – Size of the backup in bytes.

  • tags (dict[str, str] | None) – User-defined key-value tags.

  • created_at (str | None) – Timestamp when the backup was created.

Parameters:

  • backup_id (str)

  • source_index_name (str)

  • source_index_id (str)

  • status (str)

  • cloud (str)

  • region (str)

  • name (str | None)

  • description (str | None)

  • dimension (int | None)

  • metric (str | None)

  • record_count (int | None)

  • namespace_count (int | None)

  • size_bytes (int | None)

  • tags (dict[str, str] | None)

  • created_at (str | None)

backup_id: str
cloud: str
created_at: str | None
description: str | None
dimension: int | None
metric: str | None
name: str | None
namespace_count: int | None
record_count: int | None
region: str
property schema: None

Metadata schema associated with this backup (not populated in the rewrite).

size_bytes: int | None
source_index_id: str
source_index_name: str
status: str
tags: dict[str, str] | None
to_dict()[source]

Return a dict representation of this backup model.

Returns:

Dictionary with all fields, including optional ones that are None (e.g. name, description, dimension, metric, record_count, namespace_count, size_bytes, tags, created_at). Values are not recursively converted.

Return type:

dict[str, Any]

Examples

>>> from pinecone.models.backups.model import BackupModel
>>> backup = BackupModel(
...     backup_id="bkp-1",
...     source_index_name="my-index",
...     source_index_id="idx-abc",
...     status="Ready",
...     cloud="aws",
...     region="us-east-1",
...     name="weekly-backup",
... )
>>> d = backup.to_dict()
>>> d["backup_id"]
'bkp-1'
>>> d["name"]
'weekly-backup'
>>> d["description"] is None
True
class pinecone.models.backups.list.BackupList(backups, *, pagination=None)[source]

Bases: object

Wrapper around a list of BackupModel with convenience methods.

Parameters:
__init__(backups, *, pagination=None)[source]

Initialize a BackupList.

Parameters:

  • backups (list[BackupModel]) – List of BackupModel instances representing index backups.

  • pagination (Pagination | None) – Optional Pagination token for fetching additional pages of results.

Return type:

None

property data: list[BackupModel]

Return the list of backups.

names()[source]

Return a list of backup names, falling back to backup_id.

If a backup has no name set, its backup_id is used instead.

Returns:

Backup names (or IDs when names are absent).

Return type:

list[str]

Examples

>>> from pinecone import Pinecone
>>> pc = Pinecone(api_key="your-api-key")
>>> backups = pc.list_backups(index_name="movie-recommendations")
>>> backups.names()
['daily-2025-01-01', 'weekly-2024-12-29']
to_dict()[source]

Return the list as a serializable dict.

Returns:

A dict with a "data" key containing a list of backup dicts, each produced by BackupModel.to_dict(). When the wrapper has a pagination token, the dict also includes a "pagination" key with the token for fetching the next page.

Return type:

dict[str, Any]

Examples

>>> from pinecone import Pinecone
>>> pc = Pinecone(api_key="your-api-key")
>>> backups = pc.list_backups(index_name="movie-recommendations")
>>> backups.to_dict()
{'data': [{'backup_id': 'bkp-abc123', ...}, {'backup_id': 'bkp-def456', ...}]}
class pinecone.models.backups.model.RestoreJobModel(*, restore_job_id, backup_id, target_index_name, target_index_id, status, created_at, completed_at=None, percent_complete=None)[source]

Bases: Struct

Response model for a Pinecone restore job.

Variables:

  • restore_job_id (str) – Unique identifier for the restore job.

  • backup_id (str) – Identifier of the backup being restored.

  • target_index_name (str) – Name of the index being restored to.

  • target_index_id (str) – Unique identifier of the target index.

  • status (str) – Current status of the restore job.

  • created_at (str) – Timestamp when the restore job was created.

  • completed_at (str | None) – Timestamp when the restore job completed.

  • percent_complete (float | None) – Percentage of the restore job that has completed.

Parameters:

  • restore_job_id (str)

  • backup_id (str)

  • target_index_name (str)

  • target_index_id (str)

  • status (str)

  • created_at (str)

  • completed_at (str | None)

  • percent_complete (float | None)

backup_id: str
completed_at: str | None
created_at: str
percent_complete: float | None
restore_job_id: str
status: str
target_index_id: str
target_index_name: str
to_dict()[source]

Return a dict representation of this restore job model.

Returns:

Dictionary with all fields, including optional ones that are None (completed_at and percent_complete). Values are not recursively converted.

Return type:

dict[str, Any]

Examples

>>> from pinecone.models.backups.model import RestoreJobModel
>>> job = RestoreJobModel(
...     restore_job_id="rj-1",
...     backup_id="bkp-1",
...     target_index_name="my-index",
...     target_index_id="idx-abc",
...     status="Running",
...     created_at="2024-01-01T00:00:00Z",
... )
>>> d = job.to_dict()
>>> d["restore_job_id"]
'rj-1'
>>> d["completed_at"] is None
True
class pinecone.models.backups.list.RestoreJobList(restore_jobs, *, pagination=None)[source]

Bases: object

Wrapper around a list of RestoreJobModel with convenience methods.

Parameters:
__init__(restore_jobs, *, pagination=None)[source]

Initialize a RestoreJobList.

Parameters:

  • restore_jobs (list[RestoreJobModel]) – List of RestoreJobModel instances representing restore operations.

  • pagination (Pagination | None) – Optional Pagination token for fetching additional pages of results.

Return type:

None

property data: list[RestoreJobModel]

Return the list of restore jobs.

to_dict()[source]

Return the list as a serializable dict.

Returns:

A dict with a "data" key containing a list of restore job dicts, each produced by RestoreJobModel.to_dict(). When the wrapper has a pagination token, the dict also includes a "pagination" key with the token for fetching the next page.

Return type:

dict[str, Any]

Examples

from pinecone import Pinecone

pc = Pinecone(api_key="your-api-key")
jobs = pc.restore_jobs.list()
jobs.to_dict()
# {'data': [{'restore_job_id': 'rj-abc123', ...}, ...]}
class pinecone.models.backups.model.CreateIndexFromBackupResponse(*, restore_job_id, index_id)[source]

Bases: StructDictMixin, Struct

Response model for creating an index from a backup.

Variables:

  • restore_job_id (str) – Identifier of the restore job created.

  • index_id (str) – Identifier of the new index being created.

Parameters:

  • restore_job_id (str)

  • index_id (str)

index_id: str
restore_job_id: str

Namespace Models

class pinecone.models.namespaces.models.NamespaceDescription(*, name='', record_count=0, schema=None, indexed_fields=None)[source]

Bases: StructDictMixin, Struct

Description of a namespace including name, record count, and schema.

Variables:

  • name (str) – The name of the namespace.

  • record_count (int) – The total number of records in the namespace.

  • schema (pinecone.models.namespaces.models.NamespaceSchema | None) – Schema configuration for metadata indexing, or None.

  • indexed_fields (pinecone.models.namespaces.models.IndexedFields | None) – List of indexed metadata fields, or None.

Parameters:

  • name (str)

  • record_count (int)

  • schema (NamespaceSchema | None)

  • indexed_fields (IndexedFields | None)

indexed_fields: IndexedFields | None
name: str
record_count: int
schema: NamespaceSchema | None
class pinecone.models.namespaces.models.ListNamespacesResponse(*, namespaces=<factory>, pagination=None, total_count=0)[source]

Bases: StructDictMixin, Struct

Response from a list namespaces operation.

Variables:

  • namespaces (list[pinecone.models.namespaces.models.NamespaceDescription]) – List of namespace descriptions in this page.

  • pagination (pinecone.models.vectors.responses.Pagination | None) – Pagination token for the next page, or None if last page.

  • total_count (int) – Total number of namespaces matching the query.

Parameters:
namespaces: list[NamespaceDescription]
pagination: Pagination | None
total_count: int

Pagination Models

class pinecone.models.pagination.Page(*, items, pagination_token)[source]

Bases: Generic[T]

A single page of results from a paginated API.

Parameters:

  • items (list[T])

  • pagination_token (str | None)

__init__(*, items, pagination_token)[source]
Parameters:

  • items (list[T])

  • pagination_token (str | None)

Return type:

None

property has_more: bool

True if more pages are available.

class pinecone.models.pagination.Paginator(*, fetch_page, initial_token=None, limit=None)[source]

Bases: Generic[T]

Lazy iterator over paginated API results (sync).

Fetches pages on demand. Supports item-level iteration, page-level access via pages(), bulk collection via to_list(), and resumption via the pagination_token property.

Parameters:

  • fetch_page (Callable[[str | None], Page[T]]) – Callable that takes an optional pagination token and returns a Page.

  • initial_token (str | None) – Token to start pagination from. None starts from the beginning.

  • limit (int | None) – Maximum number of items to yield across all pages. None yields all items.

Examples

paginator = pc.assistants.list()
for assistant in paginator:
    print(assistant.name)

Collect all results into a list:

all_assistants = pc.assistants.list().to_list()
__init__(*, fetch_page, initial_token=None, limit=None)[source]
Parameters:
Return type:

None

pages()[source]

Iterate over pages rather than individual items.

When limit is set, yields full pages until the remaining budget is exhausted, then yields a truncated final page and stops.

Returns:

Generator yielding Page objects. Each page has an items list and an optional pagination_token.

Return type:

Generator[Page[T], None, None]

Examples

for page in pc.assistants.list().pages():
    for assistant in page.items:
        print(assistant.name)
property pagination_token: str | None

Token for the next page, or None if all pages have been fetched.

to_list()[source]

Fetch all items across all pages into a list.

Returns:

list of all items.

Return type:

list[T]

Examples

all_assistants = pc.assistants.list().to_list()
class pinecone.models.pagination.AsyncPaginator(*, fetch_page, initial_token=None, limit=None)[source]

Bases: Generic[T]

Async lazy iterator over paginated API results.

Fetches pages on demand. Supports item-level async iteration, page-level access via pages(), bulk collection via to_list(), and resumption via the pagination_token property.

Parameters:

  • fetch_page (Callable[[str | None], Awaitable[Page[T]]]) – Async callable that takes an optional pagination token and returns a Page.

  • initial_token (str | None) – Token to start pagination from. None starts from the beginning.

  • limit (int | None) – Maximum number of items to yield across all pages. None yields all items.

Examples

paginator = async_pc.assistants.list()
async for assistant in paginator:
    print(assistant.name)

Collect all results into a list:

paginator = async_pc.assistants.list()
all_assistants = await paginator.to_list()
__init__(*, fetch_page, initial_token=None, limit=None)[source]
Parameters:
Return type:

None

async pages()[source]

Iterate over pages rather than individual items.

When limit is set, yields full pages until the remaining budget is exhausted, then yields a truncated final page and stops.

Returns:

AsyncGenerator yielding Page objects. Each page has an items list and an optional pagination_token.

Return type:

AsyncGenerator[Page[T], None]

Examples

async for page in async_pc.assistants.list().pages():
    for assistant in page.items:
        print(assistant.name)
property pagination_token: str | None

Token for the next page, or None if all pages have been fetched.

async to_list()[source]

Fetch all items across all pages into a list.

Returns:

list of all items.

Return type:

list[T]

Examples

paginator = async_pc.assistants.list()
all_assistants = await paginator.to_list()

Enums

class pinecone.models.enums.CloudProvider(value)[source]

Bases: str, Enum

Supported cloud providers for Pinecone indexes.

AWS = 'aws'
AZURE = 'azure'
GCP = 'gcp'
class pinecone.models.enums.Metric(value)[source]

Bases: str, Enum

Supported similarity metrics for vector search.

COSINE = 'cosine'
DOTPRODUCT = 'dotproduct'
EUCLIDEAN = 'euclidean'
class pinecone.models.enums.VectorType(value)[source]

Bases: str, Enum

Supported vector types.

DENSE = 'dense'
SPARSE = 'sparse'
class pinecone.models.enums.DeletionProtection(value)[source]

Bases: str, Enum

Deletion protection setting for indexes.

DISABLED = 'disabled'
ENABLED = 'enabled'
class pinecone.models.enums.EmbedModel(value)[source]

Bases: str, Enum

Known embedding models for integrated indexes.

Multilingual_E5_Large = 'multilingual-e5-large'
Pinecone_Sparse_English_V0 = 'pinecone-sparse-english-v0'
class pinecone.models.enums.RerankModel(value)[source]

Bases: str, Enum

Known reranking models.

Bge_Reranker_V2_M3 = 'bge-reranker-v2-m3'
Cohere_Rerank_3_5 = 'cohere-rerank-3.5'
Pinecone_Rerank_V0 = 'pinecone-rerank-v0'
class pinecone.models.enums.PodType(value)[source]

Bases: str, Enum

Supported pod type and size combinations.

P1_X1 = 'p1.x1'
P1_X2 = 'p1.x2'
P1_X4 = 'p1.x4'
P1_X8 = 'p1.x8'
P2_X1 = 'p2.x1'
P2_X2 = 'p2.x2'
P2_X4 = 'p2.x4'
P2_X8 = 'p2.x8'
S1_X1 = 's1.x1'
S1_X2 = 's1.x2'
S1_X4 = 's1.x4'
S1_X8 = 's1.x8'
class pinecone.db_control.enums.clouds.AwsRegion(value)[source]

Bases: str, Enum

AWS regions supported for serverless indexes.

AP_SOUTHEAST_1 = 'ap-southeast-1'
EU_CENTRAL_1 = 'eu-central-1'
EU_WEST_1 = 'eu-west-1'
US_EAST_1 = 'us-east-1'
US_WEST_2 = 'us-west-2'
class pinecone.db_control.enums.clouds.AzureRegion(value)[source]

Bases: str, Enum

Azure regions supported for serverless indexes.

EASTUS2 = 'eastus2'
GERMANYWESTCENTRAL = 'germanywestcentral'
class pinecone.db_control.enums.clouds.GcpRegion(value)[source]

Bases: str, Enum

GCP regions supported for serverless indexes.

EUROPE_WEST4 = 'europe-west4'
US_CENTRAL1 = 'us-central1'

Admin Models

class pinecone.models.admin.api_key.APIKeyModel(*, id, name, project_id, roles, description=None)[source]

Bases: StructDictMixin, Struct

Response model for a Pinecone API key.

Variables:

  • id (str) – Unique identifier for the API key.

  • name (str) – Name of the API key.

  • project_id (str) – Identifier of the project the key belongs to.

  • roles (list[APIKeyRole]) – List of roles assigned to the key (see APIKeyRole).

  • description (str | None) – Optional description for the API key. None if no description was set.

Parameters:

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> key = admin.api_keys.describe(api_key_id="key-abc123")
>>> key.id
'key-abc123'
>>> key.name
'prod-search-key'
>>> key.roles
[<APIKeyRole.DATA_PLANE_EDITOR: 'DataPlaneEditor'>]
>>> key.description
'Used by the search service'
description: str | None
id: str
name: str
project_id: str
property role: APIKeyRole

Singular alias for roles when the key has exactly one role.

Returns:

The single role assigned to this key.

Return type:

APIKeyRole

Raises:

ValueError – If the key has no roles or more than one role.

Examples

>>> key = admin.api_keys.describe(api_key_id="key-abc123")
>>> key.role
<APIKeyRole.DATA_PLANE_EDITOR: 'DataPlaneEditor'>

Keys with multiple roles raise ValueError; use roles instead:

multi_role_key = APIKeyModel(
    id="k2", name="k2", project_id="p1",
    roles=[APIKeyRole.PROJECT_EDITOR, APIKeyRole.DATA_PLANE_EDITOR]
)
try:
    multi_role_key.role
except ValueError as exc:
    print(exc)
# API key has 2 roles; use .roles to access all
roles: list[APIKeyRole]
class pinecone.models.admin.api_key.APIKeyList(api_keys)[source]

Bases: object

Wrapper around a list of APIKeyModel with convenience methods.

Parameters:

api_keys (list[APIKeyModel])

__init__(api_keys)[source]

Initialize an APIKeyList.

Parameters:

api_keys (list[APIKeyModel]) – List of APIKeyModel instances representing Pinecone API keys.

Return type:

None

names()[source]

Return a list of API key names.

Returns:

API key names in the same order as the list.

Return type:

list[str]

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> keys = admin.api_keys.list(project_id="proj-abc123")
>>> keys.names()
['prod-search-key', 'ci-pipeline-key']
to_dict()[source]

Return the list as a serializable dict.

Returns:

A dict with a "data" key containing a list of API key dicts, each produced by APIKeyModel.to_dict().

Return type:

dict[str, Any]

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> keys = admin.api_keys.list(project_id="proj-abc123")
>>> keys.to_dict()
{'data': [{'name': 'prod-search-key', ...}, {'name': 'ci-pipeline-key', ...}]}
class pinecone.models.admin.api_key.APIKeyWithSecret(*, key, value)[source]

Bases: StructDictMixin, Struct

Response model for an API key with its secret value.

The secret value is only available at creation time.

Variables:
Parameters:
key: APIKeyModel
value: str
class pinecone.models.admin.api_key.APIKeyRole(value)[source]

Bases: str, Enum

Roles that can be assigned to a Pinecone API key.

Possible values: PROJECT_EDITOR, PROJECT_VIEWER, CONTROL_PLANE_EDITOR, CONTROL_PLANE_VIEWER, DATA_PLANE_EDITOR, DATA_PLANE_VIEWER.

Examples

>>> from pinecone import Admin
>>> from pinecone.models.admin.api_key import APIKeyRole
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> result = admin.api_keys.create(
...     project_id="proj-abc123",
...     name="read-only-key",
...     roles=[APIKeyRole.DATA_PLANE_VIEWER],
... )
>>> result.key.roles
[<APIKeyRole.DATA_PLANE_VIEWER: 'DataPlaneViewer'>]

Update a key to use control-plane access:

>>> key = admin.api_keys.update(
...     api_key_id="key-abc123",
...     roles=[APIKeyRole.CONTROL_PLANE_EDITOR],
... )
>>> key.role
<APIKeyRole.CONTROL_PLANE_EDITOR: 'ControlPlaneEditor'>
CONTROL_PLANE_EDITOR = 'ControlPlaneEditor'
CONTROL_PLANE_VIEWER = 'ControlPlaneViewer'
DATA_PLANE_EDITOR = 'DataPlaneEditor'
DATA_PLANE_VIEWER = 'DataPlaneViewer'
PROJECT_EDITOR = 'ProjectEditor'
PROJECT_VIEWER = 'ProjectViewer'
class pinecone.models.admin.organization.OrganizationModel(*, id, name, plan, payment_status, created_at, support_tier)[source]

Bases: StructDictMixin, Struct

Response model for a Pinecone organization.

Variables:

  • id (str) – Unique identifier for the organization.

  • name (str) – Name of the organization.

  • plan (str) – Plan tier (e.g. Free, Standard, Enterprise, Dedicated).

  • payment_status (str) – Current payment status.

  • created_at (str) – Timestamp when the organization was created.

  • support_tier (str) – Support tier for the organization.

Parameters:
created_at: str
id: str
name: str
payment_status: str
plan: str
support_tier: str
class pinecone.models.admin.organization.OrganizationList(organizations)[source]

Bases: object

Wrapper around a list of OrganizationModel with convenience methods.

Parameters:

organizations (list[OrganizationModel])

__init__(organizations)[source]

Initialize an OrganizationList.

Parameters:

organizations (list[OrganizationModel]) – List of OrganizationModel instances representing Pinecone organizations.

Return type:

None

names()[source]

Return a list of organization names.

Returns:

Organization names in the same order as the list.

Return type:

list[str]

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> orgs = admin.organizations.list()
>>> orgs.names()
['acme-corp', 'research-team']
to_dict()[source]

Return the list as a serializable dict.

Returns:

A dict with a "data" key containing a list of organization dicts, each produced by OrganizationModel.to_dict().

Return type:

dict[str, Any]

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> orgs = admin.organizations.list()
>>> orgs.to_dict()
{'data': [{'name': 'acme-corp', ...}, {'name': 'research-team', ...}]}
class pinecone.models.admin.project.ProjectModel(*, id, name, max_pods, force_encryption_with_cmek, organization_id, created_at=None)[source]

Bases: StructDictMixin, Struct

Response model for a Pinecone project.

Variables:

  • id (str) – Unique identifier for the project.

  • name (str) – Name of the project.

  • max_pods (int) – Maximum number of pods allowed in the project.

  • force_encryption_with_cmek (bool) – Whether CMEK encryption is enforced.

  • organization_id (str) – Identifier of the parent organization.

  • created_at (str | None) – Timestamp when the project was created.

Parameters:

  • id (str)

  • name (str)

  • max_pods (int)

  • force_encryption_with_cmek (bool)

  • organization_id (str)

  • created_at (str | None)

created_at: str | None
force_encryption_with_cmek: bool
id: str
max_pods: int
name: str
organization_id: str
class pinecone.models.admin.project.ProjectList(projects)[source]

Bases: object

Wrapper around a list of ProjectModel with convenience methods.

Parameters:

projects (list[ProjectModel])

__init__(projects)[source]

Initialize a ProjectList.

Parameters:

projects (list[ProjectModel]) – List of ProjectModel instances representing Pinecone projects.

Return type:

None

names()[source]

Return a list of project names.

Returns:

Project names in the same order as the list.

Return type:

list[str]

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> projects = admin.projects.list()
>>> projects.names()
['production-search', 'staging-recommendations']
to_dict()[source]

Return the list as a serializable dict.

Returns:

A dict with a "data" key containing a list of project dicts, each produced by ProjectModel.to_dict().

Return type:

dict[str, Any]

Examples

>>> from pinecone import Admin
>>> admin = Admin(client_id="your-client-id", client_secret="your-client-secret")
>>> projects = admin.projects.list()
>>> projects.to_dict()
{'data': [{'name': 'production-search', ...}, {'name': 'staging-recommendations', ...}]}

Assistant Models

class pinecone.models.assistant.model.AssistantModel(*, name, status, metadata=None, instructions=None, host=None, created_at=None, updated_at=None)[source]

Bases: AssistantModelLegacyMethodsMixin, StructDictMixin, Struct

Response model for a Pinecone assistant.

Variables:

  • name (str) – The name of the assistant.

  • status (str) – Current status of the assistant (e.g. "Initializing", "Ready", "Terminating", "Failed", "InitializationFailed").

  • created_at (str | None) – ISO 8601 timestamp when the assistant was created, or None if not returned by the API.

  • updated_at (str | None) – ISO 8601 timestamp when the assistant was last updated, or None if not returned by the API.

  • metadata (dict[str, Any] | None) – Optional metadata dictionary associated with the assistant, or None if not set.

  • instructions (str | None) – Optional description or directive for the assistant to apply to all responses, or None if not set.

  • host (str | None) – The host where the assistant is deployed, or None if not yet available.

Parameters:

  • name (str)

  • status (str)

  • metadata (dict[str, Any] | None)

  • instructions (str | None)

  • host (str | None)

  • created_at (str | None)

  • updated_at (str | None)

created_at: str | None
host: str | None
instructions: str | None
metadata: dict[str, Any] | None
name: str
status: str
updated_at: str | None
class pinecone.models.assistant.file_model.AssistantFileModel(*, name, id, metadata=None, created_on=None, updated_on=None, status=None, size=None, multimodal=None, signed_url=None, content_hash=None, percent_done=None, error_message=None)[source]

Bases: StructDictMixin, Struct

Response model for a file attached to a Pinecone assistant.

Variables:

  • name (str) – The name of the file.

  • id (str) – Unique identifier for the file.

  • metadata (dict[str, object] | None) – Optional metadata dictionary associated with the file, or None if not set.

  • created_on (str | None) – ISO 8601 timestamp when the file was created, or None.

  • updated_on (str | None) – ISO 8601 timestamp when the file was last updated, or None.

  • status (str | None) – Current status of the file (e.g. "Processing", "Available", "Deleting", "ProcessingFailed"), or None.

  • size (int | None) – Size of the file in bytes, or None.

  • multimodal (bool | None) – Whether the file was processed as multimodal, or None.

  • signed_url (str | None) – A temporary signed URL for downloading the file, or None when not requested or unavailable.

  • content_hash (str | None) – Hash of the file content (wire key crc32c_hash), or None when not available. Legacy callers can also access this value via the crc32c_hash property alias.

  • percent_done (float | None) – Processing progress as a percentage (0.0–100.0), or None when not available or not applicable.

  • error_message (str | None) – Error message describing why processing failed, or None when processing succeeded or is still in progress.

Parameters:

  • name (str)

  • id (str)

  • metadata (dict[str, object] | None)

  • created_on (str | None)

  • updated_on (str | None)

  • status (str | None)

  • size (int | None)

  • multimodal (bool | None)

  • signed_url (str | None)

  • content_hash (str | None)

  • percent_done (float | None)

  • error_message (str | None)

content_hash: str | None
property crc32c_hash: str | None

Backwards-compatibility alias for content_hash.

created_on: str | None
error_message: str | None
id: str
metadata: dict[str, object] | None
multimodal: bool | None
name: str
percent_done: float | None
signed_url: str | None
size: int | None
status: str | None
updated_on: str | None
class pinecone.models.assistant.list.ListAssistantsResponse(*, assistants, next=None)[source]

Bases: StructDictMixin, Struct

Paginated response for listing assistants.

Variables:
Parameters:
assistants: list[AssistantModel]
next: str | None
property next_token: str | None

Backwards-compatibility alias for next.

class pinecone.models.assistant.list.ListFilesResponse(*, files, next=None)[source]

Bases: StructDictMixin, Struct

Paginated response for listing assistant files.

Variables:
Parameters:
files: list[AssistantFileModel]
next: str | None
property next_token: str | None

Backwards-compatibility alias for next.

class pinecone.models.assistant.message.Message(*, content, role='user')[source]

Bases: StructDictMixin, Struct

A message to send to an assistant.

Variables:

  • content (str) – The text content of the message.

  • role (str) – The role of the message author. Defaults to "user".

Parameters:
content: str
classmethod from_dict(d)[source]

Create a Message from a dictionary.

Extracts "content" and "role" keys, defaulting role to "user" when not present.

Parameters:

d (dict[str, Any]) – A dictionary with at least a "content" key.

Returns:

A new Message instance.

Return type:

Message

role: str
class pinecone.models.assistant.chat.ChatResponse(*, id, model, usage, message, finish_reason, citations)[source]

Bases: StructDictMixin, Struct

Non-streaming response from the assistant chat endpoint.

Variables:

  • id (str) – Unique identifier for the chat response.

  • model (str) – The model used to generate the response.

  • usage (pinecone.models.assistant.chat.ChatUsage) – Token usage statistics for the request.

  • message (pinecone.models.assistant.chat.ChatMessage) – The assistant’s response message.

  • finish_reason (str) – The reason the model stopped generating (e.g. "stop", "length").

  • citations (list[pinecone.models.assistant.chat.ChatCitation]) – List of citations linking response text to source documents.

Parameters:

  • id (str)

  • model (str)

  • usage (ChatUsage)

  • message (ChatMessage)

  • finish_reason (str)

  • citations (list[ChatCitation])

citations: list[ChatCitation]
finish_reason: str
id: str
message: ChatMessage
model: str
usage: ChatUsage
class pinecone.models.assistant.chat.ChatCompletionResponse(*, id, model, usage, choices)[source]

Bases: StructDictMixin, Struct

Non-streaming response from the OpenAI-compatible chat completion endpoint.

Variables:

  • id (str) – Unique identifier for the chat completion.

  • model (str) – The model used to generate the response.

  • usage (pinecone.models.assistant.chat.ChatUsage) – Token usage statistics for the request.

  • choices (list[pinecone.models.assistant.chat.ChatCompletionChoice]) – List of completion choices.

Parameters:

  • id (str)

  • model (str)

  • usage (ChatUsage)

  • choices (list[ChatCompletionChoice])

choices: list[ChatCompletionChoice]
id: str
model: str
usage: ChatUsage
class pinecone.models.assistant.context.ContextResponse(*, snippets, usage, id=None)[source]

Bases: StructDictMixin, Struct

Response from the assistant context endpoint.

Variables:

  • snippets (list[pinecone.models.assistant.context.TextSnippet | pinecone.models.assistant.context.MultimodalSnippet]) – The list of context snippets.

  • usage (pinecone.models.assistant.chat.ChatUsage) – Token usage statistics for the request.

  • id (str | None) – Unique identifier for the context response, or None if not included in the response.

Parameters:

  • snippets (list[TextSnippet | MultimodalSnippet])

  • usage (ChatUsage)

  • id (str | None)

id: str | None
snippets: list[TextSnippet | MultimodalSnippet]
usage: ChatUsage
class pinecone.models.assistant.options.ContextOptions(*, top_k=None, snippet_size=None, multimodal=None, include_binary_content=None)[source]

Bases: StructDictMixin, Struct

Options controlling how context is retrieved for assistant operations.

All fields are optional and default to None, letting the server apply its own defaults.

Variables:

  • top_k (int | None) – Maximum number of context snippets to retrieve.

  • snippet_size (int | None) – Target size (in tokens) for each context snippet.

  • multimodal (bool | None) – Whether to include multimodal (image) content in retrieved context.

  • include_binary_content (bool | None) – Whether to include binary file content in retrieved context.

Parameters:

  • top_k (int | None)

  • snippet_size (int | None)

  • multimodal (bool | None)

  • include_binary_content (bool | None)

classmethod from_dict(d)[source]

Construct a ContextOptions from a plain dict representation.

Parameters:

d (dict[str, Any])

Return type:

ContextOptions

include_binary_content: bool | None
multimodal: bool | None
snippet_size: int | None
top_k: int | None
class pinecone.models.assistant.evaluation.AlignmentResult(*, scores, facts, usage)[source]

Bases: StructDictMixin, Struct

Full result of an alignment evaluation.

Variables:

  • scores (pinecone.models.assistant.evaluation.AlignmentScores) – Aggregate correctness, completeness, and alignment scores.

  • facts (list[pinecone.models.assistant.evaluation.EntailmentResult]) – Per-fact entailment results with reasoning.

  • usage (pinecone.models.assistant.chat.ChatUsage) – Token usage statistics for the evaluation request.

Parameters:

  • scores (AlignmentScores)

  • facts (list[EntailmentResult])

  • usage (ChatUsage)

facts: list[EntailmentResult]
scores: AlignmentScores
usage: ChatUsage
class pinecone.models.assistant.streaming.ChatStream(stream)[source]

Bases: object

Wraps a Pinecone-native streaming response for convenient text access.

Iterating over this object yields the full ChatStreamChunk sequence, preserving the existing typed-chunk contract for callers that need it. text() and collect() give direct access to text content without manual type dispatch.

The stream is single-pass: iterating, calling text(), or calling collect() all consume the same underlying iterator.

Examples

from pinecone import Pinecone
pc = Pinecone(api_key="your-api-key")
stream = pc.assistants.chat(
    assistant_name="acme-support-bot",
    messages=[{"content": "What can you help me with?"}],
    stream=True,
)
for text in stream.text():
    print(text, end="", flush=True)

Use collect() to drain the stream and return the full content as a single string:

stream = pc.assistants.chat(
    assistant_name="acme-support-bot",
    messages=[{"content": "Summarize your capabilities."}],
    stream=True,
)
full_content = stream.collect()
Parameters:

stream (Iterator[ChatStreamChunk])

__init__(stream)[source]
Parameters:

stream (Iterator[StreamMessageStart | StreamContentChunk | StreamCitationChunk | StreamMessageEnd])

Return type:

None

collect()[source]

Drain the stream and return all content fragments concatenated.

Returns:

The complete response as a single string.

Return type:

str

Examples

from pinecone import Pinecone
pc = Pinecone(api_key="your-api-key")
stream = pc.assistants.chat(
    assistant_name="acme-support-bot",
    messages=[{"content": "Explain vector databases in one sentence."}],
    stream=True,
)
full = stream.collect()
print(full)
text()[source]

Yield text fragments, skipping start/citation/end chunks.

Returns:

Iterator of text fragment strings. Each fragment is a partial response as it arrives from the server.

Return type:

Iterator[str]

Examples

from pinecone import Pinecone
pc = Pinecone(api_key="your-api-key")
stream = pc.assistants.chat(
    assistant_name="acme-support-bot",
    messages=[{"content": "Explain vector databases in one sentence."}],
    stream=True,
)
for chunk_text in stream.text():
    print(chunk_text, end="", flush=True)
pinecone.models.assistant.streaming.ChatStreamChunk

Union of all Pinecone-native chat streaming chunk types.

class pinecone.models.assistant.streaming.ChatCompletionStream(stream)[source]

Bases: object

Wraps an OpenAI-compatible streaming response for convenient text access.

Iterating over this object yields the full ChatCompletionStreamChunk sequence. text() filters to non-empty content fragments and handles the None sentinel values that appear in role-only and finish chunks.

The stream is single-pass: iterating, calling text(), or calling collect() all consume the same underlying iterator.

Examples

from pinecone import Pinecone
pc = Pinecone(api_key="your-api-key")
stream = pc.assistants.chat_completions(
    assistant_name="acme-support-bot",
    messages=[{"content": "What can you help me with?"}],
    stream=True,
)
for text in stream.text():
    print(text, end="", flush=True)

Use collect() to drain the stream and return the full content as a single string:

stream = pc.assistants.chat_completions(
    assistant_name="acme-support-bot",
    messages=[{"content": "Summarize your capabilities."}],
    stream=True,
)
full_content = stream.collect()
Parameters:

stream (Iterator[ChatCompletionStreamChunk])

__init__(stream)[source]
Parameters:

stream (Iterator[ChatCompletionStreamChunk])

Return type:

None

collect()[source]

Drain the stream and return all content fragments concatenated.

Returns:

The complete response as a single string.

Return type:

str

Examples

from pinecone import Pinecone
pc = Pinecone(api_key="your-api-key")
stream = pc.assistants.chat_completions(
    assistant_name="acme-support-bot",
    messages=[{"content": "Explain vector databases in one sentence."}],
    stream=True,
)
full = stream.collect()
print(full)
text()[source]

Yield non-empty content strings, skipping role-only and finish chunks.

Returns:

Iterator of non-empty text fragment strings. Role-only chunks and finish-reason chunks with None or empty content are skipped.

Return type:

Iterator[str]

Examples

from pinecone import Pinecone
pc = Pinecone(api_key="your-api-key")
stream = pc.assistants.chat_completions(
    assistant_name="acme-support-bot",
    messages=[{"content": "Explain vector databases in one sentence."}],
    stream=True,
)
for chunk_text in stream.text():
    print(chunk_text, end="", flush=True)
class pinecone.models.assistant.streaming.ChatCompletionStreamChunk(*, id, choices, model=None, object=None, created=None, system_fingerprint=None)[source]

Bases: StructDictMixin, Struct

A streaming chunk from the OpenAI-compatible chat completion endpoint.

Variables:

  • id (str) – Unique identifier for this chunk.

  • choices (list[pinecone.models.assistant.streaming.ChatCompletionStreamChoice]) – List of streaming choices.

  • model (str | None) – The model used to generate the response, or None if not provided.

  • object (str | None) – The object type (typically "chat.completion.chunk"), or None.

  • created (int | None) – Unix timestamp when the chunk was created, or None.

  • system_fingerprint (str | None) – Opaque fingerprint identifying the backend, or None.

Parameters:

  • id (str)

  • choices (list[ChatCompletionStreamChoice])

  • model (str | None)

  • object (str | None)

  • created (int | None)

  • system_fingerprint (str | None)

choices: list[ChatCompletionStreamChoice]
created: int | None
id: str
model: str | None
object: str | None
system_fingerprint: str | None
class pinecone.models.assistant.streaming.StreamMessageStart(*, model, role)[source]

Bases: StructDictMixin, Struct

First chunk in a chat stream, containing the model and role.

Variables:

  • type – Discriminator value "message_start".

  • model (str) – The model used to generate the response.

  • role (str) – The role of the message author (e.g. "assistant").

Parameters:
model: str
role: str
property type: str

Discriminator value, always "message_start".

class pinecone.models.assistant.streaming.StreamMessageEnd(*, id, usage, model=None)[source]

Bases: StructDictMixin, Struct

Final chunk in a chat stream, containing token usage statistics.

Variables:

  • type – Discriminator value "message_end".

  • id (str) – Unique identifier for this chunk.

  • usage (pinecone.models.assistant.chat.ChatUsage) – Token usage statistics for the request.

  • model (str | None) – The model used to generate this response, or None if not provided.

Parameters:

  • id (str)

  • usage (ChatUsage)

  • model (str | None)

id: str
model: str | None
property type: str

Discriminator value, always "message_end".

usage: ChatUsage
class pinecone.models.assistant.streaming.StreamContentChunk(*, id, delta, model=None)[source]

Bases: StructDictMixin, Struct

A content chunk containing a text fragment in a delta object.

Variables:

  • type – Discriminator value "content_chunk".

  • id (str) – Unique identifier for this chunk.

  • delta (pinecone.models.assistant.streaming.StreamContentDelta) – The delta object containing the text fragment.

  • model (str | None) – The model used to generate this response, or None if not provided.

Parameters:

  • id (str)

  • delta (StreamContentDelta)

  • model (str | None)

delta: StreamContentDelta
id: str
model: str | None
property type: str

Discriminator value, always "content_chunk".

class pinecone.models.assistant.streaming.StreamCitationChunk(*, id, citation, model=None)[source]

Bases: StructDictMixin, Struct

A citation chunk linking response text to source references.

Variables:

  • type – Discriminator value "citation".

  • id (str) – Unique identifier for this chunk.

  • citation (pinecone.models.assistant.chat.ChatCitation) – The citation data with position and references.

  • model (str | None) – The model used to generate this response, or None if not provided.

Parameters:

  • id (str)

  • citation (ChatCitation)

  • model (str | None)

citation: ChatCitation
id: str
model: str | None
property type: str

Discriminator value, always "citation".

class pinecone.models.assistant.streaming.AsyncChatStream(stream)[source]

Bases: object

Async version of ChatStream for use with AsyncPinecone.

The stream is single-pass: iterating, calling text(), or calling collect() all consume the same underlying async iterator.

Examples

import asyncio
from pinecone import Pinecone
pc = Pinecone(api_key="your-api-key")
async def main() -> None:
    stream = await pc.assistants.chat(
        assistant_name="acme-support-bot",
        messages=[{"content": "What can you help me with?"}],
        stream=True,
    )
    async for text in stream.text():
        print(text, end="", flush=True)
asyncio.run(main())

Use collect() to drain the stream and return the full content as a single string:

async def main() -> None:
    stream = await pc.assistants.chat(
        assistant_name="acme-support-bot",
        messages=[{"content": "Summarize your capabilities."}],
        stream=True,
    )
    full_content = await stream.collect()
asyncio.run(main())
Parameters:

stream (AsyncIterator[ChatStreamChunk])

__init__(stream)[source]
Parameters:

stream (AsyncIterator[StreamMessageStart | StreamContentChunk | StreamCitationChunk | StreamMessageEnd])

Return type:

None

async collect()[source]

Drain the stream and return all content fragments concatenated.

Returns:

The complete response as a single string.

Return type:

str

Examples

import asyncio
from pinecone import Pinecone
pc = Pinecone(api_key="your-api-key")
async def main() -> None:
    stream = await pc.assistants.chat(
        assistant_name="acme-support-bot",
        messages=[{"content": "Explain vector databases in one sentence."}],
        stream=True,
    )
    full = await stream.collect()
    print(full)
asyncio.run(main())
async text()[source]

Yield text fragments, skipping start/citation/end chunks.

Returns:

Async iterator of text fragment strings. Each fragment is a partial response as it arrives from the server.

Return type:

AsyncIterator[str]

Examples

import asyncio
from pinecone import Pinecone
pc = Pinecone(api_key="your-api-key")
async def main() -> None:
    stream = await pc.assistants.chat(
        assistant_name="acme-support-bot",
        messages=[{"content": "Explain vector databases in one sentence."}],
        stream=True,
    )
    async for chunk_text in stream.text():
        print(chunk_text, end="", flush=True)
asyncio.run(main())
class pinecone.models.assistant.streaming.AsyncChatCompletionStream(stream)[source]

Bases: object

Async version of ChatCompletionStream for use with AsyncPinecone.

The stream is single-pass: iterating, calling text(), or calling collect() all consume the same underlying async iterator.

Examples

import asyncio
from pinecone import Pinecone
pc = Pinecone(api_key="your-api-key")
async def main() -> None:
    stream = await pc.assistants.chat_completions(
        assistant_name="acme-support-bot",
        messages=[{"content": "What can you help me with?"}],
        stream=True,
    )
    async for text in stream.text():
        print(text, end="", flush=True)
asyncio.run(main())

Use collect() to drain the stream and return the full content as a single string:

async def main() -> None:
    stream = await pc.assistants.chat_completions(
        assistant_name="acme-support-bot",
        messages=[{"content": "Summarize your capabilities."}],
        stream=True,
    )
    full_content = await stream.collect()
asyncio.run(main())
Parameters:

stream (AsyncIterator[ChatCompletionStreamChunk])

__init__(stream)[source]
Parameters:

stream (AsyncIterator[ChatCompletionStreamChunk])

Return type:

None

async collect()[source]

Drain the stream and return all content fragments concatenated.

Returns:

The complete response as a single string.

Return type:

str

Examples

import asyncio
from pinecone import Pinecone
pc = Pinecone(api_key="your-api-key")
async def main() -> None:
    stream = await pc.assistants.chat_completions(
        assistant_name="acme-support-bot",
        messages=[{"content": "Explain vector databases in one sentence."}],
        stream=True,
    )
    full = await stream.collect()
    print(full)
asyncio.run(main())
async text()[source]

Yield non-empty content strings, skipping role-only and finish chunks.

Returns:

Async iterator of non-empty text fragment strings. Role-only chunks and finish-reason chunks with None or empty content are skipped.

Return type:

AsyncIterator[str]

Examples

import asyncio
from pinecone import Pinecone
pc = Pinecone(api_key="your-api-key")
async def main() -> None:
    stream = await pc.assistants.chat_completions(
        assistant_name="acme-support-bot",
        messages=[{"content": "Explain vector databases in one sentence."}],
        stream=True,
    )
    async for chunk_text in stream.text():
        print(chunk_text, end="", flush=True)
asyncio.run(main())

Filter Builder

class pinecone.utils.filter_builder.Field(name)[source]

Bases: object

Represents a metadata field name for building filter expressions.

Usage:

Field("genre") == "drama"       # {"genre": {"$eq": "drama"}}
Field("score").gt(0.5)           # {"score": {"$gt": 0.5}}
Parameters:

name (str)

__init__(name)[source]
Parameters:

name (str)

Return type:

None

exists()[source]

$exists — field exists.

Return type:

Condition

gt(value)[source]

$gt — greater than (numeric only).

Parameters:

value (int | float)

Return type:

Condition

gte(value)[source]

$gte — greater than or equal (numeric only).

Parameters:

value (int | float)

Return type:

Condition

is_in(values)[source]

$in — value is in the given list.

Parameters:

values (list[str | int | float | bool])

Return type:

Condition

lt(value)[source]

$lt — less than (numeric only).

Parameters:

value (int | float)

Return type:

Condition

lte(value)[source]

$lte — less than or equal (numeric only).

Parameters:

value (int | float)

Return type:

Condition

not_in(values)[source]

$nin — value is not in the given list.

Parameters:

values (list[str | int | float | bool])

Return type:

Condition

pinecone.utils.filter_builder.FilterBuilder

alias of Field