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, status, schema, deployment, deletion_protection, host=None, read_capacity=None, tags=None, private_host=None, source_collection=None, source_backup_id=None, cmek_id=None)[source]

Bases: Struct

Response model for a Pinecone index (2026-07 API).

Variables:
Parameters:
cmek_id: str | None
deletion_protection: str
deployment: ManagedDeployment | PodDeployment | ByocDeployment
property dimension: int

Deprecated. Use index.schema.fields["<field-name>"].dimension instead.

host: str | None
property metric: str

Deprecated. Use index.schema.fields["<field-name>"].metric instead.

name: str
private_host: str | None
read_capacity: ReadCapacityOnDemandResponse | ReadCapacityDedicatedResponse | None
schema: IndexSchema
source_backup_id: str | None
source_collection: str | None
status: IndexStatus
tags: dict[str, str] | None
to_dict()[source]

Return a plain dict representation, recursively converting nested fields.

Nested structs (status, schema, deployment, read_capacity) become plain dicts. Tagged-union members include their discriminator key (deployment_type, mode, type); legacy untyped schema fields are emitted without a type key, matching the wire format. Optional fields that are None are included with their None values.

Return type:

dict[str, Any]

property vector_type: str

Deprecated. Inspect index.schema.fields field types instead.

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.IndexStatus(*, ready, state)[source]

Bases: StructDictMixin, Struct

Status of an index.

Variables:

  • ready (bool) – Whether the index is ready to accept requests.

  • state (str) – Current state of the index. Possible values: "Initializing", "InitializationFailed", "ScalingUp", "ScalingDown", "ScalingUpPodSize", "ScalingDownPodSize", "Terminating", "Ready", or "Disabled".

Parameters:
ready: bool
state: str
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, dimension=None, 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"}).

  • dimension (int | None) – Optional dimension hint or override for the embedding model. When absent the backend infers the dimension from the model.

  • 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:
dimension: int | None
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.requests.CreateIndexRequest(*, schema, name=None, deployment=None, read_capacity=None, deletion_protection=None, tags=None, source_collection=None, source_backup_id=None, cmek_id=None)[source]

Bases: Struct

Request model for creating an index.

Variables:

  • schema (dict[str, Any] | pinecone.models.indexes.schema.IndexSchema) – Index schema definition (required). Maps field names to searched-field configurations — dense_vector, sparse_vector, or string with full_text_search.

  • name (str | None) – Optional name for the index. Auto-generated by the server if omitted.

  • deployment (dict[str, Any] | pinecone.models.indexes.deployment.ManagedDeployment | pinecone.models.indexes.deployment.PodDeployment | pinecone.models.indexes.deployment.ByocDeployment | None) – Optional deployment configuration, discriminated on deployment_type (managed | pod | byoc). Defaults server-side to managed on AWS us-east-1.

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

  • deletion_protection (str | None) – Optional deletion protection setting ("enabled" or "disabled").

  • tags (dict[str, str] | None) – Optional key-value tags for the index.

  • source_collection (str | None) – Optional name of an existing collection to create the index from.

  • source_backup_id (str | None) – Optional ID of an existing backup to create the index from.

  • cmek_id (str | None) – Optional customer-managed encryption key ID (valid for managed/BYOC indexes without full-text search fields).

Raises:

PineconeValueError – If deployment names a deployment_type that is not one of the discriminator values. The comparison is case-sensitive, so "MANAGED" is rejected.

Parameters:
cmek_id: str | None
deletion_protection: str | None
deployment: dict[str, Any] | ManagedDeployment | PodDeployment | ByocDeployment | None
name: str | None
read_capacity: dict[str, Any] | None
schema: dict[str, Any] | IndexSchema
source_backup_id: str | None
source_collection: str | None
tags: dict[str, str] | None
class pinecone.models.indexes.requests.ConfigureIndexRequest(*, schema=None, deployment=None, read_capacity=None, deletion_protection=None, tags=None)[source]

Bases: Struct

Request model for configuring an existing index.

All fields are optional — only provided fields are updated, and unset fields are omitted from the PATCH body entirely.

Variables:

  • schema (dict[str, Any] | pinecone.models.indexes.schema.IndexSchema | None) – Optional schema updates (semantic_text field parameters only).

  • deployment (dict[str, Any] | None) – Optional deployment updates for pod-based indexes (replicas and/or pod_type; no deployment_type key).

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

  • deletion_protection (str | None) – Optional updated deletion protection setting.

  • tags (dict[str, str] | None) – Optional tag updates. Merged with existing tags; set a value to "" to delete that tag key.

Parameters:
deletion_protection: str | None
deployment: dict[str, Any] | None
read_capacity: dict[str, Any] | None
schema: dict[str, Any] | IndexSchema | None
tags: dict[str, str] | None

Index Schema Models

IndexModel.schema describes every field in the index. These types replace the removed IndexModel.dimension, .metric, .vector_type and .embed attributes.

class pinecone.models.indexes.schema.IndexSchema(*, fields)[source]

Bases: Struct

Index schema definition.

The schema defines all fields in the index, including vector, text, and metadata fields.

Variables:

fields (dict[str, pinecone.models.indexes.schema.DenseVectorField | pinecone.models.indexes.schema.SparseVectorField | pinecone.models.indexes.schema.SemanticTextField | pinecone.models.indexes.schema.StringField | pinecone.models.indexes.schema.StringListField | pinecone.models.indexes.schema.BooleanField | pinecone.models.indexes.schema.IntegerField | pinecone.models.indexes.schema.FloatField | pinecone.models.indexes.schema.LegacyMetadataField]) – Mapping of field name to its typed field definition.

Parameters:

fields (dict[str, DenseVectorField | SparseVectorField | SemanticTextField | StringField | StringListField | BooleanField | IntegerField | FloatField | LegacyMetadataField])

fields: dict[str, DenseVectorField | SparseVectorField | SemanticTextField | StringField | StringListField | BooleanField | IntegerField | FloatField | LegacyMetadataField]
to_dict()[source]

Return a plain dict representation.

Typed fields include their type discriminator; legacy untyped fields are emitted without a type key, matching the wire format.

Return type:

dict[str, Any]

pinecone.models.indexes.schema.IndexSchemaField = pinecone.models.indexes.schema.DenseVectorField | pinecone.models.indexes.schema.SparseVectorField | pinecone.models.indexes.schema.SemanticTextField | pinecone.models.indexes.schema.StringField | pinecone.models.indexes.schema.StringListField | pinecone.models.indexes.schema.BooleanField | pinecone.models.indexes.schema.IntegerField | pinecone.models.indexes.schema.FloatField | pinecone.models.indexes.schema.LegacyMetadataField

Union of all schema field types appearing in index responses. Use this as the decode target when parsing a single field from JSON.

class pinecone.models.indexes.schema.DenseVectorField(*, dimension, metric, description=None)[source]

Bases: Struct

Dense vector field definition.

Dense vectors are fixed-length floating-point vectors used for approximate nearest-neighbor (ANN) similarity search.

Variables:

  • dimension (int) – Number of dimensions in the vector (1-20000).

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

  • description (str | None) – Optional human-readable description of the field. Always present in responses; None when no description was given.

Parameters:

  • dimension (int)

  • metric (str)

  • description (str | None)

Note

The type field is automatically set to "dense_vector" by msgspec’s tagged union system and should not be included explicitly.

description: str | None
dimension: int
metric: str
class pinecone.models.indexes.schema.SparseVectorField(*, description=None)[source]

Bases: Struct

Sparse vector field definition.

Sparse vectors represent most values as zero and are stored as (indices, values) pairs. Useful for keyword-based search (e.g. BM25).

Variables:

description (str | None) – Optional human-readable description of the field.

Parameters:

description (str | None)

Note

The type field is automatically set to "sparse_vector" by msgspec’s tagged union system.

description: str | None
class pinecone.models.indexes.schema.SemanticTextField(*, model, metric=None, description=None, read_parameters=None, write_parameters=None)[source]

Bases: Struct

Semantic text field with integrated embedding.

Semantic text fields automatically embed text using a specified model, eliminating the need to generate embeddings separately. In the 2026-07 API this field type cannot be declared at index creation; it appears in responses for indexes that already carry one (including indexes created via create_index_for_model).

Variables:

  • model (str) – Embedding model name (e.g. "multilingual-e5-large").

  • metric (str | None) – Distance metric ("cosine", "dotproduct", or "euclidean"), or None to use the model default.

  • description (str | None) – Optional human-readable description of the field.

  • read_parameters (dict[str, Any] | None) – Parameters forwarded to the embedding model on read operations (e.g. {"input_type": "query"}), or None.

  • write_parameters (dict[str, Any] | None) – Parameters forwarded to the embedding model on write operations (e.g. {"input_type": "passage"}), or None.

Parameters:

Note

The type field is automatically set to "semantic_text" by msgspec’s tagged union system.

description: str | None
metric: str | None
model: str
read_parameters: dict[str, Any] | None
write_parameters: dict[str, Any] | None
class pinecone.models.indexes.schema.StringField(*, description=None, filterable=False, full_text_search=None)[source]

Bases: Struct

String field for full-text search or metadata filtering.

In responses, string fields configured for full-text search include a full_text_search object; string fields used for metadata filtering only include a filterable flag. At index creation, a string field must include full_text_search — metadata-only fields are not declared in the schema (pass them as record metadata instead).

Variables:

  • description (str | None) – Optional human-readable description of the field.

  • filterable (bool) – Whether the field can be used in metadata filters. Defaults to False. On create a string field is either searchable or filterable, never both: passing filterable=True alongside full_text_search makes the server keep the filter and discard the search configuration, and it reports no error for doing so.

  • full_text_search (pinecone.models.indexes.schema.FullTextSearchConfig | None) – Full-text search configuration. Presence (even an empty config) indicates the field is full-text searchable; absence (None) means it is not.

Parameters:

Note

The type field is automatically set to "string" by msgspec’s tagged union system.

description: str | None
filterable: bool
full_text_search: FullTextSearchConfig | None
class pinecone.models.indexes.schema.StringListField(*, description=None, filterable=False)[source]

Bases: Struct

List-of-strings field for metadata filtering.

Stores a list of strings per record — useful for tag-style metadata (e.g. ["sci-fi", "mystery"]) that should be filterable against individual elements. Not declared at index creation; appears in responses for fields indexed automatically at upsert time.

Variables:

  • description (str | None) – Optional human-readable description of the field.

  • filterable (bool) – Whether the field can be used in metadata filters. Defaults to False.

Parameters:

  • description (str | None)

  • filterable (bool)

Note

The type field is automatically set to "string_list" by msgspec’s tagged union system.

description: str | None
filterable: bool
class pinecone.models.indexes.schema.BooleanField(*, description=None, filterable=False)[source]

Bases: Struct

Boolean field for metadata filtering.

Not declared at index creation; appears in responses for fields indexed automatically at upsert time.

Variables:

  • description (str | None) – Optional human-readable description.

  • filterable (bool) – Whether the field can be used in metadata filters.

Parameters:

  • description (str | None)

  • filterable (bool)

Note

The type field is automatically set to "boolean" by msgspec’s tagged union system.

description: str | None
filterable: bool
class pinecone.models.indexes.schema.IntegerField(*, description=None, filterable=False)[source]

Bases: Struct

Legacy integer field. Response-only — not accepted on create.

Numeric values are normalised to float at upsert time in current indexes; integer appears only in responses for indexes that pre-date that normalisation.

Important

The 2026-07 create-index schema has no integer field type. Sending one is rejected by the server with a 422 whose body is plain text, not a structured API error. A describe-then-create round-trip must therefore drop integer fields (numeric metadata is indexed for filtering automatically at upsert time) or re-declare them as float. SchemaBuilder offers no method for this type and refuses {"type": "integer"} passed through add_custom_field(), so the failure surfaces client-side with an explanation.

Variables:

  • description (str | None) – Optional human-readable description.

  • filterable (bool) – Whether the field can be used in metadata filters.

Parameters:

  • description (str | None)

  • filterable (bool)

Note

The type field is automatically set to "integer" by msgspec’s tagged union system.

description: str | None
filterable: bool
class pinecone.models.indexes.schema.FloatField(*, description=None, filterable=False)[source]

Bases: Struct

Numeric (float) field for metadata filtering.

Numeric fields store double-precision floating-point values and can be used for range filtering (e.g. year >= 2020). Create schemas have no separate integer type — integers are stored and filtered as floats, and float is the only numeric type name the API accepts. Not declared at index creation on managed or BYOC indexes; appears in responses for fields indexed automatically at upsert time.

Variables:

  • description (str | None) – Optional human-readable description of the field.

  • filterable (bool) – Whether the field can be used in metadata filters. Defaults to False.

Parameters:

  • description (str | None)

  • filterable (bool)

Note

The type field is automatically set to "float" by msgspec’s tagged union system.

description: str | None
filterable: bool
class pinecone.models.indexes.schema.LegacyMetadataField(*, filterable)[source]

Bases: Struct

Untyped metadata field from indexes that pre-date typed schemas.

The original data type of the field (string, float, boolean, etc.) was not recorded — only the filterable flag is available. On the wire these fields carry no type key. This field type never appears in new indexes.

Variables:

filterable (bool) – Whether the field is indexed for metadata filtering.

Parameters:

filterable (bool)

Note

msgspec requires a discriminator for union decoding, so this class carries the internal tag "__untyped__". The tag is an SDK artifact: it is stripped by IndexSchema.to_dict() and never appears in API traffic, but msgspec.json.encode output of this class does include it.

filterable: bool
class pinecone.models.indexes.schema.FullTextSearchConfig(*, language=None, stemming=None, stop_words=None, ngram=None)[source]

Bases: Struct

Full-text search configuration for a string field.

Presence of this object on a StringField indicates the field is full-text searchable; absence means it is not. All keys are optional on create — an empty config (FullTextSearchConfig()) is valid and requests the server defaults. Responses always carry language, stemming, and stop_words.

Variables:

  • language (str | None) – Language used for text analysis, as a two-letter code or English name (e.g. "en" or "english"). When None, the server applies its default ("en").

  • stemming (bool | None) – Whether to stem tokens to root form during indexing. When None, the server applies its default (False).

  • stop_words (bool | None) – Whether to filter stop words during indexing. Requires stemming=True. When None, the server applies its default (False).

  • ngram (pinecone.models.indexes.schema.NgramConfig | None) – Character n-gram tokenization configuration, or None for word-based tokenization. Cannot be combined with stemming or stop_words.

Parameters:
language: str | None
ngram: NgramConfig | None
stemming: bool | None
stop_words: bool | None
class pinecone.models.indexes.schema.NgramConfig(*, min_gram, max_gram, prefix_only=False)[source]

Bases: Struct

Character n-gram tokenization configuration for a string field.

When present, the field is tokenized into character n-grams instead of words (useful for substring matching and autocomplete). Cannot be combined with stemming or stop_words.

Variables:

  • min_gram (int) – Minimum n-gram length (1-10, no greater than max_gram).

  • max_gram (int) – Maximum n-gram length (1-10, no less than min_gram).

  • prefix_only (bool) – When True, only prefix n-grams anchored at the start of the token are generated. Defaults to False.

Parameters:

  • min_gram (int)

  • max_gram (int)

  • prefix_only (bool)

max_gram: int
min_gram: int
prefix_only: bool

Index Deployment Models

IndexModel.deployment describes where and how the index runs. These types replace the removed IndexSpec, ServerlessSpecInfo, PodSpecInfo and ByocSpecInfo.

pinecone.models.indexes.deployment.IndexDeployment = pinecone.models.indexes.deployment.ManagedDeployment | pinecone.models.indexes.deployment.PodDeployment | pinecone.models.indexes.deployment.ByocDeployment

Union of all deployment variants, dispatched on the deployment_type field.

class pinecone.models.indexes.deployment.ManagedDeployment(*, cloud, region, environment=None)[source]

Bases: Struct

Managed (serverless) deployment configuration.

Serverless indexes scale automatically and are billed per usage. This deployment type also covers full-text search indexes.

Variables:

  • cloud (str) – Cloud provider — "aws", "gcp", or "azure".

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

  • environment (str | None) – The internal environment (cell) hosting the index, derived from cloud and region. Response-only and informational — it cannot be set on create and is not stable API surface.

Parameters:

  • cloud (str)

  • region (str)

  • environment (str | None)

Note

The deployment_type field is automatically set to "managed" by msgspec’s tagged union system.

cloud: str
environment: str | None
region: str
class pinecone.models.indexes.deployment.PodDeployment(*, environment, pod_type, replicas, shards)[source]

Bases: Struct

Pod-based deployment configuration.

All properties are required on create — omitting replicas or shards is rejected with a 422. Responses always carry all of them as well.

Variables:

  • environment (str) – Environment where the index is hosted (e.g. "us-east1-gcp").

  • pod_type (str) – Pod type — one of s1, p1, or p2 appended with . and one of x1, x2, x4, or x8 (e.g. "p1.x1").

  • replicas (int) – Number of replicas. Replicas duplicate the index for higher availability and throughput.

  • shards (int) – Number of shards. Shards split data across multiple pods to fit more data into an index.

Parameters:

  • environment (str)

  • pod_type (str)

  • replicas (int)

  • shards (int)

Note

The deployment_type field is automatically set to "pod" by msgspec’s tagged union system.

environment: str
pod_type: str
replicas: int
shards: int
class pinecone.models.indexes.deployment.ByocDeployment(*, environment)[source]

Bases: Struct

Bring-your-own-compute (BYOC) deployment configuration.

BYOC indexes run in customer-managed infrastructure.

Variables:

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

Parameters:

environment (str)

Note

The deployment_type field is automatically set to "byoc" by msgspec’s tagged union system.

environment: str

Read Capacity Models

IndexModel.read_capacity replaces the removed IndexSpec.serverless.read_capacity.

pinecone.models.indexes.read_capacity.ReadCapacityResponse = pinecone.models.indexes.read_capacity.ReadCapacityOnDemandResponse | pinecone.models.indexes.read_capacity.ReadCapacityDedicatedResponse

Union of read-capacity response variants, dispatched on the mode field.

class pinecone.models.indexes.read_capacity.ReadCapacityOnDemandResponse(*, status)[source]

Bases: Struct

On-demand read capacity in API responses.

Variables:

status (pinecone.models.indexes.read_capacity.ReadCapacityStatus) – Current provisioning status.

Parameters:

status (ReadCapacityStatus)

Note

The mode field is automatically set to "OnDemand" by msgspec’s tagged-union system.

status: ReadCapacityStatus
class pinecone.models.indexes.read_capacity.ReadCapacityDedicatedResponse(*, dedicated, status)[source]

Bases: Struct

Dedicated read capacity in API responses.

Variables:
Parameters:

Note

The mode field is automatically set to "Dedicated" by msgspec’s tagged-union system.

dedicated: ReadCapacityDedicatedConfig
status: ReadCapacityStatus
class pinecone.models.indexes.read_capacity.ReadCapacityDedicatedConfig(*, node_type, scaling, manual=None)[source]

Bases: Struct

Dedicated read-capacity configuration details.

Variables:
Parameters:
manual: ScalingConfigManual | None
node_type: str
scaling: str
class pinecone.models.indexes.read_capacity.ReadCapacityStatus(*, state, current_shards=None, current_replicas=None, error_message=None)[source]

Bases: Struct

Read capacity provisioning status.

Variables:

  • state (str) – Current provisioning state — "Ready" most of the time, "Scaling" after a recent replica/shard change, "Migrating" while moving to a new node type, or "Error" (see error_message).

  • current_shards (int | None) – Current number of active shards. None for an index with on-demand read capacity, which has no fixed shard count.

  • current_replicas (int | None) – Current number of active replicas. None for an index with on-demand read capacity, which has no fixed replica count.

  • error_message (str | None) – Message describing a read-capacity configuration issue; None unless state is "Error".

Parameters:

  • state (str)

  • current_shards (int | None)

  • current_replicas (int | None)

  • error_message (str | None)

current_replicas: int | None
current_shards: int | None
error_message: str | None
state: str
class pinecone.models.indexes.read_capacity.ScalingConfigManual(*, shards, replicas)[source]

Bases: Struct

Manual scaling configuration for dedicated read capacity.

Variables:

  • shards (int) – Number of shards. Each shard provides 250 GB of storage.

  • replicas (int) – Number of replicas. Setting replicas to 0 disables the index but can be used to reduce costs while usage is paused.

Parameters:
replicas: int
shards: int

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.

At least one of values or sparse_values must be populated. values is not required on its own: a sparse-only vector leaves it empty, and an empty dense array is still sent so the pair reads as populated.

Variables:

  • id (str) – Unique identifier for the vector. ASCII, 1 to 512 characters, no NUL.

  • values (list[float]) – Dense vector values as a list of floats. Empty for a sparse-only vector.

  • 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. Each value must be a string, a number, a boolean, or a list of strings — nested objects and lists with a non-string element are rejected. A key whose value is None is dropped by the server rather than rejected. Keys may not begin with $, which is reserved for filter operators; every other key is accepted, including empty and non-ASCII keys. The field is typed Any rather than narrowed to that grammar so that decoding a response never fails on a value shape the server has started returning; requests are validated on the way out instead.

Raises:

PineconeValueError – If neither values nor sparse_values is populated.

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.index(name="articles-en")
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. Omitting error_mode selects this.

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, source_index_deleted_at=None, name=None, description=None, schema=None, record_count=None, namespace_count=None, size_bytes=None, tags=None, created_at=None)[source]

Bases: Struct

Response model for a Pinecone backup (2026-07 API).

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 — "Initializing", "Ready", or "Failed".

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

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

  • source_index_deleted_at (str | None) – Timestamp at which the source index was deleted, or None when the source index is still active. Only populated by list_index_backups(include_deleted=True).

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

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

  • schema (pinecone.models.indexes.schema.IndexSchema | None) – Schema captured from the source index, or None when the server returns no schema (e.g. schedule-produced backups of an index that declared none). Legacy metadata-only schemas decode to LegacyMetadataField entries.

  • 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, Any] | None) – User-defined key-value tags, or None when the source index had none (the API returns "tags": null rather than {}).

  • 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)

  • source_index_deleted_at (str | None)

  • name (str | None)

  • description (str | None)

  • schema (IndexSchema | None)

  • record_count (int | None)

  • namespace_count (int | None)

  • size_bytes (int | None)

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

  • created_at (str | None)

backup_id: str
cloud: str
created_at: str | None
property dense_dimension: int | None

Dimension of the backup’s single dense vector field, if there is one.

Returns None when the schema is absent, declares no dense_vector field, or declares more than one — in which case read the dimension off the field you want via schema.fields['<field-name>'].dimension.

description: str | None
name: str | None
namespace_count: int | None
record_count: int | None
region: str
schema: IndexSchema | None
size_bytes: int | None
source_index_deleted_at: str | None
source_index_id: str
source_index_name: str
status: str
tags: dict[str, Any] | 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, record_count, source_index_deleted_at). schema becomes a plain dict; legacy untyped schema fields are emitted without a type key, matching the wire format.

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
>>> d["source_index_deleted_at"] 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=None, 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 | None) – Timestamp when the restore job was created, or None if the backend has not yet assigned a creation timestamp.

  • 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 | None)

  • completed_at (str | None)

  • percent_complete (float | None)

backup_id: str
completed_at: str | None
created_at: str | None
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.CreateIndexFromBackupRequest(*, name, tags=None, deletion_protection=None, read_capacity=None)[source]

Bases: Struct

Request model for creating an index from a backup.

omit_defaults=True keeps unset optionals off the wire, so a request built with only name serialises to {"name": ...} and the server applies its own defaults (on-demand read capacity, deletion protection disabled, the backup’s own tags).

Variables:

  • name (str) – Name for the restored index (required). 1-45 characters, starting and ending with an alphanumeric character.

  • tags (dict[str, str] | None) – Optional key-value tags for the restored index. When omitted, the server copies the backup’s tags.

  • deletion_protection (str | None) – Optional deletion protection setting ("enabled" or "disabled").

  • read_capacity (dict[str, Any] | None) – Optional read capacity configuration, letting the restore land directly on dedicated read nodes instead of defaulting to on-demand capacity.

Parameters:
deletion_protection: str | None
name: str
read_capacity: dict[str, Any] | None
tags: dict[str, str] | None
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

Backup Schedule Models

class pinecone.models.backups.schedules.BackupScheduleModel(*, schedule_id, name, index_id, project_id, schedule_type, frequency, retention_expire_after_days, enabled, created_at, next_scheduled_run=None)[source]

Bases: Struct

Response model for a backup schedule (2026-07 API).

Variables:

  • schedule_id (str) – Unique identifier for the schedule. Used as the path parameter for describe / update / delete / history calls.

  • name (str) – User-defined name for the schedule. Backups it produces are named "{name}-{run timestamp}".

  • index_id (str) – Identifier of the index this schedule backs up. This is the index id, not its name – schedules are created against a name but reported against the id, so a deleted-and-recreated index does not inherit the old schedule.

  • project_id (str) – Project containing the schedule, always the same project as the source index.

  • schedule_type (str) – Schedule category. "time-based" for any schedule created through this SDK, which always sends that value; the server does not constrain the field, so a schedule created by another client can report something else.

  • frequency (str) – Cadence, one of "daily", "weekly", "monthly".

  • retention_expire_after_days (int) – Days each backup produced by this schedule is retained. (The create/update request models spell the same value retention_days, mirroring the request body’s retention.expire_after_days.)

  • enabled (bool) – Whether the schedule is active. A disabled schedule does not run and is not deleted.

  • next_scheduled_run (datetime.datetime | None) – When the next backup is planned, or None. None iff enabled is False: disabling clears the pending run, and re-enabling recomputes it from the moment of the update, so a disable/re-enable cycle shifts the cadence rather than resuming the old slot. The field is documented as always present and sent as null when disabled; it also decodes when absent entirely.

  • created_at (datetime.datetime) – When the schedule was created.

Parameters:

  • schedule_id (str)

  • name (str)

  • index_id (str)

  • project_id (str)

  • schedule_type (str)

  • frequency (str)

  • retention_expire_after_days (int)

  • enabled (bool)

  • created_at (datetime)

  • next_scheduled_run (datetime | None)

Note

Only one enabled schedule may exist per index. Creating a second one fails with a 409 telling you to disable or delete the first; re-enabling a disabled schedule while another is enabled fails the same way.

created_at: datetime
enabled: bool
frequency: str
index_id: str
name: str
next_scheduled_run: datetime | None
project_id: str
retention_expire_after_days: int
schedule_id: str
schedule_type: str
to_dict()[source]

Return a dict representation of this schedule.

Returns:

Dictionary with all fields, including next_scheduled_run when it is None. Timestamps are rendered back to RFC 3339 strings (normalised to UTC Z form), so the result is JSON-serialisable.

Return type:

dict[str, Any]

Examples

>>> from datetime import datetime, timezone
>>> from pinecone.models.backups.schedules import BackupScheduleModel
>>> schedule = BackupScheduleModel(
...     schedule_id="sched-1",
...     name="daily-compliance-backup",
...     index_id="idx-1",
...     project_id="proj-1",
...     schedule_type="time-based",
...     frequency="daily",
...     retention_expire_after_days=90,
...     enabled=False,
...     created_at=datetime(2026, 4, 2, 18, 22, 56, tzinfo=timezone.utc),
... )
>>> schedule.to_dict()["created_at"]
'2026-04-02T18:22:56Z'
>>> schedule.to_dict()["next_scheduled_run"] is None
True
class pinecone.models.backups.list.BackupScheduleList(schedules, *, pagination=None)[source]

Bases: object

Wrapper around a list of BackupScheduleModel with convenience methods.

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

Initialize a BackupScheduleList.

Parameters:

  • schedules (list[BackupScheduleModel]) – List of BackupScheduleModel instances representing the backup schedules on an index.

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

Return type:

None

property data: list[BackupScheduleModel]

Return the list of backup schedules.

enabled_schedules()[source]

Return only the enabled schedules.

At most one schedule per index can be enabled, so this is the answer to “which schedule is actually running”. Named to avoid reading like the enabled flag on BackupScheduleModel, which a bare enabled method would shadow at a glance.

Return type:

list[BackupScheduleModel]

names()[source]

Return the schedule names.

Returns:

Schedule names, in the order the API returned them.

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 schedule dicts, each produced by BackupScheduleModel.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]

class pinecone.models.backups.schedules.BackupScheduleHistoryItem(*, backup_id, source_index_id, source_index_name, status, cloud, region, created_at, scheduled_execution_at=None, name=None, description=None, schema=None, record_count=None, namespace_count=None, size_bytes=None, tags=None)[source]

Bases: Struct

A backup produced by a schedule (2026-07 API).

History rows describe backup snapshots, not the schedule itself. A row appears as soon as a run is planned, so the list mixes runs that have not happened yet with ones that have.

Variables:

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

  • source_index_id (str) – Identifier of the index that was backed up.

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

  • status (str) – Lifecycle status of the snapshot – "Scheduled" (planned, not yet started), "Initializing", "Ready", or "InitializationFailed". Left as a plain str so a value the SDK has not seen before still decodes.

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

  • region (str) – Cloud region where the snapshot is stored.

  • created_at (datetime.datetime) – When the backup record was created – which for a Scheduled row is when the run was planned, not when data was captured.

  • scheduled_execution_at (datetime.datetime | None) – When the run is planned to happen. Present when status is "Scheduled"; None once the run has started, and None on servers that do not report it.

  • name (str | None) – Name of the snapshot, generated as "{schedule name}-{run timestamp}".

  • description (str | None) – Description of the snapshot, or None.

  • schema (pinecone.models.indexes.schema.IndexSchema | None) – Schema captured from the source index, or None when the server reports none. Reuses the typed IndexSchema union; metadata-only schemas from older indexes decode to LegacyMetadataField entries when the payload is routed through decode_backups_envelope.

  • record_count (int | None) – Records in the snapshot. 0 for a Scheduled row – nothing has been captured yet.

  • namespace_count (int | None) – Namespaces in the snapshot.

  • size_bytes (int | None) – Approximate stored size of the snapshot, in bytes.

  • tags (dict[str, Any] | None) – Tags carried over from the source index, or None (the API sends null rather than {} when there are none).

Parameters:

Note

name, record_count, namespace_count and size_bytes are all documented as required, but the backend serves schedule history from its shared backup handler, where each is optional. They are typed as optional here so a real response decodes rather than raising; see the divergence recorded on issue #224.

backup_id: str
cloud: str
created_at: datetime
description: str | None
property is_scheduled: bool

Whether this row is a planned run that has not started yet.

name: str | None
namespace_count: int | None
record_count: int | None
region: str
scheduled_execution_at: datetime | None
schema: IndexSchema | None
size_bytes: int | None
source_index_id: str
source_index_name: str
status: str
tags: dict[str, Any] | None
to_dict()[source]

Return a dict representation of this history row.

Returns:

Dictionary with all fields, including optional ones that are None. Timestamps are rendered back to RFC 3339 strings (normalised to UTC Z form), schema becomes a plain dict with the SDK’s internal untyped-field tag stripped, and the result is JSON-serialisable.

Return type:

dict[str, Any]

class pinecone.models.backups.list.BackupScheduleHistoryList(items, *, pagination=None)[source]

Bases: object

Wrapper around a list of BackupScheduleHistoryItem with convenience methods.

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

Initialize a BackupScheduleHistoryList.

Parameters:

  • items (list[BackupScheduleHistoryItem]) – List of BackupScheduleHistoryItem instances representing backups produced by one schedule.

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

Return type:

None

property data: list[BackupScheduleHistoryItem]

Return the list of history rows.

scheduled()[source]

Return only the rows for runs that have not started yet.

Return type:

list[BackupScheduleHistoryItem]

to_dict()[source]

Return the list as a serializable dict.

Returns:

A dict with a "data" key containing a list of history-row dicts, each produced by BackupScheduleHistoryItem.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]

class pinecone.models.backups.schedules.CreateBackupScheduleRequest(*, name, frequency, retention_days)[source]

Bases: Struct

Request model for creating a backup schedule.

Takes flat keyword arguments and builds the nested request body in to_wire(), filling in schedule.type rather than making every caller repeat the one value the SDK sends.

Variables:

  • name (str) – Name for the schedule (required). Produced backups are named "{name}-{run timestamp}".

  • frequency (str) – Cadence (required), one of "daily", "weekly", "monthly". Validated on construction.

  • retention_days (int) – Days to retain each backup this schedule produces (required). Must be at least 1, which is checked here; the maximum is a per-project setting enforced server-side. Serialised as retention.expire_after_days.

Raises:

ValueError – If frequency is not a supported cadence, or retention_days is less than 1.

Parameters:

  • name (str)

  • frequency (str)

  • retention_days (int)

Examples

>>> from pinecone.models.backups.schedules import CreateBackupScheduleRequest
>>> request = CreateBackupScheduleRequest(
...     name="daily-compliance-backup", frequency="daily", retention_days=90
... )
>>> request.to_wire() == {
...     "name": "daily-compliance-backup",
...     "schedule": {"type": "time-based", "frequency": "daily"},
...     "retention": {"expire_after_days": 90},
... }
True
frequency: str
name: str
retention_days: int
to_wire()[source]

Return the nested JSON body the create-schedule endpoint expects.

This is the encoding entry point for this model: the flat fields do not match the wire shape, so encode to_wire() rather than the struct itself.

Return type:

dict[str, Any]

class pinecone.models.backups.schedules.UpdateBackupScheduleRequest(*, frequency=None, retention_days=None, enabled=None)[source]

Bases: Struct

Request model for updating an existing backup schedule.

Every field is optional; omitted fields are left unchanged. Like CreateBackupScheduleRequest, this takes flat keyword arguments and builds the nested body in to_wire(), which emits only the fields you set. A request with nothing set encodes to {} and is a no-op server-side.

The schedule’s name cannot be changed, and neither can the index it is attached to – the API exposes no field for either.

Variables:

  • frequency (str | None) – New cadence, one of "daily", "weekly", "monthly", or None to leave it unchanged.

  • retention_days (int | None) – New retention window in days, or None to leave it unchanged. Must be at least 1; serialised as retention.expire_after_days. Changing it also re-times the pending deletions of backups this schedule already produced.

  • enabled (bool | None) – False to disable the schedule (clearing its next_scheduled_run), True to re-enable it, or None to leave it unchanged. Re-enabling enqueues a new backup and recomputes the next run from now, so it is not a free toggle; it also fails with a 409 if another schedule on the same index is already enabled.

Raises:

ValueError – If frequency is set to an unsupported cadence, or retention_days is set to less than 1.

Parameters:

  • frequency (str | None)

  • retention_days (int | None)

  • enabled (bool | None)

Examples

>>> from pinecone.models.backups.schedules import UpdateBackupScheduleRequest
>>> UpdateBackupScheduleRequest(enabled=False).to_wire()
{'enabled': False}
>>> UpdateBackupScheduleRequest(frequency="weekly", retention_days=30).to_wire() == {
...     "frequency": "weekly",
...     "retention": {"expire_after_days": 30},
... }
True
enabled: bool | None
frequency: str | None
retention_days: int | None
to_wire()[source]

Return the sparse nested JSON body the update-schedule endpoint expects.

Only the fields you set appear, so unset fields are left unchanged server-side rather than being reset to a default.

Return type:

dict[str, Any]

Namespace Models

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

Bases: StructDictMixin, Struct

Description of a namespace including name, record count, size, 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.

  • size_bytes (int) – The total size of the namespace’s data, in bytes. This is an approximation, not an exact byte count: data written before size tracking was enabled reads as 0, and recently deleted data may still be counted until compaction converges the value. Defaults to 0, which also covers API versions before 2026-07 that omit the field — a 0 therefore does not by itself mean the namespace is empty.

Parameters:

  • name (str)

  • record_count (int)

  • schema (NamespaceSchema | None)

  • indexed_fields (IndexedFields | None)

  • size_bytes (int)

indexed_fields: IndexedFields | None
name: str
record_count: int
schema: NamespaceSchema | None
size_bytes: int
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.

A convenience enum rather than an exhaustive list: model is also accepted as a plain string, so a model added after this SDK release can still be used. Call list_models() for the models currently available.

Llama_Text_Embed_V2 = 'llama-text-embed-v2'
Multilingual_E5_Large = 'multilingual-e5-large'
Pinecone_Sparse_English_V0 = 'pinecone-sparse-english-v0'
Pinecone_Sparse_Multilingual_V0 = 'pinecone-sparse-multilingual-v0'
class pinecone.models.enums.RerankModel(value)[source]

Bases: str, Enum

Known reranking models.

Like EmbedModel, a convenience enum rather than an exhaustive list.

Note

Pinecone_Rerank_V0 is deprecated and most projects can no longer use it: a request naming it is rejected with a permission error whose message points to a current model. Prefer another member of this enum.

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=None, project_id, roles)[source]

Bases: StructDictMixin, Struct

Response model for a Pinecone API key.

Variables:

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

  • name (str | None) – Name of the API key, or None when the backend has no display label set for this key.

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

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

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'>]
id: str
name: str | None
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.

Elements are None for keys whose backend display label is unset.

Return type:

list[str | None]

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) – The organization’s plan tier, as the server names it.

  • 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', ...}]}
class pinecone.models.admin.token.TokenResponse(*, access_token, token_type=None, expires_in=None)[source]

Bases: StructDictMixin, Struct

Response model for the OAuth2 client-credentials token exchange.

Variables:

  • access_token (str) – The Bearer token used to authorize Admin API requests.

  • token_type (str | None) – The type of token issued. "Bearer" in practice.

  • expires_in (int | None) – Seconds until the token expires.

Parameters:

  • access_token (str)

  • token_type (str | None)

  • expires_in (int | None)

access_token: str
expires_in: int | None
token_type: str | None
class pinecone.models.admin.pagination.PaginationResponse(*, next=None)[source]

Bases: StructDictMixin, Struct

Cursor envelope returned by paginated Admin API list responses.

Variables:

next (str | None) – Opaque cursor for the next page, or None when the server did not supply one. The value is never parsed or constructed by the SDK — pass it back verbatim as the pagination_token argument on the following list call.

Parameters:

next (str | None)

Examples

>>> from pinecone.models.admin.pagination import PaginationResponse
>>> page = PaginationResponse(next="eyJsYXN0X2lkIjoiZTJlOTI1MjMifQ==")
>>> page.next
'eyJsYXN0X2lkIjoiZTJlOTI1MjMifQ=='
next: str | None
class pinecone.models.admin.user.UserModel(*, id, email, name=None)[source]

Bases: StructDictMixin, Struct

Response model for a user who is a member of the organization.

Role bindings are not included; use the role binding operations with principal_type="user" to see what a user can do.

Variables:

  • id (str) – Unique identifier (UUID) for the user.

  • email (str) – The user’s email address.

  • name (str | None) – The user’s display name, or None when the user has not set one. The server omits the field entirely in that case.

Parameters:

Examples

>>> from pinecone.models.admin.user import UserModel
>>> user = UserModel(id="e2e92523-85dc-4142-b8c2-e681be8b78df", email="alice@example.com")
>>> user.email
'alice@example.com'
>>> user.name is None
True
email: str
id: str
name: str | None
class pinecone.models.admin.user.UserList(*, data=<factory>, pagination=None)[source]

Bases: Struct

A page of users, plus the cursor for the next page.

Variables:

  • data (list[UserModel]) – The users on this page.

  • pagination (PaginationResponse | None) – Cursor envelope for the next page, or None on the final page.

Parameters:

Examples

>>> from pinecone.models.admin.user import UserList, UserModel
>>> users = UserList(data=[UserModel(id="u1", email="alice@example.com")])
>>> len(users)
1
>>> users.has_more
False
>>> users.emails()
['alice@example.com']
data: list[UserModel]
emails()[source]

Return the email addresses on this page, in order.

Return type:

list[str]

property has_more: bool

True when the server supplied a cursor for a further page.

pagination: PaginationResponse | None
property pagination_token: str | None

Opaque cursor for the next page, or None if this is the last page.

to_dict()[source]

Return this page as a serializable dict with data and pagination keys.

Return type:

dict[str, Any]

class pinecone.models.admin.invite.InviteModel(*, id, email, status, expires_at=None, processed_at=None, created_at)[source]

Bases: StructDictMixin, Struct

Response model for an invitation to join the organization.

status is typed as str rather than InviteStatus so a status added by the server after this SDK release surfaces as its raw string instead of raising. Compare against InviteStatus members directly — they are str values.

Variables:

  • id (str) – Unique identifier (UUID) for the invite.

  • email (str) – The email address the invite was sent to.

  • status (str) – One of the InviteStatus values.

  • expires_at (str | None) – RFC 3339 timestamp for when the invite expires if not accepted, or None if it does not expire. Resending an invite pushes this further out; read the new value from the resend response rather than computing it.

  • processed_at (str | None) – RFC 3339 timestamp for when the invite was accepted. None (or omitted by the server) while the invite is still pending or expired.

  • created_at (str) – RFC 3339 timestamp for when the invite was created.

Parameters:

  • id (str)

  • email (str)

  • status (str)

  • expires_at (str | None)

  • processed_at (str | None)

  • created_at (str)

Examples

>>> from pinecone.models.admin.invite import InviteModel, InviteStatus
>>> invite = InviteModel(
...     id="9c8e3528-b9c0-4358-84ce-84c28e91b566",
...     email="newhire@acme.com",
...     status="pending",
...     expires_at="2026-05-21T03:00:00Z",
...     created_at="2026-04-14T20:00:00Z",
... )
>>> invite.status == InviteStatus.PENDING
True
>>> invite.processed_at is None
True
created_at: str
email: str
expires_at: str | None
id: str
processed_at: str | None
status: str
class pinecone.models.admin.invite.InviteList(*, data=<factory>, pagination=None)[source]

Bases: Struct

A page of invites, plus the cursor for the next page.

Variables:
Parameters:

Examples

>>> from pinecone.models.admin.invite import InviteList, InviteModel
>>> invites = InviteList(
...     data=[
...         InviteModel(
...             id="i1",
...             email="newhire@acme.com",
...             status="pending",
...             created_at="2026-04-14T20:00:00Z",
...         )
...     ]
... )
>>> invites.emails()
['newhire@acme.com']
data: list[InviteModel]
emails()[source]

Return the invited email addresses on this page, in order.

Return type:

list[str]

property has_more: bool

True when the server supplied a cursor for a further page.

pagination: PaginationResponse | None
property pagination_token: str | None

Opaque cursor for the next page, or None if this is the last page.

to_dict()[source]

Return this page as a serializable dict with data and pagination keys.

Return type:

dict[str, Any]

class pinecone.models.admin.invite.InviteStatus(value)[source]

Bases: str, Enum

The lifecycle status of an organization invite.

Possible values: pending, expired, processed.

List operations return only pending and expired invites; processed is returned only when fetching a single invite by ID.

Examples

>>> from pinecone.models.admin.invite import InviteStatus
>>> InviteStatus.PENDING == "pending"
True
EXPIRED = 'expired'
PENDING = 'pending'
PROCESSED = 'processed'
class pinecone.models.admin.service_account.ServiceAccountModel(*, id, name, client_id, created_at, updated_at)[source]

Bases: StructDictMixin, Struct

Response model for a service account. The OAuth secret is not included.

Role bindings are not included; use the role binding operations with principal_type="service_account" to see what the account can do.

Variables:

  • id (str) – Unique identifier (UUID) for the service account. Use this as the path parameter on service account operations and as the principal_id when querying or creating role bindings.

  • name (str) – Short human-readable label set at creation time.

  • client_id (str) – OAuth client ID the service account uses to obtain access tokens. Used only for OAuth token exchange — it is not the service account’s identifier for role bindings.

  • created_at (str) – RFC 3339 timestamp for when the account was created.

  • updated_at (str) – RFC 3339 timestamp of the most recent metadata update.

Parameters:

Examples

>>> from pinecone.models.admin.service_account import ServiceAccountModel
>>> account = ServiceAccountModel(
...     id="f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
...     name="My Service Account",
...     client_id="l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn",
...     created_at="2026-04-10T15:23:00Z",
...     updated_at="2026-04-12T09:11:00Z",
... )
>>> account.name
'My Service Account'
client_id: str
created_at: str
id: str
name: str
updated_at: str
class pinecone.models.admin.service_account.ServiceAccountList(*, data=<factory>, pagination=None)[source]

Bases: Struct

A page of service accounts, plus the cursor for the next page.

Variables:
Parameters:

Examples

>>> from pinecone.models.admin.service_account import (
...     ServiceAccountList,
...     ServiceAccountModel,
... )
>>> accounts = ServiceAccountList(
...     data=[
...         ServiceAccountModel(
...             id="sa1",
...             name="ci-prod",
...             client_id="cid",
...             created_at="2026-04-10T15:23:00Z",
...             updated_at="2026-04-10T15:23:00Z",
...         )
...     ]
... )
>>> accounts.names()
['ci-prod']
data: list[ServiceAccountModel]
property has_more: bool

True when the server supplied a cursor for a further page.

names()[source]

Return the service account names on this page, in order.

Return type:

list[str]

pagination: PaginationResponse | None
property pagination_token: str | None

Opaque cursor for the next page, or None if this is the last page.

to_dict()[source]

Return this page as a serializable dict with data and pagination keys.

Return type:

dict[str, Any]

class pinecone.models.admin.service_account.ServiceAccountWithSecret(*, service_account, client_secret)[source]

Bases: StructDictMixin, Struct

Response model for a service account with a newly issued OAuth secret.

The secret is returned exactly once — at creation and on secret rotation — and cannot be retrieved later. __repr__() masks it so it does not leak into logs; to_dict() and JSON encoding return it in full.

Variables:

  • service_account (ServiceAccountModel) – The service account metadata.

  • client_secret (str) – The OAuth client secret. Treat as a credential.

Parameters:

Examples

>>> from pinecone.models.admin.service_account import (
...     ServiceAccountModel,
...     ServiceAccountWithSecret,
... )
>>> created = ServiceAccountWithSecret(
...     service_account=ServiceAccountModel(
...         id="sa1",
...         name="ci-prod",
...         client_id="cid",
...         created_at="2026-04-10T15:23:00Z",
...         updated_at="2026-04-10T15:23:00Z",
...     ),
...     client_secret="8p-kkC23XOWvkCosKq",
... )
>>> created.client_secret
'8p-kkC23XOWvkCosKq'
>>> repr(created).endswith("client_secret='...osKq')")
True
client_secret: str
service_account: ServiceAccountModel
class pinecone.models.admin.role_binding.RoleBindingModel(*, id, principal_type, principal_id, resource_type, resource_id, role, created_at)[source]

Bases: StructDictMixin, Struct

Response model for a role binding: a role granted to a principal at a scope.

principal_type, resource_type, and role are typed as str rather than as enums so values the server adds after this SDK release surface as their raw strings instead of raising. Compare against PrincipalType, ResourceType, and RoleName directly — they are str values.

Variables:

  • id (str) – Unique identifier (UUID) for the role binding.

  • principal_type (str) – One of the PrincipalType values.

  • principal_id (str) – The principal’s UUID.

  • resource_type (str) – One of the ResourceType values.

  • resource_id (str) – The organization or project the binding is scoped to.

  • role (str) – One of the RoleName values.

  • created_at (str) – RFC 3339 timestamp for when the binding was created.

Parameters:

  • id (str)

  • principal_type (str)

  • principal_id (str)

  • resource_type (str)

  • resource_id (str)

  • role (str)

  • created_at (str)

Examples

>>> from pinecone.models.admin.role_binding import RoleBindingModel, RoleName
>>> binding = RoleBindingModel(
...     id="9a8e3528-b9c0-4358-84ce-84c28e91b566",
...     principal_type="service_account",
...     principal_id="f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
...     resource_type="project",
...     resource_id="a2f7dddb-1597-4eff-9f71-535fde243f58",
...     role="DataPlaneEditor",
...     created_at="2026-04-10T15:23:00Z",
... )
>>> binding.role == RoleName.DATA_PLANE_EDITOR
True
created_at: str
id: str
principal_id: str
principal_type: str
resource_id: str
resource_type: str
role: str
class pinecone.models.admin.role_binding.RoleBindingList(*, data=<factory>, pagination=None)[source]

Bases: Struct

A page of role bindings, plus the cursor for the next page.

Variables:
Parameters:

Examples

>>> from pinecone.models.admin.role_binding import RoleBindingList, RoleBindingModel
>>> bindings = RoleBindingList(
...     data=[
...         RoleBindingModel(
...             id="rb1",
...             principal_type="user",
...             principal_id="u1",
...             resource_type="organization",
...             resource_id="org-1",
...             role="OrgMember",
...             created_at="2026-04-10T15:23:00Z",
...         )
...     ]
... )
>>> bindings.roles()
['OrgMember']
data: list[RoleBindingModel]
property has_more: bool

True when the server supplied a cursor for a further page.

pagination: PaginationResponse | None
property pagination_token: str | None

Opaque cursor for the next page, or None if this is the last page.

roles()[source]

Return the role names on this page, in order.

Return type:

list[str]

to_dict()[source]

Return this page as a serializable dict with data and pagination keys.

Return type:

dict[str, Any]

class pinecone.models.admin.role_binding.RoleBindingInput(*, resource_type, role, resource_id=None)[source]

Bases: StructDictMixin, Struct

A role to grant when creating an invite or a service account.

Unlike the response models, this is an input the SDK sends, so resource_type and role are validated on construction against the values this SDK release knows about.

resource_type selects the binding scope. For organization scope, omit resource_id — the binding applies to the organization inferred from the request context. For project scope, resource_id is required and must be the project UUID.

Variables:

  • resource_type (str) – One of the ResourceType values.

  • role (str) – One of the RoleName values.

  • resource_id (str | None) – The project UUID for project scope; leave unset for organization scope.

Raises:

PineconeValueError – If resource_type or role is not a recognized value, or if resource_type is project and resource_id is missing or empty.

Parameters:

  • resource_type (str)

  • role (str)

  • resource_id (str | None)

Examples

>>> from pinecone.models.admin.role_binding import (
...     ResourceType,
...     RoleBindingInput,
...     RoleName,
... )
>>> RoleBindingInput(
...     resource_type=ResourceType.ORGANIZATION, role=RoleName.ORG_MEMBER
... ).to_dict()
{'resource_type': 'organization', 'role': 'OrgMember', 'resource_id': None}

Project-scoped bindings need the project UUID:

>>> RoleBindingInput(
...     resource_type="project",
...     role="ProjectViewer",
...     resource_id="a2f7dddb-1597-4eff-9f71-535fde243f58",
... ).resource_id
'a2f7dddb-1597-4eff-9f71-535fde243f58'
resource_id: str | None
resource_type: str
role: str
class pinecone.models.admin.role_binding.RoleName(value)[source]

Bases: str, Enum

A role that can be assigned to a principal at a resource scope.

Organization-scoped roles: OrgOwner, OrgManager, OrgMember, OrgBillingAdmin. Project-scoped roles: ProjectOwner, ProjectManager, ProjectMember, ProjectEditor, ProjectViewer, ControlPlaneEditor, ControlPlaneViewer, DataPlaneEditor, DataPlaneViewer.

Examples

>>> from pinecone.models.admin.role_binding import RoleName
>>> RoleName.DATA_PLANE_EDITOR == "DataPlaneEditor"
True
CONTROL_PLANE_EDITOR = 'ControlPlaneEditor'
CONTROL_PLANE_VIEWER = 'ControlPlaneViewer'
DATA_PLANE_EDITOR = 'DataPlaneEditor'
DATA_PLANE_VIEWER = 'DataPlaneViewer'
ORG_BILLING_ADMIN = 'OrgBillingAdmin'
ORG_MANAGER = 'OrgManager'
ORG_MEMBER = 'OrgMember'
ORG_OWNER = 'OrgOwner'
PROJECT_EDITOR = 'ProjectEditor'
PROJECT_MANAGER = 'ProjectManager'
PROJECT_MEMBER = 'ProjectMember'
PROJECT_OWNER = 'ProjectOwner'
PROJECT_VIEWER = 'ProjectViewer'
class pinecone.models.admin.role_binding.PrincipalType(value)[source]

Bases: str, Enum

The kind of principal that receives permissions from a role binding.

Possible values: user, service_account, api_key, invite.

Examples

>>> from pinecone.models.admin.role_binding import PrincipalType
>>> PrincipalType.SERVICE_ACCOUNT == "service_account"
True
API_KEY = 'api_key'
INVITE = 'invite'
SERVICE_ACCOUNT = 'service_account'
USER = 'user'
class pinecone.models.admin.role_binding.ResourceType(value)[source]

Bases: str, Enum

The kind of resource scope a role binding applies to.

Possible values: organization, project.

Examples

>>> from pinecone.models.admin.role_binding import ResourceType
>>> ResourceType.PROJECT == "project"
True
ORGANIZATION = 'organization'
PROJECT = 'project'

Assistant Models

class pinecone.models.assistant.model.AssistantModel(*, name, status, metadata=None, instructions=None, host=None, region=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", "Terminated", "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.

  • region (str | None) – The region the assistant is deployed in ("us" or "eu"), or None if not returned by the API.

Parameters:

  • name (str)

  • status (str)

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

  • instructions (str | None)

  • host (str | None)

  • region (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
region: str | None
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)[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. On 2026-07 this may be a user-provided identifier, so it is not guaranteed to be a UUID.

  • 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.

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 and error_message were removed in the 2026-07 API; accessing them raises an AttributeError naming describe_operation as the replacement.

content_hash: str | None
property crc32c_hash: str | None

Backwards-compatibility alias for content_hash.

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

Bases: StructDictMixin, Struct

Paginated response for listing assistants.

Variables:

  • assistants (list[pinecone.models.assistant.model.AssistantModel]) – The assistants returned in this page.

  • pagination (pinecone.models.assistant.list._Pagination | None) – Nested pagination object from the v202604 API, or None when no more pages exist.

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

Continuation token for the next page, or None when exhausted.

property next_token: str | None

Backwards-compatibility alias for next.

pagination: _Pagination | None
class pinecone.models.assistant.list.ListFilesResponse(*, files, pagination=None)[source]

Bases: StructDictMixin, Struct

Paginated response for listing assistant files.

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

Continuation token for the next page, or None when exhausted.

property next_token: str | None

Backwards-compatibility alias for next.

pagination: _Pagination | None
class pinecone.models.assistant.operation.OperationModel(*, operation_id, status, operation_type=None, file_id=None, created_at=None, completed_on=None, percent_complete=None, error=None, ingestion_units=None)[source]

Bases: StructDictMixin, Struct

Response model for a long-running assistant operation.

Returned by the file endpoints that start an operation (POST /files/{assistant_name}, PUT /files/{assistant_name}/{file_id}, DELETE /files/{assistant_name}/{file_id}) and by the operations endpoints (GET /operations/{assistant_name}/{operation_id}, GET /operations/{assistant_name}).

The API uses id, created_on and error_message; the rename mapping presents them as operation_id, created_at and error in Python for clarity. Every other attribute carries its wire name.

Every field except operation_id and status is optional so that the smaller body shipped by the 2026-04 upsert path still decodes. The server omits completed_on, error_message and ingestion_units while they do not apply; a spec-conformant server may instead send them as null. Both decode to None.

Variables:

  • operation_id (str) – Unique identifier for the operation (JSON field: id).

  • status (str) – Current status of the operation: "Processing" while it is in progress, "Completed" when it finished successfully, "Failed" when it did not (see error).

  • operation_type (str | None) – The kind of action this operation represents — "upload_file", "upsert_file", "update_file_metadata" or "delete_file" — or None when the server did not report one.

  • file_id (str | None) – Identifier of the file being operated on, or None.

  • created_at (str | None) – ISO 8601 timestamp when the operation was created, or None (JSON field: created_on).

  • completed_on (str | None) – ISO 8601 timestamp when the operation completed or failed, or None while status is "Processing".

  • percent_complete (int | None) – Progress of the operation as a percentage from 0 to 100, or None when the server did not report progress.

  • error (str | None) – Error message if the operation failed, or None (JSON field: error_message). Goes stale across a retry: the backend writes this column with COALESCE, so it is never cleared once set — a retried operation that is back to "Processing", or that eventually succeeds, still carries the earlier attempt’s text. Read it only when status is "Failed".

  • ingestion_units (float | None) – Ingestion units consumed by this operation, reported once a file ingestion operation has completed, or None.

Parameters:

  • operation_id (str)

  • status (str)

  • operation_type (str | None)

  • file_id (str | None)

  • created_at (str | None)

  • completed_on (str | None)

  • percent_complete (int | None)

  • error (str | None)

  • ingestion_units (float | None)

completed_on: str | None
created_at: str | None
error: str | None
file_id: str | None
ingestion_units: float | None
operation_id: str
operation_type: str | None
percent_complete: int | None
status: str
class pinecone.models.assistant.list.ListOperationsResponse(*, operations, pagination=None)[source]

Bases: StructDictMixin, Struct

Paginated response for listing assistant operations.

Variables:
Parameters:
property next: str | None

Continuation token for the next page, or None when exhausted.

property next_token: str | None

Backwards-compatibility alias for next.

operations: list[OperationModel]
pagination: _Pagination | None
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. Must not be blank — the backend trims before checking, so "" and a whitespace-only string alike come back 400 "Message content cannot be empty".

  • role (str) – The role of the message author. Defaults to "user". The backend accepts only the exact strings "user" and "assistant", compared case-sensitively: "User" is rejected with 400 "Role 'User' is not valid", and "" with 400 "Role cannot be empty". Neither field is validated client-side.

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 (Mapping[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, context_snippet_count=None, content_filter_results=None)[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 — one of "stop" (the model finished), "length" (the token limit was reached), "content_filter" (content filtering rules blocked the output), "tool_calls" (a tool call was triggered), or the literal string "null". The backend enum carries that fifth null variant and serializes it as the JSON string "null", not as JSON null; the 2026-07 OAS x-enum omits it, which is why this is typed str rather than a closed set.

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

  • context_snippet_count (int | None) – Number of retrieved context snippets that were provided to the model, or None if the server did not report it. 0 means no relevant context was found for the query.

  • content_filter_results (dict[str, Any] | None) – Safety classifications reported by the LLM provider, or None when the provider returned none. The payload carries a spec key naming the provider (e.g. "openai", "gemini") and a results value whose structure is defined by that provider, so it is left as a plain dict.

Parameters:

  • id (str)

  • model (str)

  • usage (ChatUsage)

  • message (ChatMessage)

  • finish_reason (str)

  • citations (list[ChatCitation])

  • context_snippet_count (int | None)

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

citations: list[ChatCitation]
content_filter_results: dict[str, Any] | None
context_snippet_count: int | None
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. The backend accepts 1-64; 0 and values above 64 are each rejected with a 400 (the spec documents a default of 16).

  • snippet_size (int | None) – Target size (in tokens) for each context snippet. The backend accepts 512-8192; anything outside that range is rejected with a 400 (the spec documents a default of 2048).

  • 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, usage=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.

  • usage (pinecone.models.assistant.chat.ChatUsage | None) – Token usage statistics, populated on the final chunk, or None.

Parameters:

  • id (str)

  • choices (list[ChatCompletionStreamChoice])

  • model (str | None)

  • object (str | None)

  • created (int | None)

  • system_fingerprint (str | None)

  • usage (ChatUsage | None)

choices: list[ChatCompletionStreamChoice]
created: int | None
id: str
model: str | None
object: str | None
system_fingerprint: str | None
usage: ChatUsage | None
class pinecone.models.assistant.streaming.StreamMessageStart(*, model, role, id=None, context_snippet_count=None, content_filter_results=None)[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").

  • id (str | None) – Unique identifier for this chat response, shared by every chunk in the stream, or None if the server did not report it.

  • context_snippet_count (int | None) – Number of retrieved context snippets that were provided to the model, or None if the server did not report it. Arrives before any content, so a value of 0 lets callers react to “no relevant context found” without waiting for the full stream.

  • content_filter_results (dict[str, Any] | None) – Safety classifications reported by the LLM provider, or None when the provider returned none. The payload carries a spec key naming the provider (e.g. "openai", "gemini") and a results value whose structure is defined by that provider, so it is left as a plain dict.

Parameters:

  • model (str)

  • role (str)

  • id (str | None)

  • context_snippet_count (int | None)

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

content_filter_results: dict[str, Any] | None
context_snippet_count: int | None
id: str | None
model: str
role: str
property type: str

Discriminator value, always "message_start".

class pinecone.models.assistant.streaming.StreamMessageEnd(*, id, usage=None, model=None, finish_reason=None, content_filter_results=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 | None) – Token usage statistics for the request.

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

  • finish_reason (str | None) – The reason generation stopped — one of "stop" (the model finished), "length" (the token limit was reached), "content_filter" (content filtering rules blocked the output), "tool_calls" (a tool call was triggered), or the literal string "null". The backend enum carries that fifth null variant and serializes it as the JSON string "null", not as JSON null; the 2026-07 OAS x-enum omits it. Python None is distinct, and only appears for payloads recorded before the field was documented.

  • content_filter_results (dict[str, Any] | None) – Safety classifications reported by the LLM provider, or None when the provider returned none. The payload carries a spec key naming the provider (e.g. "openai", "gemini") and a results value whose structure is defined by that provider, so it is left as a plain dict.

Parameters:

  • id (str)

  • usage (ChatUsage | None)

  • model (str | None)

  • finish_reason (str | None)

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

content_filter_results: dict[str, Any] | None
finish_reason: str | None
id: str
model: str | None
property type: str

Discriminator value, always "message_end".

usage: ChatUsage | None
class pinecone.models.assistant.streaming.StreamContentChunk(*, id, delta, model=None, content_filter_results=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.

  • content_filter_results (dict[str, Any] | None) – Safety classifications reported by the LLM provider for this fragment, or None when the provider returned none. The payload carries a spec key naming the provider (e.g. "openai", "gemini") and a results value whose structure is defined by that provider, so it is left as a plain dict.

Parameters:

  • id (str)

  • delta (StreamContentDelta)

  • model (str | None)

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

content_filter_results: dict[str, Any] | 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