AsyncPinecone

AsyncPinecone is the asynchronous twin of Pinecone: the same namespaces (pc.indexes, pc.collections, …), each method an async def. Use it inside an async with block; awaiting index() returns an AsyncIndex.

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    index = await pc.index("my-index")
    async with index:
        results = await index.query(
            vector=[0.012, -0.087, 0.153],
            top_k=10,
        )

Note

AsyncPinecone.index() is a coroutine and must be awaited, where Pinecone.index() is a plain call. Both resolve a host the same way: an explicit host is used as-is, a name is served from the host cache, and a name that misses the cache costs one describe request. Awaiting is what makes that request non-blocking.

Pass host= when you already have it to skip the lookup entirely:

desc = await pc.indexes.describe("my-index")
idx = await pc.index(host=desc.host)
class pinecone.async_client.pinecone.AsyncPinecone(api_key=None, *, host=None, additional_headers=None, source_tag=None, proxy_url=None, proxy_headers=None, ssl_ca_certs=None, ssl_verify=True, timeout=30.0, connection_pool_maxsize=0, retry_config=None, **kwargs)[source]

Bases: object

Entry point to Pinecone’s control plane, over asyncio.

One client carries your API key, resolved host, and connection pool, so build it once — inside async with, which closes it for you — and reuse it. Its namespace properties — indexes, collections, backups, backup_schedules, restore_jobs, inference, and assistants — create and inspect those resources. Vectors are read and written on the data plane instead, through the separate client index() hands back.

Pinecone is the blocking twin, and Sync vs async clients compares the two. The one shape difference is index(): here it is a coroutine you await, so the one describe request a cache-missing name costs does not block the event loop, and it takes no grpc= argument, the gRPC transport being sync-only. Any call can raise the connection, timeout, and API errors catalogued in Error handling, and every Raises: section below names only what is specific to that method. Retries and resilience covers what the client retries on your behalf and what retry_config changes.

Parameters:

  • api_key (str | None) – Your Pinecone API key. None (default) reads PINECONE_API_KEY from the environment, which is how most deployments supply it.

  • host (str | None) – Control-plane host, e.g. "https://api.pinecone.io". A value with no scheme is read as https. None (default) reads PINECONE_CONTROLLER_HOST, then falls back to the public API. Point it elsewhere for a gateway, a private endpoint, or a local simulator.

  • additional_headers (Mapping[str, str] | None) – Headers added to every control-plane request, e.g. {"X-Request-Source": "nightly-reindex"}. A name matches the SDK’s own headers (X-Pinecone-Api-Version, User-Agent, Api-Key) regardless of case, and your value replaces the SDK’s, so exactly one is sent. When omitted, the client reads PINECONE_ADDITIONAL_HEADERS as a JSON object instead.

  • source_tag (str | None) – Attribution tag appended to the User-Agent, e.g. "acme-search-service". Lowercased, spaces become underscores, and anything outside a-z, 0-9, _ and : is dropped.

  • proxy_url (str | None) – Proxy for outgoing requests, e.g. "http://proxy.corp.internal:3128".

  • proxy_headers (Mapping[str, str] | None) – Not supported here: a non-empty mapping raises NotImplementedError at construction. Use Pinecone when the proxy needs headers of its own.

  • ssl_ca_certs (str | None) – Path to a CA bundle file, or to a directory of them, for a corporate root or a self-signed endpoint. It wins over ssl_verify=False: pass both and verification stays on.

  • ssl_verify (bool) – Whether to verify the server’s certificate. True (default) is right everywhere but a throwaway test endpoint.

  • timeout (float) – Deadline in seconds for a single HTTP attempt, not for the whole call — each retry gets its own. Must be greater than zero. Defaults to 30.0.

  • connection_pool_maxsize (int) – Ceiling on connections held open to the control plane. 0 (default) leaves httpx’s own ceiling in place; raise it for a process issuing many concurrent control-plane calls.

  • retry_config (RetryConfig | None) – Retry policy for control-plane requests. None (default) uses the built-in policy, which suits most callers; see Retries and resilience for the defaults, for how to switch retries off, and for why it does not reach data-plane REST.

  • kwargs (NoReturn)

Raises:

  • PineconeValueError – If no API key is given and PINECONE_API_KEY is unset, since nothing would authenticate the first request. Also raised when the key is not a valid HTTP header value, such as a blank key or one with a trailing newline, so the failure is local and never echoes the key.

  • PineconeValueError – If proxy_url has a scheme other than http, https, socks5 or socks5h, no host, an invalid port, surrounding whitespace, or an unencoded #, / or ? in the username or password; the message masks the username and password.

  • NotImplementedError – If proxy_headers is non-empty.

  • PineconeTypeError – If a keyword argument other than those listed above is passed, which is how a misspelled parameter name surfaces. It derives from TypeError, so except TypeError catches it too.

  • FileNotFoundError – If ssl_ca_certs names a path that does not exist, raised on the first request rather than when the client is constructed, so a mistyped path cannot leave you silently verifying against the default trust store instead. A bundle that exists but cannot be parsed as a certificate raises ssl.SSLError at the same point.

Examples

Construct inside async with, then reach the control plane through the namespace properties. Leaving api_key off entirely reads it from PINECONE_API_KEY:

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    if not await pc.indexes.exists("product-search"):
        await pc.indexes.create(
            name="product-search",
            schema={"fields": {"your_vector": {
                "type": "dense_vector", "dimension": 1536,
                "metric": "cosine"}}},
        )

index() hands back a separate data-plane client scoped to one index, which is what reads and writes vectors. It manages its own connections, so it gets its own async with block. A query vector has to be as wide as the index’s dense field — the three floats below stand in for a full 1536-dimensional embedding:

async with AsyncPinecone(api_key="your-api-key") as pc:
    idx = await pc.index(name="product-search")
    async with idx:
        results = await idx.query(
            vector=[0.012, -0.087, 0.153],
            top_k=10,
        )
        for match in results.matches:
            print(match.id, match.score)
__init__(api_key=None, *, host=None, additional_headers=None, source_tag=None, proxy_url=None, proxy_headers=None, ssl_ca_certs=None, ssl_verify=True, timeout=30.0, connection_pool_maxsize=0, retry_config=None, **kwargs)[source]
Parameters:
Return type:

None

property indexes: AsyncIndexes

Create, inspect, configure, and delete the project’s indexes.

Returns:

The AsyncIndexes namespace.

Examples

async with AsyncPinecone(api_key="your-api-key") as pc:
    async for index in pc.indexes.list():
        print(index.name, index.status.state)
property collections: AsyncCollections

Create and inspect collections, the static snapshots of a pod-based index.

A collection is the pod-based snapshot format. The serverless equivalent is a backup, under backups.

Returns:

The AsyncCollections namespace.

Examples

async with AsyncPinecone(api_key="your-api-key") as pc:
    for col in await pc.collections.list():
        print(col.name, col.status)
property assistants: AsyncAssistants

Create and manage Pinecone Assistants.

An assistant is a hosted, retrieval-augmented chat service: upload files to it and it answers questions grounded in their content, with no index or embedding pipeline of your own.

Returns:

The AsyncAssistants namespace.

Examples

async with AsyncPinecone(api_key="your-api-key") as pc:
    async for assistant in pc.assistants.list():
        print(assistant.name, assistant.status)
property assistant: _AsyncAssistantNamespaceProxy

Reach one assistant by name, or the whole namespace by attribute.

assistants is the canonical namespace; this singular alias is not deprecated. It forwards every attribute there, and awaiting it with a name is shorthand for describe().

Returns:

A proxy that behaves like the AsyncAssistants namespace for attribute access (pc.assistant.create(...)) and, when awaited with a name, returns that assistant’s details.

Examples

Awaiting the proxy with a name is shorthand for describe():

async with AsyncPinecone(api_key="your-api-key") as pc:
    bot = await pc.assistant("acme-support-bot")
    print(bot.status, bot.instructions)

Every other attribute forwards to the plural namespace, so pc.assistant.create and pc.assistants.create are the same method reached two ways:

async with AsyncPinecone(api_key="your-api-key") as pc:
    new_bot = await pc.assistant.create(
        name="acme-billing-bot",
        instructions="Help users with billing questions.",
    )
    print(new_bot.status)
property backups: AsyncBackups

Create, inspect, and delete backups of a serverless index.

Restoring one is not done from here: pass a backup_id to create_index_from_backup(), which creates a new index from it. For pod-based indexes the snapshot format is a collection, under collections.

Returns:

The AsyncBackups namespace.

Examples

list() returns one page, so follow pagination.next to read every backup:

async with AsyncPinecone(api_key="your-api-key") as pc:
    page = await pc.backups.list()
    backups = list(page)
    while page.pagination and page.pagination.next:
        page = await pc.backups.list(pagination_token=page.pagination.next)
        backups.extend(page)
    for backup in backups:
        print(backup.backup_id, backup.source_index_name, backup.status)
property backup_schedules: AsyncBackupSchedules

Attach a recurring backup cadence to an index.

A schedule gives an index a daily, weekly, or monthly cadence, so Pinecone creates each backup for you rather than you triggering one every time.

Returns:

The AsyncBackupSchedules namespace.

Examples

iter_schedules() walks every page of an index’s schedules:

async with AsyncPinecone(api_key="your-api-key") as pc:
    async for schedule in pc.backup_schedules.iter_schedules(
        index_name="product-search"
    ):
        print(schedule.name, schedule.frequency, schedule.enabled)
property restore_jobs: AsyncRestoreJobs

Track a restore that create_index_from_backup() started.

A restore job is the request itself, so it is what to follow when you passed timeout=-1 and the target index does not exist yet.

Returns:

The AsyncRestoreJobs namespace.

Examples

list() returns one page, and pages can overlap, so follow pagination.next and key the jobs by id:

async with AsyncPinecone(api_key="your-api-key") as pc:
    page = await pc.restore_jobs.list()
    jobs = {job.restore_job_id: job for job in page}
    while page.pagination and page.pagination.next:
        page = await pc.restore_jobs.list(
            pagination_token=page.pagination.next
        )
        jobs.update((job.restore_job_id, job) for job in page)
    for job in jobs.values():
        print(job.restore_job_id, job.target_index_name, job.status)
property inference: AsyncInference

Embed text or images, and rerank documents, on hosted models.

Reach for this when you want vectors or relevance scores without hosting a model yourself.

Returns:

The AsyncInference namespace.

Examples

multilingual-e5-large is asymmetric, so input_type tells it which side of a search the text belongs to — "passage" for text you intend to store, "query" for text you intend to search with:

async with AsyncPinecone(api_key="your-api-key") as pc:
    embeddings = await pc.inference.embed(
        model="multilingual-e5-large",
        inputs=["Solar panels reduce energy costs and lower carbon emissions."],
        parameters={"input_type": "passage"},
    )
    print(len(embeddings.data))
async create_index_from_backup(*, name, backup_id, deletion_protection=None, tags=None, read_capacity=None, timeout=None)[source]

Create a new index by restoring from a backup.

Polls until the restored index is ready, unless timeout is -1. This is the only supported way to restore a backup: create() rejects source_backup_id= with a message pointing here.

Parameters:

  • name (str) – Name for the new index.

  • backup_id (str) – Identifier of the backup to restore from. Obtain it from AsyncBackups.create or AsyncBackups.list.

  • deletion_protection (DeletionProtection | str | None) – "enabled" or "disabled". Defaults to "disabled" server-side when omitted.

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

  • read_capacity (dict[str, Any] | None) – Optional read capacity for the restored index — {"mode": "OnDemand"} or {"mode": "Dedicated", "dedicated": {"node_type": ..., "scaling": "Manual", "manual": {"shards": ..., "replicas": ...}}}. Omitted entirely when None, leaving the server’s on-demand default in place. Serverless backups only; the server rejects a dedicated configuration too small to hold the backup.

  • timeout (int | None) – Seconds to wait for readiness. None (default) blocks up to 300 s. -1 returns a CreateIndexFromBackupResponse immediately (contains restore_job_id and index_id) without polling.

Returns:

A CreateIndexFromBackupResponse when timeout is -1 (contains restore_job_id and index_id), or an IndexModel describing the restored index once it is ready.

Raises:
Return type:

CreateIndexFromBackupResponse | IndexModel

Examples

The default form blocks until the restored index is ready and hands back the index itself, so the next call can use it:

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    index = await pc.create_index_from_backup(
        name="product-search-restored",
        backup_id="bk-abc123",
    )
    print(index.status.state)

timeout=-1 returns as soon as the restore is accepted. What comes back is a CreateIndexFromBackupResponse, not an index — the index does not exist yet, so follow the restore through pc.restore_jobs rather than treating the return value as one:

async with AsyncPinecone(api_key="your-api-key") as pc:
    result = await pc.create_index_from_backup(
        name="product-search-restored",
        backup_id="bk-abc123",
        timeout=-1,
    )
    job = await pc.restore_jobs.describe(job_id=result.restore_job_id)
    print(job.status)

A restore can land straight onto dedicated read nodes instead of the on-demand default:

async with AsyncPinecone(api_key="your-api-key") as pc:
    index = await pc.create_index_from_backup(
        name="product-search-restored",
        backup_id="bk-abc123",
        read_capacity={
            "mode": "Dedicated",
            "dedicated": {
                "node_type": "t1",
                "scaling": "Manual",
                "manual": {"shards": 2, "replicas": 2},
            },
        },
    )
    print(index.status.state)

Changed in version 10.0: Added read_capacity, so a restore can land straight onto dedicated read nodes instead of defaulting to on-demand capacity.

property config: PineconeConfig

Read back the settings this client resolved at construction.

Returns:

PineconeConfig carrying the resolved API key, host, timeout, and connection settings.

Examples

The values are post-resolution, with defaults and environment variables folded in, so this is where to confirm which host a client is actually pointed at:

async with AsyncPinecone(api_key="your-api-key") as pc:
    print(pc.config.host, pc.config.timeout)
async index(name='', *, host='')[source]

Open an async data-plane client for one index, to read and write vectors.

A coroutine: awaiting it is what keeps the host lookup off the event loop. An explicit host is used as-is, a name is served from this client’s host cache, and a name that misses the cache costs one describe request. The sync twin, Pinecone.index(), is a plain call, and is the only one of the two that can return a gRPC client.

Parameters:

  • name (str) – Name of the index, e.g. "product-search". Costs one describe request the first time, then comes from the host cache.

  • host (str) – The index’s host, e.g. "product-search-abc123.svc.pinecone.io". Pass it when you have it already and the describe request is skipped entirely. A scheme you include is kept as given: "https://..." and a bare host both use TLS, while "http://..." is sent in cleartext and emits a RuntimeWarning unless the host is a loopback or RFC 1918 IP address, localhost, or *.localhost.

Returns:

An AsyncIndex.

Raises:

  • PineconeValueError – If neither name nor host is given, or if name names an index that has no host yet — it is still initializing, so wait for its status to reach Ready.

  • NotFoundError – If name names no index in this project.

Return type:

AsyncIndex

Examples

async with AsyncPinecone(api_key="your-api-key") as pc:
    idx = await pc.index(name="product-search")
    async with idx:
        print(await idx.describe_index_stats())

Passing the host skips the lookup, which saves a round trip when you already know it — from AsyncIndexes.describe, or from your own config:

async with AsyncPinecone(api_key="your-api-key") as pc:
    idx = await pc.index(host="product-search-abc123.svc.pinecone.io")
    async with idx:
        print(await idx.describe_index_stats())

Warning

The returned index manages its own HTTP client. Always use async with idx: or call await idx.close() when done — closing the parent AsyncPinecone does not close index clients.

See also

indexes — the control-plane namespace, for creating, listing, describing, configuring, and deleting indexes rather than reading from one.

async close()[source]

Release this client’s control-plane connections.

Closes the control-plane connection pool, plus the inference and assistants pools if those namespaces were used. Index clients from index() hold their own connections and are not closed here. Prefer the async context manager form, async with AsyncPinecone(...) as pc:, which calls this on the way out.

Examples

The async context manager form closes the client on the way out, on an exception as well as on a normal exit:

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    async for index in pc.indexes.list():
        print(index.name)

Close it yourself when the client has to outlive a single block:

pc = AsyncPinecone(api_key="your-api-key")
try:
    print(await pc.indexes.exists("product-search"))
finally:
    await pc.close()
Return type:

None

async __aenter__()[source]

Enter the async context manager, returning this client.

Returns:

This AsyncPinecone instance.

Return type:

AsyncPinecone

Examples

async with AsyncPinecone(api_key="your-api-key") as pc:
    async for index in pc.indexes.list():
        print(index.name)
async __aexit__(*args)[source]

Exit the async context manager, closing the client.

Calls close() to release open HTTP connections.

Examples

async with AsyncPinecone(api_key="your-api-key") as pc:
    async for index in pc.indexes.list():
        print(index.name)
Parameters:

args (Any)

Return type:

None

AsyncIndexes

class pinecone.async_client.indexes.AsyncIndexes(http, host_cache=None)[source]

Bases: object

Async control-plane operations for Pinecone indexes.

An index is the container your records live in: its searched fields are declared as a schema when you create it, and every query is aimed at one index. Reached as pc.indexes on an AsyncPinecone client; not constructed directly. Mirrors Indexes one-for-one.

The backup methods here are scoped to a single index. AsyncBackups (pc.backups) covers the project-wide backup listing plus delete, which belong to no one index.

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    names = [index.name async for index in pc.indexes.list()]

See also

AsyncPinecone.index(name), the data-plane client for reads and writes against one index.

Error handling, the exceptions any method here can raise and how to handle them.

Sync vs async clients, when to reach for this client over the synchronous one.

Changed in version 10.0: Graduated to the schema-based API. create() takes schema=/deployment= instead of spec=/dimension=/ metric=/vector_type=; configure() nests pod scaling under deployment= and dropped embed=; list() returns an AsyncPaginator; the index-scoped backup methods graduated from the preview namespace.

Parameters:

  • http (AsyncHTTPClient)

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

__init__(http, host_cache=None)[source]
Parameters:

  • http (AsyncHTTPClient)

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

Return type:

None

list(*, limit=None, pagination_token=None)[source]

List every index in the project.

Not a coroutine: iterate the result rather than awaiting the call.

Parameters:

  • limit (int | None) – Maximum number of indexes to yield. Must be a positive integer; None (the default) yields every index.

  • pagination_token (str | None) – Accepted so this listing shares the paginator interface of the other listings. The server issues no pagination token for indexes, so leave it None.

Returns:

AsyncPaginator over IndexModel instances.

Raises:

PineconeValueError – If limit is zero or negative.

Return type:

AsyncPaginator[IndexModel]

Examples

async with AsyncPinecone(api_key="your-api-key") as pc:
    async for index in pc.indexes.list():
        print(index.name, index.status.state)

Changed in version 10.0: Returns an AsyncPaginator instead of an IndexList, and is no longer a coroutine; replace (await pc.indexes.list()).names() with [index.name async for index in pc.indexes.list()].

async describe(name)[source]

Get detailed information about a named index.

Caches the index’s host, so a later AsyncPinecone.index(name) call for the same name skips its own describe round trip.

Parameters:

name (str) – The name of the index to describe.

Returns:

IndexModel with name, host, schema, deployment, read_capacity, status, deletion_protection, and tags.

Raises:
Return type:

IndexModel

Examples

The returned host carries the https:// scheme:

async with AsyncPinecone(api_key="your-api-key") as pc:
    index = await pc.indexes.describe("my-index")
    print(index.host)
    print(list(index.schema.fields))
async exists(name)[source]

Check whether a named index exists.

Calls describe() internally and returns False instead of raising when the index isn’t found. Every other error propagates.

Parameters:

name (str) – The name of the index to check.

Returns:

True if the index exists, False otherwise.

Raises:
Return type:

bool

Examples

async with AsyncPinecone(api_key="your-api-key") as pc:
    if await pc.indexes.exists("my-index"):
        print("Index found")

Changed in version 10.0: An empty name now raises PineconeValueError instead of returning False.

async delete(name, *, timeout=None)[source]

Delete an index by name.

Waits until the index is gone, with no upper time bound unless you pass timeout.

Parameters:

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

  • timeout (int | None) – Seconds to wait for the index to disappear. Use None (default) to poll indefinitely until the index is gone. Use a positive int to poll with a deadline. Use -1 to return immediately without polling.

Raises:
Return type:

None

Examples

Delete an index and block until it is gone:

async with AsyncPinecone(api_key="your-api-key") as pc:
    await pc.indexes.delete("my-index")

Or bound the wait, so an index still present after a minute raises PineconeTimeoutError instead of polling forever:

async with AsyncPinecone(api_key="your-api-key") as pc:
    await pc.indexes.delete("my-index", timeout=60)

Passing timeout=-1 returns as soon as the delete request is accepted, without polling; the index is still being torn down when the call returns.

async create(*, schema=None, name=None, deployment=None, read_capacity=None, deletion_protection=None, tags=None, cmek_id=None, timeout=None, spec=None, dimension=None, metric=None, vector_type=None, **legacy_kwargs)[source]

Create a new index.

An index’s field layout is declared as a schema of named, typed fields. Every field in the schema must be a searched field: dense_vector, sparse_vector, or string with full_text_search, embed or sparse_embed. A string field with embed or sparse_embed supports integrated embedding: Pinecone embeds its text on write and the query text on search. The result is a document index; read and write it through index.documents. Metadata-only fields aren’t declared here; they’re indexed automatically the first time they appear on an upserted record. The schema can’t change once the index exists, and the call waits until the index is ready unless you pass timeout=-1.

Parameters:

  • schema (dict[str, Any] | IndexSchema | None) –

    The index’s field schema. Required unless the deprecated dimension= (with optional metric=/ vector_type=) is used instead; the two are mutually exclusive. A dict with a "fields" key mapping field names to typed configurations:

    {
    "fields": {
        "your_vector": {"type": "dense_vector",
                        "dimension": 1536, "metric": "cosine"},
        "body": {"type": "string",
                 "full_text_search": {"language": "en",
                                      "stemming": True}},
    }
}

    Also accepts the dict produced by SchemaBuilder or an IndexSchema. A hybrid index has to declare its sparse_vector field here; see the note after the examples. full_text_search.language accepts a fixed set of language codes (or their English names, default en), but stop_words=True is not supported for every language: the server’s 400 names the unsupported language, by its English name rather than the code you sent.

  • name (str | None) – Name for the index, in lowercase alphanumerics and hyphens, e.g. "movie-recommendations". The server assigns a name when omitted.

  • deployment (dict[str, Any] | None) – Deployment configuration, discriminated on "deployment_type". For a managed index: {"deployment_type": "managed", "cloud": "aws", "region": "us-east-1"}. For a pod-based index, "deployment_type": "pod" plus environment, pod_type, replicas, and shards. Defaults to a managed index on AWS us-east-1 when omitted. Mutually exclusive with the deprecated spec=.

  • read_capacity (dict[str, Any] | None) – Read capacity for a managed or BYOC index, either {"mode": "OnDemand"} or {"mode": "Dedicated", "dedicated": {"node_type": ..., "scaling": ..., "manual": {"replicas": ..., "shards": ...}}}.

  • deletion_protection (str | None) – "enabled" to block delete() on this index until it’s set back to "disabled" (the default).

  • tags (Mapping[str, str] | None) – Key-value tags to attach, e.g. {"env": "prod"}. Pass None (the default) to attach none.

  • cmek_id (str | None) – ID of a customer-managed encryption key to encrypt the index with, e.g. "key-abc123".

  • timeout (int | None) – Seconds to wait for the index to become ready before returning. None (default) waits indefinitely, -1 returns immediately without waiting, and a positive number waits up to that many seconds. Any other negative value raises PineconeValueError before a request is sent.

  • spec (Any) –

    Deprecated. A ServerlessSpec, PodSpec, ByocSpec, or the equivalent dict, translated into deployment= (and read_capacity= when the spec carries one). Mutually exclusive with deployment=. Use create_for_model() for IntegratedSpec.

    Deprecated since version 10.0: Pass deployment= directly instead.

  • dimension (int | None) –

    Deprecated. Dense vector width for the legacy path, translated into a single-field schema=. Required when creating a dense index this way.

    Deprecated since version 10.0: Declare a named field in schema= instead.

  • metric (Metric | str | None) –

    Deprecated. Similarity metric for the legacy dense path: "cosine" (default), "euclidean", or "dotproduct".

    Deprecated since version 10.0: Set metric inside the schema= field declaration instead.

  • vector_type (VectorType | str | None) –

    Deprecated. "dense" (default) or "sparse", for the legacy path.

    Deprecated since version 10.0: Declare a named dense_vector/sparse_vector field in schema= instead.

  • legacy_kwargs (Any)

Returns:

IndexModel describing the created index, ready unless timeout=-1 was passed.

Raises:

  • PineconeValueError – If neither schema= nor dimension= is given, or mutually exclusive arguments (schema= with a legacy vector kwarg, or deployment= with spec=) are combined, or timeout is a negative value other than -1.

  • PineconeTypeError – If an unsupported legacy keyword (e.g. pods=) or spec=IntegratedSpec(...) is passed.

  • IndexInitFailedError – If the index fails to initialize.

  • PineconeTimeoutError – If the index isn’t ready before timeout elapses.

Return type:

IndexModel

Examples

A dense index on the default deployment (managed, AWS us-east-1):

async with AsyncPinecone(api_key="your-api-key") as pc:
    await pc.indexes.create(
        name="movie-recommendations",
        schema={"fields": {"your_vector": {
            "type": "dense_vector", "dimension": 1536, "metric": "cosine"}}},
    )

A hybrid index in a region of your choosing. Declare the sparse_vector field now; see the note below:

async with AsyncPinecone(api_key="your-api-key") as pc:
    index = await pc.indexes.create(
        name="support-articles",
        schema={"fields": {
            "your_vector": {"type": "dense_vector",
                            "dimension": 1024, "metric": "cosine"},
            "keywords": {"type": "sparse_vector"},
            "body": {"type": "string",
                     "full_text_search": {"language": "en",
                                          "stemming": True}},
        }},
        deployment={"deployment_type": "managed",
                    "cloud": "aws", "region": "us-west-2"},
        tags={"env": "prod"},
    )
    print(index.host)

Integrated embedding on a string field, processed in the US for both documents and queries:

async with AsyncPinecone(api_key="your-api-key") as pc:
    await pc.indexes.create(
        name="support-articles-us",
        schema={"fields": {"body": {
            "type": "string",
            "embed": {
                "model": "text-embedding-3-large",
                "processing_location": "us",
            },
        }}},
    )

Note

A hybrid index must declare its sparse_vector field explicitly. A dense field with metric="dotproduct" does not accept sparse values on its own: the create succeeds, and only the sparse upserts are refused later. The field cannot be added by configure(), so an index created without one has to be recreated. See Migrating to V10.

See also

create_for_model() creates a legacy integrated index, which requires the legacy Records API. For integrated embedding in a document index, declare embed / sparse_embed on a string field here instead.

Changed in version 10.0: spec=, dimension=, metric=, and vector_type= are deprecated, keyword-only sugar for the current schema=/ deployment= arguments. pods=, metadata_config=, source_collection=, source_backup_id=, and spec=IntegratedSpec(...) have no equivalent here; use create_for_model() for a legacy integrated index, or embed / sparse_embed on a string field for integrated embedding in a document index.

async create_for_model(*, name, cloud, region, embed, deletion_protection=None, tags=None, schema=None, read_capacity=None, timeout=None)[source]

Create a legacy integrated index, served by the legacy Records API.

Pinecone embeds text written to the mapped field automatically at upsert time and embeds queries at read time using the same model. In the returned index, the embedding configuration surfaces as a semantic_text field in schema, named after the field_map text entry.

This creates a legacy integrated index, and legacy integrated indexes require the legacy Records API (upsert_records() and search()). For new work, create a document index with integrated embedding instead: pass create() a string field with embed or sparse_embed and use index.documents, which adds full-text search on the same fields and score_by.

Parameters:

  • name (str) – Name for the index, in lowercase alphanumerics and hyphens, e.g. "semantic-search".

  • cloud (str) – Public cloud provider: "aws", "gcp", or "azure".

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

  • embed (Mapping[str, Any] | Any) – Embedding configuration. A dict (or EmbedConfig / IndexEmbed) with required model and field_map (e.g. {"text": "chunk_text"}) and optional metric, dimension, read_parameters, write_parameters. The model cannot be changed after creation.

  • deletion_protection (str | None) – "enabled" to block delete() on this index until it’s set back to "disabled" (the default).

  • tags (Mapping[str, str] | None) – Key-value tags to attach, e.g. {"env": "prod"}. Pass None (the default) to attach none.

  • schema (dict[str, Any] | None) – Filterable metadata fields, e.g. {"fields": {"genre": {"filterable": True}}}. A bare field map is wrapped in {"fields": ...} for you.

  • read_capacity (dict[str, Any] | None) – Read capacity for the index, in the same shape as for create().

  • timeout (int | None) – Seconds to wait for the index to become ready before returning. None (default) waits indefinitely, -1 returns immediately without waiting, and a positive number waits up to that many seconds. Any other negative value raises PineconeValueError before a request is sent.

Returns:

IndexModel describing the created index, ready unless timeout=-1 was passed.

Raises:

PineconeValueError – If name, cloud, region, embed, tags, deletion_protection, or timeout (a negative value other than -1) fail client-side validation.

Return type:

IndexModel

Examples

The field_map text entry names the record field Pinecone embeds, and that same name is what the field is called in the returned schema (chunk_text below):

async with AsyncPinecone(api_key="your-api-key") as pc:
    index = await pc.indexes.create_for_model(
        name="semantic-search",
        cloud="aws",
        region="us-east-1",
        embed={"model": "multilingual-e5-large",
               "field_map": {"text": "chunk_text"}},
    )
    print(index.schema.fields["chunk_text"])

See also

create() creates an index you supply the vectors for yourself, declaring them as dense_vector/sparse_vector fields in schema=.

async configure(name, *, deployment=None, schema=None, read_capacity=None, deletion_protection=None, tags=None, replicas=None, pod_type=None, serverless_read_capacity=None, **legacy_kwargs)[source]

Configure an existing index.

Only the fields you provide are updated; omitted parameters are left unchanged on the server. Read capacity and pod scaling apply asynchronously, so the call returns while the change is still in flight.

Parameters:

  • name (str) – Name of the index to configure.

  • deployment (dict[str, Any] | None) – Pod-scaling updates for pod-based indexes: {"replicas": int, "pod_type": str} (either or both). Only those two keys are accepted; any other key is rejected by the server. "deployment_type" raises PineconeValueError client-side, since deployment type, cloud/region, and environment cannot be changed after creation.

  • schema (dict[str, Any] | IndexSchema | None) – Schema updates. On an index created with create(schema=...) the schema is fixed: nothing in it can be changed, including the embed/sparse_embed parameters of a string field. On an index created with create_for_model(), only semantic_text field parameters (read_parameters/write_parameters) can be updated; see the note after the examples.

  • read_capacity (dict[str, Any] | None) – Updated read capacity dict, either {"mode": "OnDemand"} or {"mode": "Dedicated", "dedicated": {...}}. Applies to managed and BYOC indexes.

  • deletion_protection (str | None) – "enabled" to block delete() on this index, "disabled" to allow it again.

  • tags (Mapping[str, str] | None) – Tag updates, merged into the index’s existing tags. Set a value to "" to delete that key; keys you don’t mention stay unchanged. The server applies its tag limit to the merged total, so adding tags to an index that already carries several can be rejected. {} is rejected client-side.

  • replicas (int | None) – Deprecated. Legacy pod-scaling replica count, translated into deployment={"replicas": ...}. Mutually exclusive with deployment.

  • pod_type (PodType | str | None) – Deprecated. Legacy pod type, translated into deployment={"pod_type": ...} alongside replicas. Mutually exclusive with deployment.

  • serverless_read_capacity (dict[str, Any] | None) – Deprecated. Legacy read-capacity keyword for managed indexes, translated straight into read_capacity. Mutually exclusive with read_capacity.

  • legacy_kwargs (Any)

Returns:

IndexModel reflecting the updated index state. Read status for how far an asynchronous change has got rather than assuming it landed.

Raises:

  • PineconeValueError – If name is empty, all kwargs are None, any dict kwarg is empty, deployment includes deployment_type, tags/deletion_protection are invalid, or deployment/read_capacity is combined with the deprecated keyword argument it translates to.

  • PineconeTypeError – If name is not a str, or if embed= or spec= is passed (neither has a translation here; the message shows the equivalent current call where one exists).

  • NotFoundError – If the index does not exist.

  • ApiError – Typically status 422 or 400, if schema is passed for an index created with create(schema=...) (even unchanged fields are refused), or if deployment has a key other than replicas or pod_type. The message comes from the server and can read as a raw deserialization error rather than naming the field.

Return type:

IndexModel

Examples

Scale a pod-based index. Pod scaling is applied in the background, so read index.status on the returned model to see how far the change has got rather than assuming it landed:

async with AsyncPinecone(api_key="your-api-key") as pc:
    index = await pc.indexes.configure(
        "legacy-recommender", deployment={"replicas": 4, "pod_type": "p1.x2"}
    )
    print(index.status.state)

Tag updates merge into the tags the index already carries. Given an index tagged {"env": "staging", "team": "search"}, the call below sets env, deletes team (an empty value removes a key), and leaves every other tag as it was:

async with AsyncPinecone(api_key="your-api-key") as pc:
    index = await pc.indexes.configure(
        "my-index", tags={"env": "prod", "team": ""}
    )
    print(index.tags)

Note

Only semantic_text field parameters (read_parameters/ write_parameters) can be updated through schema=; other field types can’t be added, removed, or retyped after creation. Since create() cannot declare a semantic_text field directly, this only applies to indexes created with create_for_model(). On an index created with create(schema=...) the schema is fixed, and passing schema= is rejected.

Changed in version 10.0: Before/after:

# 9.x
await pc.indexes.configure("my-index", replicas=4, pod_type="p1.x2")
# 10.x
await pc.indexes.configure("my-index",
                           deployment={"replicas": 4, "pod_type": "p1.x2"})

embed= is gone entirely, along with the convert-to-integrated flow it drove; replicas=/pod_type=/ serverless_read_capacity= remain as deprecated keyword-only sugar for deployment=/read_capacity=; and the method returns the updated IndexModel instead of None.

Deprecated since version 10.0: replicas=, pod_type=, and serverless_read_capacity= are translated into deployment=/read_capacity= rather than sent as-is, and cannot be combined with the argument they translate to; passing both raises PineconeValueError. New code should use deployment=/read_capacity= directly.

async create_backup(index_name, *, name=None, description=None)[source]

Create a backup of an index.

Index-scoped shortcut for AsyncBackups.create, which does the same thing; the difference is that this one takes the index name positionally.

Parameters:

  • index_name (str) – Name of the index to back up.

  • name (str | None) – Your own name for the backup, e.g. "nightly-20240115". Omit it and the server assigns one.

  • description (str | None) – Free-text note stored with the backup, e.g. "pre-reindex snapshot".

Returns:

BackupModel describing the new backup. status is typically "Initializing" right after creation; poll describe_backup() until it reads "Ready" before restoring from it.

Raises:
Return type:

BackupModel

Examples

async with AsyncPinecone(api_key="your-api-key") as pc:
    backup = await pc.indexes.create_backup(
        "my-index", name="nightly-20240115"
    )
    print(backup.backup_id, backup.status)

Added in version 10.0: Graduated from pc.preview.indexes.create_backup, now returning the single top-level BackupModel.

list_backups(index_name, *, limit=None, pagination_token=None, include_deleted=None)[source]

List the backups of one index, following pages as you iterate.

Parameters:

  • index_name (str) – Name of the index whose backups to list.

  • limit (int | None) – Maximum number of backups to yield across all pages. Must be a positive integer. None yields all backups. It also sets the requested page size, but only on a request that carries no pagination token: every later page is sized by the token, which already encodes it.

  • pagination_token (str | None) – Token from an earlier call, to resume where that call stopped. limit still caps the total yield, but it is not sent alongside a token (see above). See Pagination.

  • include_deleted (bool | None) – When True, include backups of every index that has ever used index_name, deleted ones included; those backups carry a non-None source_index_deleted_at. When None (the default) the parameter is omitted entirely and the server’s default (false) applies.

Returns:

AsyncPaginator over BackupModel instances.

Raises:

  • PineconeValueError – If index_name is empty or limit is zero or negative.

  • PineconeTypeError – If index_name is not a str.

  • NotFoundError – If index_name does not resolve to an active index, which is not the same as the name being unknown; see the note after the examples.

Return type:

AsyncPaginator[BackupModel]

Examples

async with AsyncPinecone(api_key="your-api-key") as pc:
    async for backup in pc.indexes.list_backups("my-index"):
        print(backup.backup_id, backup.status)

Once every index that used a name has been deleted, that name’s backups come back only with include_deleted=True; without it this raises NotFoundError. They are the ones carrying a source_index_deleted_at:

async with AsyncPinecone(api_key="your-api-key") as pc:
    backups = await pc.indexes.list_backups(
        "legacy-catalog", include_deleted=True
    ).to_list()
    print([b.backup_id for b in backups if b.source_index_deleted_at])

Important

NotFoundError here does not necessarily mean index_name was never used. With include_deleted omitted or False, index_name must resolve to an active index: if every index that used the name has since been deleted, this raises NotFoundError rather than returning an empty list. Retry with include_deleted=True to get those backups back; a NotFoundError there means the name was never used in this project.

See also

AsyncBackups.list is the project-wide listing, where the index name is an optional filter. It hands back one page for you to drive the token yourself, rather than a paginator that follows the pages for you.

Added in version 10.0: Graduated from pc.preview.indexes.list_backups, and gained include_deleted.

async describe_backup(backup_id)[source]

Describe a backup by its ID.

Backups are identified independently of any index, so despite living on indexes this takes a backup ID rather than an index name.

Parameters:

backup_id (str) – Identifier of the backup to describe, as returned in backup_id by create_backup().

Returns:

BackupModel with the current state of the backup.

Raises:
Return type:

BackupModel

Examples

async with AsyncPinecone(api_key="your-api-key") as pc:
    backup = await pc.indexes.describe_backup("bk-abc123")
    print(backup.status, backup.record_count)

See also

AsyncBackups.describe is the same lookup reached through pc.backups, which takes backup_id as a keyword argument rather than positionally.

Added in version 10.0: Graduated from pc.preview.indexes.describe_backup.

AsyncCollections

class pinecone.async_client.collections.AsyncCollections(http)[source]

Bases: object

Async control-plane operations for Pinecone collections.

A collection is a static, point-in-time copy of a pod-based index’s vector data, held outside the index. Reach it as pc.collections; not constructed directly: AsyncPinecone builds and caches its own instance on first access.

Collections are the snapshot mechanism for pod-based indexes; AsyncBackups is the one for serverless and BYOC indexes. The difference that decides which you want is restore: a backup can be restored into a new index with create_index_from_backup(), and this SDK cannot restore a collection: only API versions before 2026-07 create an index from one.

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    for col in await pc.collections.list():
        print(col.name, col.status)

See also

AsyncBackups, the equivalent for serverless and BYOC indexes, and the only snapshot this SDK can restore.

Parameters:

http (AsyncHTTPClient)

__init__(http)[source]
Parameters:

http (AsyncHTTPClient)

Return type:

None

async create(*, name, source)[source]

Create a collection from an existing pod-based index.

A collection is a static copy of an index’s vector data, held outside the index as a snapshot of its contents at the moment it was taken. Only a pod-based index can be used as a source, and it must already be ready. The call returns as soon as creation starts; it does not wait for the collection to become ready.

Parameters:

  • name (str) – Name for the new collection: lowercase alphanumeric characters and hyphens, not starting or ending with a hyphen (e.g. "movie-embeddings-snapshot").

  • source (str) – Name of the pod-based index to copy.

Returns:

CollectionModel whose status is "Initializing" until the snapshot has been built.

Raises:
Return type:

CollectionModel

Examples

The collection is still being built when the call returns, so its status is "Initializing" rather than "Ready":

col = await pc.collections.create(
    name="movie-embeddings-snapshot", source="movie-recommendations"
)
print(col.status)

There is no timeout= argument to wait on. Poll describe() until the status leaves "Initializing", then read col.status to see where it settled:

import asyncio

while col.status == "Initializing":
    await asyncio.sleep(5)
    col = await pc.collections.describe(col.name)

Note

This SDK cannot create an index from a collection; only API versions before 2026-07 can. AsyncIndexes.create() rejects source_collection with a PineconeTypeError in both spellings: as a top-level keyword argument, and nested in a PodSpec passed to the deprecated spec= argument. If you need a snapshot you can restore, back up a serverless index with AsyncBackups.create() and restore it with create_index_from_backup().

See also

AsyncBackups.create(), the serverless equivalent, whose snapshot can be restored into a new index.

async list()[source]

List every collection in the project.

There’s no filtering, sorting, or pagination; all collections come back at once.

Returns:

CollectionList, which supports iteration, len(), index access, and a names() convenience method.

Return type:

CollectionList

Examples

collections = await pc.collections.list()
print(collections.names())
for col in collections:
    print(col.name, col.status)

See also

AsyncBackups.list() lists snapshots of serverless and BYOC indexes, and unlike this one is paginated.

async describe(name)[source]

Get details about a collection.

Parameters:

name (str) – Name of the collection to describe.

Returns:

CollectionModel with name, status, environment, size (bytes on disk), dimension, and vector_count.

Raises:
Return type:

CollectionModel

Examples

size is how much space the snapshot occupies, in bytes, not the dimension of its vectors. It, dimension, and vector_count are None until the collection finishes initializing:

desc = await pc.collections.describe("movie-embeddings-snapshot")
print(desc.status, desc.dimension, desc.vector_count, desc.size)

See also

AsyncBackups.describe(), the serverless equivalent, which reports record_count and size_bytes instead.

async delete(name)[source]

Delete a collection permanently.

Deletion is asynchronous: the call returns as soon as the request is accepted, and the collection can still show up in list() for a short time afterwards. While a collection is still being created or deleted, the server refuses to delete its source index.

Parameters:

name (str) – Name of the collection to delete.

Raises:
Return type:

None

Examples

await pc.collections.delete("movie-embeddings-snapshot")

See also

AsyncBackups.delete(), the serverless equivalent, which takes a backup_id rather than a name.

AsyncBackups

class pinecone.async_client.backups.AsyncBackups(http)[source]

Bases: object

Stored, point-in-time snapshots of a serverless or BYOC index.

A backup captures an index’s records and schema so that a new index can be created from it later with create_index_from_backup(). Backups are identified by a backup_id and outlive the index they were taken from. Reached as pc.backups; not constructed directly.

Pod-based indexes cannot be backed up; their snapshot mechanism is AsyncCollections.

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    page = await pc.backups.list(limit=100)
    print([b.backup_id for b in page])

See also

  • list_backups(), the index-scoped listing, which walks every page for you.

  • Error handling, for the exceptions these methods raise and which ones to retry.

Parameters:

http (AsyncHTTPClient)

__init__(http)[source]
Parameters:

http (AsyncHTTPClient)

Return type:

None

async create(*, index_name, name=None, description=None)[source]

Create a backup of an existing index.

Only serverless and BYOC indexes can be backed up. The call returns as soon as the server accepts the request, not when the backup is ready.

Parameters:

  • index_name (str) – Name of the index to back up.

  • name (str | None) – Name for the backup, e.g. "daily-20240115". When omitted, the backup has no name and is identified only by its backup_id.

  • description (str | None) – Description for the backup.

Returns:

A BackupModel describing the new backup, with status "Initializing". Poll describe() to follow it.

Raises:

  • PineconeValueError – If index_name is empty.

  • PineconeTypeError – If index_name is not a str.

  • ForbiddenError – If the organization’s plan does not include backups.

  • NotFoundError – If index_name does not resolve to an index in this project.

  • ApiError – If index_name names a pod-based index, which is snapshotted into a collection rather than a backup.

Return type:

BackupModel

Examples

Poll describe() until the status leaves "Initializing". A backup that fails settles on "InitializationFailed", so waiting for "Ready" alone could loop forever.

import asyncio

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    backup = await pc.backups.create(index_name="product-search")
    print(backup.backup_id, backup.status)

    while backup.status == "Initializing":
        await asyncio.sleep(10)
        backup = await pc.backups.describe(backup_id=backup.backup_id)
    print(backup.status)

Give the backup a name and description so a later listing identifies it by more than its backup_id:

async with AsyncPinecone(api_key="your-api-key") as pc:
    backup = await pc.backups.create(
        index_name="product-search",
        name="daily-20240115",
        description="Scheduled daily backup before reindexing",
    )

See also

async list(*, index_name=None, limit=None, pagination_token=None, include_deleted=None)[source]

List one page of backups.

When index_name is given, lists backups of that index only; otherwise lists every backup in the project. One call returns one page, and iterating the result does not fetch the next one. Follow pagination.next yourself (see Pagination), or use list_backups(), which walks every page of one index’s backups for you.

Parameters:

  • index_name (str | None) – Index name to scope the listing to, or None for every backup in the project.

  • limit (int | None) – Maximum number of results per page, e.g. 100. When None, the server applies its default. The SDK drops limit when pagination_token is given, because the token already carries the page size.

  • pagination_token (str | None) – Token for the next page, taken from BackupList.pagination.next.

  • include_deleted (bool | None) – When True, include backups of every index that has ever used index_name, including deleted ones. Defaults to the server’s behavior, which excludes them. Only valid together with index_name.

Returns:

A BackupList holding one page, supporting iteration, len(), and index access. pagination is None on the final page. Backups created or deleted during a walk can shift later pages, so de-duplicate by backup_id.

Raises:
Return type:

BackupList

Examples

Passing index_name scopes the listing to one index:

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    for backup in await pc.backups.list(index_name="product-search"):
        print(backup.name, backup.status)

Walk every page of the project-wide listing:

async with AsyncPinecone(api_key="your-api-key") as pc:
    page = await pc.backups.list(limit=100)
    backups = list(page)
    while page.pagination and page.pagination.next:
        page = await pc.backups.list(
            pagination_token=page.pagination.next
        )
        backups.extend(page)
    print([b.backup_id for b in backups])

Pass include_deleted=True to reach the backups of an index you have already deleted:

async with AsyncPinecone(api_key="your-api-key") as pc:
    orphaned = await pc.backups.list(
        index_name="legacy-catalog",
        include_deleted=True,
    )
    print([b.backup_id for b in orphaned if b.source_index_deleted_at])

Note

If every index that used index_name has been deleted, listing without include_deleted raises NotFoundError rather than returning an empty list. Pass include_deleted=True to see their backups.

Changed in version 10.0: Added include_deleted. BackupModel now carries source_index_deleted_at instead of dimension/metric.

async describe(*, backup_id)[source]

Get the current state of one backup.

Parameters:

backup_id (str) – The identifier of the backup to describe.

Returns:

A BackupModel whose status is "Initializing", "Ready", or "InitializationFailed", alongside the source_index_name it was taken from, the captured schema, and the record_count and size_bytes of the snapshot.

Raises:
Return type:

BackupModel

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    backup = await pc.backups.describe(backup_id="bk-abc123")
    print(backup.status, backup.source_index_name)

See also

describe_backup(), the same call under the indexes namespace.

async get(*, backup_id)[source]

Get detailed information about a backup (alias for describe()).

Parameters:

backup_id (str) – The identifier of the backup.

Returns:

A BackupModel whose status is "Initializing", "Ready", or "InitializationFailed", alongside the source_index_name it was taken from, the captured schema, and the record_count and size_bytes of the snapshot.

Raises:
Return type:

BackupModel

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    backup = await pc.backups.get(backup_id="bk-abc123")
    print(backup.status, backup.source_index_name)
async delete(*, backup_id)[source]

Delete a backup.

Parameters:

backup_id (str) – The identifier of the backup to delete.

Raises:
Return type:

None

Examples

Deleting a backup leaves its source index, other backups of that index, and any index restored from it untouched:

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    await pc.backups.delete(backup_id="bk-abc123")

AsyncBackupSchedules

class pinecone.async_client.backup_schedules.AsyncBackupSchedules(http)[source]

Bases: object

Recurring, time-based backups of a single index.

A schedule snapshots its index on a fixed cadence and retains each backup for a set number of days, so you do not have to call create() on a timer of your own. Reached as pc.backup_schedules; not constructed directly.

At most one schedule per index can be enabled at a time. The backups a schedule produces are ordinary backups: read one with describe(), or list a schedule’s own runs with history().

Note

Backups are a plan entitlement. A project without it gets ForbiddenError, not NotFoundError, even for a schedule that does not exist. On-demand backups need the same entitlement.

Examples

Back up an index every day and keep each backup for 90 days:

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    schedule = await pc.backup_schedules.create(
        index_name="product-search",
        name="compliance-snapshots",
        frequency="daily",
        retention_days=90,
    )
    print(schedule.schedule_id, schedule.next_scheduled_run)

See also

Error handling for the exceptions these methods raise and which ones are worth retrying.

Parameters:

http (AsyncHTTPClient)

__init__(http)[source]
Parameters:

http (AsyncHTTPClient)

Return type:

None

async create(*, index_name, name, frequency, retention_days)[source]

Create a time-based backup schedule for an index.

The schedule is created enabled, with its first run already planned. For a single backup taken now, use create() instead.

Parameters:

  • index_name (str) – Name of the serverless or BYOC index to back up, for example "product-search".

  • name (str) – Name for the schedule, for example "compliance-snapshots". Each backup it produces is named "{name}-{run timestamp}", such as "compliance-snapshots-20260403T060000Z".

  • frequency (str) – How often to back up the index: "daily", "weekly", or "monthly".

  • retention_days (int) – Days to keep each backup this schedule produces. Must be at least 1; the server enforces the maximum.

Returns:

A BackupScheduleModel for the new schedule, with next_scheduled_run set. The retention window comes back as retention_expire_after_days.

Raises:

  • PineconeValueError – If index_name or name is empty, if frequency is not a supported cadence, or if retention_days is less than 1.

  • PineconeTypeError – If index_name or name is not a str.

  • ForbiddenError – If the project’s plan does not include scheduled backups.

  • NotFoundError – If the index does not exist.

  • ConflictError – If the index already has an enabled schedule. Disable or delete that one first.

  • ApiError – If index_name names a pod-based index, which cannot be scheduled.

Return type:

BackupScheduleModel

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    schedule = await pc.backup_schedules.create(
        index_name="product-search",
        name="compliance-snapshots",
        frequency="daily",
        retention_days=90,
    )
    print(schedule.schedule_id, schedule.next_scheduled_run)
async list(*, index_name, limit=None, pagination_token=None)[source]

List one page of an index’s backup schedules.

Disabled schedules are included, so an index can list several schedules even though at most one is enabled. To walk every page, use iter_schedules(); see Pagination.

Parameters:

  • index_name (str) – Name of the index whose schedules to list.

  • limit (int | None) – Maximum results per page, for example 20. None uses the server’s page size. Ignored when pagination_token is set, because the token carries its own page size.

  • pagination_token (str | None) – The pagination.next value from the previous page, or None for the first page.

Returns:

A BackupScheduleList of BackupScheduleModel that supports iteration, len(), and index access. Its pagination is None on the last page.

Raises:
Return type:

BackupScheduleList

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    schedules = await pc.backup_schedules.list(index_name="product-search")
    print(schedules.names())
    print([s.schedule_id for s in schedules.enabled_schedules()])

names() and enabled_schedules() read only this page, so check schedules.pagination before concluding that an index has no enabled schedule.

iter_schedules(*, index_name, limit=None, pagination_token=None)[source]

Iterate every backup schedule on an index, fetching pages on demand.

The auto-paginating twin of list().

Parameters:

  • index_name (str) – Name of the index whose schedules to iterate.

  • limit (int | None) – Maximum number of schedules to yield across all pages. Must be positive. None yields all of them.

  • pagination_token (str | None) – Token to resume from a previous call. limit still caps the total yield.

Returns:

A AsyncPaginator over BackupScheduleModel instances.

Raises:

  • PineconeValueError – If index_name is empty or limit is zero or negative. Raised as soon as you call this method, before the first page is fetched.

  • PineconeTypeError – If index_name is not a str.

  • ForbiddenError – If the project’s plan does not include scheduled backups. Raised while iterating, when a page is fetched.

  • NotFoundError – If the index does not exist.

Return type:

AsyncPaginator[BackupScheduleModel]

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    async for s in pc.backup_schedules.iter_schedules(
        index_name="product-search"
    ):
        print(s.schedule_id, s.frequency, s.enabled)
async describe(*, schedule_id)[source]

Get the current configuration of one backup schedule.

Parameters:

schedule_id (str) – ID of the schedule to describe, from create() or list(). Not the index name.

Returns:

A BackupScheduleModel carrying the schedule’s frequency, its enabled flag, its retention_expire_after_days window, and next_scheduled_run, which is None while the schedule is disabled.

Raises:
Return type:

BackupScheduleModel

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    schedule = await pc.backup_schedules.describe(
        schedule_id="e88f7273-42aa-47e9-af73-593827136867"
    )
    print(schedule.enabled, schedule.next_scheduled_run)
async get(*, schedule_id)[source]

Get the current configuration of one backup schedule (alias for describe()).

Parameters:

schedule_id (str) – ID of the schedule to describe, from create() or list(). Not the index name.

Returns:

A BackupScheduleModel carrying the schedule’s frequency, its enabled flag, its retention_expire_after_days window, and next_scheduled_run, which is None while the schedule is disabled.

Raises:
Return type:

BackupScheduleModel

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    schedule = await pc.backup_schedules.get(
        schedule_id="e88f7273-42aa-47e9-af73-593827136867"
    )
    print(schedule.frequency)
async update(*, schedule_id, frequency=None, retention_days=None, enabled=None)[source]

Update a backup schedule’s cadence, retention, or enabled state.

Only the arguments you pass change; the rest keep their current values. A schedule’s name and index cannot be changed.

Parameters:

  • schedule_id (str) – ID of the schedule to update.

  • frequency (str | None) – New cadence: "daily", "weekly", or "monthly". None leaves it unchanged.

  • retention_days (int | None) – New retention window in days, at least 1. Also applies to unexpired backups this schedule already produced. None leaves it unchanged.

  • enabled (bool | None) – False pauses the schedule and clears next_scheduled_run; True resumes a paused one (see the warning below). None leaves it unchanged.

Returns:

A BackupScheduleModel with the updated configuration. After enabled=False its next_scheduled_run is None.

Raises:

  • PineconeValueError – If schedule_id is empty, if frequency is set to an unsupported cadence, or if retention_days is set to less than 1.

  • PineconeTypeError – If schedule_id is not a str.

  • ForbiddenError – If the project’s plan does not include scheduled backups.

  • NotFoundError – If the schedule does not exist.

  • ConflictError – If enabled=True and another schedule on the same index is already enabled.

Return type:

BackupScheduleModel

Examples

Move a schedule to a weekly cadence with a shorter retention window. Its name and enabled state stay as they were:

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    updated = await pc.backup_schedules.update(
        schedule_id="e88f7273-42aa-47e9-af73-593827136867",
        frequency="weekly",
        retention_days=30,
    )
    print(updated.frequency, updated.retention_expire_after_days)
    print(updated.name, updated.enabled)

Pause the schedule, keeping the rest of its configuration:

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    paused = await pc.backup_schedules.update(
        schedule_id="e88f7273-42aa-47e9-af73-593827136867",
        enabled=False,
    )
    print(paused.frequency, paused.next_scheduled_run)

Warning

Re-enabling a paused schedule plans its next run from the time of the update, not from its old slot, so a pause shifts the cadence. Re-enabling raises ConflictError if another schedule on the same index is already enabled.

async delete(*, schedule_id)[source]

Delete a backup schedule.

Deleting a schedule stops its future runs. Backups it already produced are not deleted.

Parameters:

schedule_id (str) – ID of the schedule to delete.

Raises:
Return type:

None

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    await pc.backup_schedules.delete(
        schedule_id="e88f7273-42aa-47e9-af73-593827136867"
    )

Important

If a delete’s response is lost and the call is retried, the retry raises NotFoundError because the first attempt already deleted the schedule. Treat NotFoundError from a delete as success.

async history(*, schedule_id, limit=None, pagination_token=None)[source]

List one page of the backups a schedule has produced.

Each row is a backup. The schedule’s next run is listed as soon as it is planned, before it starts, so check each row’s status. To walk every page, use iter_history(); see Pagination.

Parameters:

  • schedule_id (str) – ID of the schedule whose history to list.

  • limit (int | None) – Maximum results per page, for example 20. None uses the server’s page size. Ignored when pagination_token is set, because the token carries its own page size.

  • pagination_token (str | None) – The pagination.next value from the previous page, or None for the first page.

Returns:

A BackupScheduleHistoryList of BackupScheduleHistoryItem that supports iteration, len(), and index access. Its pagination is None on the last page.

Raises:
Return type:

BackupScheduleHistoryList

Examples

Walk the history a page at a time and print the finished backups:

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    pagination_token = None
    while True:
        runs = await pc.backup_schedules.history(
            schedule_id="e88f7273-42aa-47e9-af73-593827136867",
            pagination_token=pagination_token,
        )
        for run in runs:
            if run.status == "Ready":
                print(run.name, run.size_bytes)
        pagination_token = runs.pagination.next if runs.pagination else None
        if pagination_token is None:
            break
iter_history(*, schedule_id, limit=None, pagination_token=None)[source]

Iterate every backup a schedule has produced, fetching pages on demand.

The auto-paginating twin of history().

Parameters:

  • schedule_id (str) – ID of the schedule whose history to iterate.

  • limit (int | None) – Maximum number of backups to yield across all pages. Must be positive. None yields all of them.

  • pagination_token (str | None) – Token to resume from a previous call. limit still caps the total yield.

Returns:

A AsyncPaginator over BackupScheduleHistoryItem instances.

Raises:

  • PineconeValueError – If schedule_id is empty or limit is zero or negative. Raised as soon as you call this method, before the first page is fetched.

  • PineconeTypeError – If schedule_id is not a str.

  • ForbiddenError – If the project’s plan does not include scheduled backups. Raised while iterating, when a page is fetched.

  • NotFoundError – If the schedule does not exist.

Return type:

AsyncPaginator[BackupScheduleHistoryItem]

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    async for run in pc.backup_schedules.iter_history(
        schedule_id="e88f7273-42aa-47e9-af73-593827136867"
    ):
        if run.status == "Ready":
            print(run.name, run.size_bytes)

AsyncRestoreJobs

class pinecone.async_client.restore_jobs.AsyncRestoreJobs(http)[source]

Bases: object

Progress reports for restores of a backup into a new index.

create_index_from_backup() hands back a restore_job_id and leaves the restore running in the background; use this namespace to follow it to completion. Reached as pc.restore_jobs; not constructed directly.

A restore job is not a backup: AsyncBackups manages the snapshots themselves, while a job here is a read-only record of one attempt at turning a snapshot back into an index.

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    job = await pc.restore_jobs.describe(job_id="rj-abc123")
    print(job.status, job.target_index_name)

See also

Error handling, for the exceptions these methods raise and which ones to retry.

Parameters:

http (AsyncHTTPClient)

__init__(http)[source]
Parameters:

http (AsyncHTTPClient)

Return type:

None

async list(*, limit=None, pagination_token=None)[source]

List one page of the project’s restore jobs.

One call returns one page, and iterating the result does not fetch the next one. Follow pagination.next yourself (see Pagination). The listing is not exhaustive; see the warning below.

Parameters:

  • limit (int | None) – Maximum number of results per page, e.g. 100. When None, the server applies its default. The SDK drops limit when pagination_token is given, because the token already carries the page size.

  • pagination_token (str | None) – Token for the next page, taken from RestoreJobList.pagination.next.

Returns:

A RestoreJobList holding one page, supporting iteration, len(), and index access. pagination is None on the final page.

Return type:

RestoreJobList

Examples

Walk every page, keying jobs by restore_job_id because pages can overlap:

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    by_id = {}
    page = await pc.restore_jobs.list(limit=100)
    while True:
        for job in page:
            by_id[job.restore_job_id] = job
        if not (page.pagination and page.pagination.next):
            break
        page = await pc.restore_jobs.list(
            pagination_token=page.pagination.next
        )

    for job in by_id.values():
        print(job.restore_job_id, job.target_index_name, job.status)

When one page is all you want:

async with AsyncPinecone(api_key="your-api-key") as pc:
    page = await pc.restore_jobs.list(limit=5)
    print(len(page))

Warning

The restore-job listing is not exhaustive. Pages can overlap, pagination can end while jobs remain, and jobs whose target index has been deleted are left out. De-duplicate by restore_job_id, and never conclude a job does not exist because the listing omits it. To track a specific restore, keep its restore_job_id and call describe().

async describe(*, job_id)[source]

Get the current state of one restore job.

Parameters:

job_id (str) – The identifier of the restore job to describe.

Returns:

A RestoreJobModel naming the backup_id restored and the target_index_name it lands in. status is one of "Pending", "Completed", "Failed", or "Cancelled"; a restore that is running reports "Pending". percent_complete and completed_at are set only once status is "Completed", so percent_complete cannot report progress.

Raises:
Return type:

RestoreJobModel

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    job = await pc.restore_jobs.describe(job_id="rj-abc123")
    print(job.status, job.target_index_name)

To wait for a restore, poll until status leaves "Pending". A deadline keeps a stuck job from looping forever:

import asyncio
import time

async with AsyncPinecone(api_key="your-api-key") as pc:
    deadline = time.monotonic() + 600
    job = await pc.restore_jobs.describe(job_id="rj-abc123")
    while job.status == "Pending" and time.monotonic() < deadline:
        await asyncio.sleep(5)
        job = await pc.restore_jobs.describe(job_id="rj-abc123")

    print(job.status, job.completed_at)

Warning

A NotFoundError here does not prove the job does not exist. The server also answers 404 on a transient failure and for a job whose target index has been deleted. Treat a 404 as possibly transient unless you know the ID is wrong.

AsyncInference

class pinecone.async_client.inference.AsyncInference(config)[source]

Bases: object

Embedding and reranking against Pinecone’s hosted models.

Reached as pc.inference. Call these when you want the vectors or the scores in your own hands: to store somewhere else, to embed a query yourself, or to rerank candidates that came from another system. If instead you want Pinecone to embed on your behalf, give a document index a string field with integrated embedding (embed / sparse_embed), which needs no explicit embed step. Legacy integrated indexes, created via create_for_model(), do the same through the legacy Records API (upsert_records()). Not constructed directly.

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    embeddings = await pc.inference.embed(
        model="multilingual-e5-large",
        inputs=["Vector databases index embeddings for similarity search."],
        parameters={"input_type": "passage"},
    )
    print(len(embeddings))

See also

Error handling covers the exceptions every method here can raise, and how to retry them.

Parameters:

config (PineconeConfig)

class EmbedModel(value)

Bases: str, Enum

Known embedding models, for integrated embedding and pc.inference.

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.

Multilingual_E5_Large = 'multilingual-e5-large'
Pinecone_Sparse_English_V0 = 'pinecone-sparse-english-v0'
Llama_Text_Embed_V2 = 'llama-text-embed-v2'
Pinecone_Sparse_Multilingual_V0 = 'pinecone-sparse-multilingual-v0'
class RerankModel(value)

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'
__init__(config)[source]
Parameters:

config (PineconeConfig)

Return type:

None

async close()[source]

Close the underlying HTTP client.

Return type:

None

property model: AsyncModelResource

Model discovery for this namespace.

Returns:

An AsyncModelResource exposing list() and get().

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    info = await pc.inference.model.get("multilingual-e5-large")
    print(info.default_dimension)

    models = await pc.inference.model.list()
    print(models.names())
async embed(model, inputs, parameters=None)[source]

Generate embeddings for the provided inputs.

Many models are asymmetric: they embed a stored passage and a search query differently. Where a model accepts input_type, pass it in parameters, or the query and the corpus will not line up.

Parameters:

  • model (EmbedModel | str) – Embedding model name, e.g. "multilingual-e5-large". An EmbedModel member is accepted too; call list_models() with type="embed" for the names currently available.

  • inputs (str | Sequence[str] | Sequence[Mapping[str, Any]]) – The text to embed. Any sequence (list, tuple) of strings or mappings; a bare string is wrapped for you and still comes back as a one-item result rather than a lone embedding.

  • parameters (Mapping[str, Any] | None) – Model-specific parameters (e.g., {"input_type": "passage", "truncate": "END"}). Call get_model() and read supported_parameters to discover the keys a given model accepts.

Returns:

EmbeddingsList with one embedding per input, in input order. Iterating it (or indexing into it) yields the embeddings themselves, and data holds the same list. vector_type says which shape they are and so which fields they carry: DenseEmbedding has values, while SparseEmbedding has sparse_values and sparse_indices. model names the model that served the request, and usage.total_tokens the tokens counted for it.

Raises:

  • PineconeValueError – If model is empty or inputs is empty.

  • PineconeTypeError – If inputs has an invalid type.

  • NotFoundError – If model is not available to this project: either no such model exists, or the project is not authorized to use it. The error does not distinguish the two cases.

Return type:

EmbeddingsList

Examples

Embed the text you intend to store. input_type="passage" is the corpus side of a search:

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    embeddings = await pc.inference.embed(
        model="multilingual-e5-large",
        inputs=[
            "Vector databases index embeddings for similarity search.",
            "Reranking reorders candidate results by relevance.",
        ],
        parameters={"input_type": "passage"},
    )
    print(len(embeddings), embeddings.vector_type)

Embed the search query with input_type="query". The two are not interchangeable: a query embedded as a passage will not land where the model expects it:

async with AsyncPinecone(api_key="your-api-key") as pc:
    query = await pc.inference.embed(
        model="multilingual-e5-large",
        inputs="How does reranking work?",
        parameters={"input_type": "query"},
    )
    print(len(query.data))

Note

To store these vectors, upsert each embedding’s values into a dense_vector field of a document index (here embedding) through documents:

index = await pc.index(name="product-search")
await index.documents.upsert(
    namespace="products-en",
    documents=[{"_id": "prod-1", "embedding": embeddings.data[0].values}],
)

values exists only on the dense shape. A sparse embedding model returns SparseEmbedding objects, which carry sparse_values and sparse_indices and have no values field. Reading .values on one hands back a dict-view method rather than a vector, and raises nothing to warn you. Branch on embeddings.vector_type when the model is not fixed in advance.

See also

Embeddings covers storing and searching these vectors. On a document index whose string field uses integrated embedding, Pinecone embeds the text for you and no call here is needed.

async rerank(model, query, documents, rank_fields=['text'], return_documents=True, top_n=None, parameters=None)[source]

Rerank documents by relevance to a query.

Parameters:

  • model (RerankModel | str) – Reranking model name, e.g. "bge-reranker-v2-m3". A RerankModel member is accepted too; call list_models() with type="rerank" for the names currently available.

  • query (str) – The text the documents are scored against.

  • documents (Sequence[str] | Sequence[Mapping[str, Any]]) – Documents to rank. Any sequence (list, tuple) of strings or mappings. A bare string is wrapped as {"text": ...}, which is what the default rank_fields scores on.

  • rank_fields (Sequence[str]) – The document keys to score, e.g. ["summary"] when the text lives under summary. Defaults to ["text"].

  • return_documents (bool) – Send each document back in its result. Leave it True to read .document; set it False when you already hold the documents and want only index and score.

  • top_n (int | None) – Keep only the n best-scoring documents. None, the default, returns a result for every document.

  • parameters (Mapping[str, Any] | None) – Model-specific parameters. Call get_model() and read supported_parameters to discover the keys a given model accepts.

Returns:

RerankResult whose data is a list of RankedDocument ordered by descending score. Each one carries the index it held in documents and, unless return_documents is False, the document itself. model names the model that served the request, and usage.rerank_units the units counted for it.

Raises:

  • PineconeValueError – If model, query, or documents is empty, or top_n is less than 1.

  • PineconeTypeError – If documents has an invalid type.

  • NotFoundError – If model does not name a model the API serves. A typo in the model name surfaces here, so check this before assuming the request body was at fault.

  • ForbiddenError – If the project is not authorized to use model, including when model has been deprecated.

Return type:

RerankResult

Examples

Rank a list of strings against the query. result.data comes back ordered by descending relevance, not by the order the documents were passed in, so read .index to map a result back to its position in documents. The top hit below is the second document, so its .index is 1, not 0:

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    result = await pc.inference.rerank(
        model="bge-reranker-v2-m3",
        query="Tell me about tech companies",
        documents=["Apple is a fruit.", "Acme Inc. revolutionized tech."],
        top_n=1,
    )
    top = result.data[0]
    print(top.index, top.score, top.document["text"])

Pass mappings instead when you want your own identifiers back alongside the scores. Every key other than the ones named in rank_fields rides along untouched and comes back in .document:

async with AsyncPinecone(api_key="your-api-key") as pc:
    result = await pc.inference.rerank(
        model="bge-reranker-v2-m3",
        query="Tell me about tech companies",
        documents=[
            {"id": "doc-1", "summary": "Apple is a fruit."},
            {"id": "doc-2", "summary": "Acme Inc. revolutionized tech."},
        ],
        rank_fields=["summary"],
        top_n=1,
    )
    print(result.data[0].document["id"])

Note

The model you request may not be the model that serves the request; Pinecone may substitute a different one. result.model reports which one did, so read it there rather than assuming it echoes model.

See also

search() on a legacy integrated index takes a rerank argument that reranks that search’s own hits in one round trip. Reach for the method here when the candidates came from somewhere else.

async list_models(*, type=None, vector_type=None)[source]

List the inference models available to this project.

Parameters:

  • type (str | None) – Restrict the listing to one model type, "embed" or "rerank". Omit it to get both.

  • vector_type (str | None) – Restrict embedding models to those producing "dense" or "sparse" vectors. Carries meaning only alongside type="embed".

Returns:

ModelInfoList, a sequence of ModelInfo supporting iteration, indexing and len(), plus names() when you want the model identifiers alone.

Raises:

PineconeValueError – If type or vector_type is not one of the values above, or if vector_type is paired with type="rerank". The client rejects that pairing rather than ignoring it.

Return type:

ModelInfoList

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    models = await pc.inference.list_models()
    print(models.names())

Narrow to the embedding models that produce sparse vectors:

async with AsyncPinecone(api_key="your-api-key") as pc:
    sparse = await pc.inference.list_models(
        type="embed",
        vector_type="sparse",
    )
    print(sparse.names())
async get_model(*, model=None, **kwargs)[source]

Describe one inference model.

Parameters:

  • model (str) – The model name to look up, e.g. "multilingual-e5-large". Call list_models() for the names currently available.

  • model_name (str) – Deprecated alias for model. Passing both raises PineconeValueError.

  • kwargs (str)

Returns:

ModelInfo with supported_parameters (the keys parameters accepts on embed() and rerank() for this model), type, and, for embedding models, vector_type, default_dimension and supported_dimensions.

Raises:
Return type:

ModelInfo

Examples

supported_parameters is what embed() and rerank() point at for discovering the keys their parameters argument accepts, and each entry names the values it will take:

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    model_info = await pc.inference.get_model(
        model="multilingual-e5-large",
    )
    print(model_info.type)
    for p in model_info.supported_parameters:
        print(p.parameter, p.allowed_values)
class pinecone.async_client.inference.AsyncModelResource(inference)[source]

Bases: object

Discovery for the embedding and reranking models a project can use.

Reached as pc.inference.model. Its two methods are the same operations as AsyncInference.list_models() and AsyncInference.get_model(); take whichever reads better at the call site. Not constructed directly.

Examples

An unfiltered listing spans both embedding and reranking models:

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    models = await pc.inference.model.list()
    print(models.names())
Parameters:

inference (AsyncInference)

__init__(inference)[source]
Parameters:

inference (AsyncInference)

Return type:

None

async list(*, type=None, vector_type=None)[source]

List the inference models available to this project.

Delegates to AsyncInference.list_models().

Parameters:

  • type (str | None) – Restrict the listing to one model type, "embed" or "rerank". Omit it to get both.

  • vector_type (str | None) – Restrict embedding models to those producing "dense" or "sparse" vectors. Carries meaning only alongside type="embed".

Returns:

ModelInfoList, a sequence of ModelInfo supporting iteration, indexing and len(), plus names() when you want the model identifiers alone.

Raises:

PineconeValueError – If type or vector_type is not one of the values above, or if vector_type is paired with type="rerank". The client rejects that pairing rather than ignoring it.

Return type:

ModelInfoList

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    for info in await pc.inference.model.list():
        print(info.model, info.type)

Narrow to the embedding models that produce sparse vectors:

async with AsyncPinecone(api_key="your-api-key") as pc:
    sparse = await pc.inference.model.list(
        type="embed",
        vector_type="sparse",
    )
    print(sparse.names())
async get(model=None, **kwargs)[source]

Describe one inference model.

Delegates to AsyncInference.get_model().

Parameters:

  • model (str) – The model name to look up, e.g. "multilingual-e5-large". Call list() for the names currently available.

  • model_name (str) – Deprecated alias for model. Passing both raises PineconeValueError.

  • kwargs (str)

Returns:

ModelInfo with supported_parameters (the keys this model accepts in a parameters argument), type, and, for embedding models, vector_type, default_dimension and supported_dimensions.

Raises:
Return type:

ModelInfo

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    info = await pc.inference.model.get("multilingual-e5-large")
    print(info.type)

AsyncAssistants

class pinecone.async_client.assistants.AsyncAssistants(config)[source]

Bases: AsyncAssistantsLegacyNamespaceMixin

Async control-plane operations for Pinecone assistants.

A Pinecone assistant is a managed question-answering service grounded in documents you upload to it: create the assistant, upload files, then chat against them and get answers with citations back to the files that supported each claim.

Reached as pc.assistants on an AsyncPinecone client; not constructed directly. Unlike an index, which you query for records you then feed to your own model, an assistant does the retrieval and the generation for you.

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    async for assistant in pc.assistants.list():
        print(assistant.name, assistant.status)

See also

Error handling: the exceptions any of these methods can raise, and which ones are worth retrying.

Parameters:

config (PineconeConfig)

__init__(config)[source]
Parameters:

config (PineconeConfig)

Return type:

None

async close()[source]

Release the HTTP connections held by this namespace.

Call this when you’re done using pc.assistants to free pooled connections, including any opened for individual assistants.

Return type:

None

async create(*, name=None, instructions=None, metadata=None, region='us', environment=None, timeout=None, **kwargs)[source]

Create a new Pinecone assistant.

By default, blocks until the assistant reaches "Ready" status, so you can upload files to it as soon as the call returns.

Parameters:

  • name (str) – Name for the new assistant, e.g. "docs-assistant". Must be unique within the project. The server validates the name and rejects an invalid one.

  • instructions (str | None) – Guidance the assistant applies to every response, e.g. "Always cite the source document.".

  • metadata (dict[str, Any] | None) – Optional metadata to attach to the assistant, e.g. {"team": "docs"}.

  • region (str) – Region to deploy the assistant in, "us" or "eu". Defaults to "us". Cannot be changed afterwards: an assistant in the wrong region has to be recreated.

  • environment (str | None) – Reserved for internal Pinecone use. Leave it unset; the server rejects it for other projects.

  • timeout (float | None) – Seconds to wait for the assistant to become ready. Use None (default) to poll indefinitely, -1 to return immediately without polling, or a non-negative value to poll with a deadline.

  • **kwargs (Any) – Accepts the legacy alias assistant_name for name. Passing both, or any other keyword, raises PineconeValueError.

Returns:

AssistantModel describing the created assistant.

Raises:

  • PineconeTypeError – If name is not a str.

  • PineconeValueError – If region is not "us" or "eu".

  • PineconeError – If the assistant fails to initialize or is deleted while the call waits for it.

  • PineconeTimeoutError – If the assistant does not become ready before the deadline.

  • ConflictError – If an assistant of this name already exists in the project.

  • RateLimitError – If the project has reached its assistant limit. Retrying does not help; delete an assistant you no longer need first.

Return type:

AssistantModel

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    assistant = await pc.assistants.create(name="research-assistant")
    print(assistant.status)

Instructions, metadata and region are all optional. create returns once the assistant reaches "Ready", so the assistant below is usable as soon as the call returns:

assistant = await pc.assistants.create(
    name="support-docs-assistant",
    instructions="Always cite the source document.",
    metadata={"team": "support", "cost_center": "R-4120"},
    region="eu",
)
async describe(*, name=None, **kwargs)[source]

Get detailed information about a named assistant.

Parameters:

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

  • **kwargs (Any) – Accepts the legacy alias assistant_name for name. Passing both, or any other keyword, raises PineconeValueError.

Returns:

AssistantModel with name, status, region, host, instructions, metadata, created_at and updated_at.

Raises:
Return type:

AssistantModel

Examples

assistant = await pc.assistants.describe(name="research-assistant")
print(assistant.status)
list(*, limit=None, pagination_token=None)[source]

List assistants in the project with lazy pagination.

Parameters:

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

  • pagination_token (str | None) – Token to resume pagination from a previous call.

Returns:

AsyncPaginator over AssistantModel objects. Supports async for loops, .to_list(), .pages(), and limit.

Return type:

AsyncPaginator[AssistantModel]

Examples

async for assistant in pc.assistants.list():
    print(assistant.name, assistant.status)

The paginator fetches pages lazily as you iterate. Call to_list() instead when you want every assistant materialized up front:

all_assistants = await pc.assistants.list().to_list()

See also

  • list_page(): one page at a time, when you want to hold the continuation token yourself.

  • Pagination: how the paginator and the continuation tokens work.

async list_page(*, page_size=None, pagination_token=None, **kwargs)[source]

List one page of assistants with explicit pagination control.

Parameters:

  • page_size (int | None) – Maximum number of assistants per page. Omit it to let the server choose the page size.

  • pagination_token (str | None) – Token from a previous response to fetch the next page.

  • **kwargs (Any) – Accepts the legacy alias limit for page_size. Passing both, or any other keyword, raises PineconeValueError.

Returns:

ListAssistantsResponse with an assistants list and an optional next continuation token.

Return type:

ListAssistantsResponse

Examples

page = await pc.assistants.list_page(page_size=10)
for assistant in page.assistants:
    print(assistant.name)
if page.next:
    next_page = await pc.assistants.list_page(
        page_size=10,
        pagination_token=page.next,
    )

See also

Pagination: the continuation-token loop this method expects you to drive, and the paginator that drives it for you.

async update(*, name=None, instructions=None, metadata=None, **kwargs)[source]

Update an existing Pinecone assistant.

Pass at least one of instructions and metadata. A field left as None keeps its current value; to clear a field, pass its empty value (instructions="" or metadata={}).

Parameters:

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

  • instructions (str | None) – New instructions for the assistant. Pass an empty string to clear existing instructions.

  • metadata (dict[str, Any] | None) – New metadata dictionary. Fully replaces any existing metadata rather than merging. Pass an empty dict to clear existing metadata.

  • **kwargs (Any) – Accepts the legacy alias assistant_name for name. Passing both, or any other keyword, raises PineconeValueError.

Returns:

AssistantModel describing the updated assistant.

Raises:
Return type:

AssistantModel

Examples

Patch only the instructions. metadata is left out of the request body entirely, so whatever metadata the assistant already carries survives untouched:

assistant = await pc.assistants.update(
    name="research-assistant",
    instructions="Always cite the source document.",
)

Passing metadata replaces the whole dictionary instead of merging into it. An assistant carrying {"team": "research", "cost_center": "R-4120"} is left with only team after the call below. Its instructions stay unchanged, since they were not named:

assistant = await pc.assistants.update(
    name="research-assistant",
    metadata={"team": "docs-platform"},
)
async delete(*, name=None, timeout=None, **kwargs)[source]

Delete a Pinecone assistant by name.

Deleting an assistant also deletes its files. By default, blocks until the assistant is confirmed gone.

Parameters:

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

  • timeout (float | None) – Seconds to wait for the assistant to disappear. Use None (default) to poll indefinitely. Use -1 to return immediately without polling. Use a positive value to poll with a deadline. Raises PineconeTimeoutError if the assistant is not gone before the deadline.

  • **kwargs (Any) – Accepts the legacy alias assistant_name for name. Passing both, or any other keyword, raises PineconeValueError.

Returns:

None

Raises:
Return type:

None

Examples

await pc.assistants.delete(name="research-assistant")

The call above blocks until the assistant is confirmed gone. Pass timeout=-1 to return as soon as the request is accepted; the assistant may still be terminating when this returns:

await pc.assistants.delete(name="stale-prototype", timeout=-1)
async describe_file(*, assistant_name, file_id, include_url=False)[source]

Get the status and metadata of a file uploaded to an assistant.

Parameters:

  • assistant_name (str) – Name of the assistant that owns the file.

  • file_id (str) – Unique identifier of the file to retrieve.

  • include_url (bool) – If True, include a signed download URL in the response. Defaults to False.

Returns:

AssistantFileModel with id, name, status, metadata, size, multimodal, created_on, updated_on and content_hash, plus signed_url when include_url is True.

Raises:
Return type:

AssistantFileModel

Examples

file = await pc.assistants.describe_file(
    assistant_name="research-assistant",
    file_id="file-abc123",
)
print(file.status)

See also

list_files(): every file on the assistant. That listing drops a "ProcessingFailed" file once it is old enough; this method still returns it by id.

async list_files_page(*, assistant_name, page_size=None, pagination_token=None, filter=None, **kwargs)[source]

List one page of files for an assistant with explicit pagination control.

Parameters:

  • assistant_name (str) – Name of the assistant whose files to list.

  • page_size (int | None) – Maximum number of files in this page. Omit it to let the server choose the page size.

  • pagination_token (str | None) – Token from a previous response to fetch the next page.

  • filter (dict[str, Any] | None) – Metadata filter, e.g. {"department": "finance"}. Only files whose metadata matches are listed.

  • **kwargs (Any) – Accepts the legacy alias limit for page_size. Passing both, or any other keyword, raises PineconeValueError.

Returns:

ListFilesResponse with a files list and an optional next continuation token.

Raises:
Return type:

ListFilesResponse

Examples

page = await pc.assistants.list_files_page(
    assistant_name="research-assistant",
    page_size=10,
)
for f in page.files:
    print(f.name)
if page.next:
    next_page = await pc.assistants.list_files_page(
        assistant_name="research-assistant",
        page_size=10,
        pagination_token=page.next,
    )

See also

Pagination: the continuation-token loop this method expects you to drive, and the paginator that drives it for you.

list_files(*, assistant_name, filter=None, limit=None, pagination_token=None)[source]

List files for an assistant with lazy async pagination.

A "ProcessingFailed" file drops out of this listing once its created_on passes the listing’s age cutoff. It is not deleted: describe_file() still returns it by id.

Parameters:

  • assistant_name (str) – Name of the assistant whose files to list.

  • filter (dict[str, Any] | None) – Metadata filter, e.g. {"department": "finance"}. Only files whose metadata matches are listed.

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

  • pagination_token (str | None) – Token to resume pagination from a previous call.

Returns:

AsyncPaginator over AssistantFileModel objects. Supports async for loops, .to_list(), .pages(), and limit.

Raises:
Return type:

AsyncPaginator[AssistantFileModel]

Examples

async for f in pc.assistants.list_files(assistant_name="research-assistant"):
    print(f.name, f.status)

The paginator fetches pages lazily as you iterate. Call to_list() instead when you want every file materialized up front:

paginator = pc.assistants.list_files(assistant_name="research-assistant")
files = await paginator.to_list()

See also

  • describe_file(): one file by id, with no age filter.

  • list_files_page(): one page at a time, when you want to hold the continuation token yourself.

  • Pagination: how the paginator and the continuation tokens work.

async upload_file(*, assistant_name, file_path=None, file_stream=None, file_name=None, metadata=None, multimodal=None, file_id=None, timeout=None)[source]

Upload a file to a Pinecone assistant.

Uploads a file from a local path or an in-memory byte stream, then waits until processing finishes before returning. The server decides how to process the file from its extension, which must be .txt, .pdf, .json, .md or .docx.

Parameters:

  • assistant_name (str) – Name of the target assistant.

  • file_path (str | None) – Path to a local file to upload. Mutually exclusive with file_stream.

  • file_stream (IO[bytes] | None) – An open byte stream to upload. Mutually exclusive with file_path. Requires file_name.

  • file_name (str | None) – Filename for file_stream, including its extension, e.g. "q3-revenue-review.pdf". Required with file_stream. Ignored with file_path, whose basename is used instead.

  • metadata (dict[str, Any] | None) – Metadata to attach to the file, e.g. {"department": "finance"}. The filter argument of list_files(), chat() and context() matches against it.

  • multimodal (bool | None) – Whether to enable multimodal processing for PDFs.

  • file_id (str | None) – Optional identifier for the uploaded file. When given, any existing file with that id is replaced. Otherwise the server assigns one.

  • timeout (float | None) – Seconds to wait for processing to complete. None (default) polls indefinitely. Use -1 to return as soon as the server accepts the upload, while the file may still be "Processing". Raises PineconeTimeoutError if processing is not done before the deadline.

Returns:

AssistantFileModel describing the uploaded file, once processing completes.

Raises:

  • PineconeTypeError – If assistant_name is not a str, or file_id is given and is not a str.

  • PineconeValueError – If both or neither of file_path and file_stream are provided, if file_path does not exist, or if file_stream is used without a file_name carrying a file extension.

  • PineconeTimeoutError – If processing does not complete before timeout.

  • PineconeError – If processing fails.

Return type:

AssistantFileModel

Examples

Upload from a local path. The basename supplies the extension the server types the file by:

file = await pc.assistants.upload_file(
    assistant_name="research-assistant",
    file_path="/data/q3-revenue-review.pdf",
)
print(file.id, file.status)

Or upload from an open byte stream instead. Pass exactly one of file_path and file_stream; a stream needs file_name to carry the extension a path would have supplied:

with open("/data/q3-revenue-review.pdf", "rb") as handle:
    file = await pc.assistants.upload_file(
        assistant_name="research-assistant",
        file_stream=handle,
        file_name="q3-revenue-review.pdf",
        metadata={"department": "finance", "quarter": "2024-Q3"},
    )
print(file.id, file.status)
async delete_file(*, assistant_name, file_id, timeout=None)[source]

Delete a file from a Pinecone assistant.

Deletion can finish immediately or run as a pending operation, depending on the file’s state. When it is pending, this method polls until it finishes, unless you pass timeout=-1.

Parameters:

  • assistant_name (str) – Name of the assistant that owns the file.

  • file_id (str) – Unique identifier of the file to delete.

  • timeout (float | None) – Seconds to wait for the deletion to finish. Use None (default) to poll indefinitely. Use -1 to return as soon as the request is accepted; the file may still exist when this returns. Use a positive value to poll with a deadline. Raises PineconeTimeoutError if the deletion is not done before the deadline.

Returns:

None

Raises:

  • PineconeTypeError – If assistant_name or file_id is not a str.

  • NotFoundError – If file_id does not name a file on this assistant, including a file that has already been deleted.

  • PineconeError – If the deletion operation reports failure.

  • PineconeTimeoutError – If the deletion has not finished after timeout seconds.

Return type:

None

Examples

await pc.assistants.delete_file(
    assistant_name="research-assistant",
    file_id="file-abc123",
)
async describe_operation(*, assistant_name, operation_id)[source]

Get the current status of a long-running assistant operation.

upload_file() and delete_file() poll their own operation for you by default. Reach for this method when you called one of them with timeout=-1 and want to check on it later, for example to find the file a fire-and-forget upload created, via OperationModel.file_id.

Parameters:
Returns:

OperationModel with status, operation_type, file_id, percent_complete, created_at, completed_on, ingestion_units and error. status is "Processing", "Completed" or "Failed". Check status, not error, to tell whether the operation failed.

Raises:

  • PineconeTypeError – If assistant_name or operation_id is not a str.

  • NotFoundError – If the assistant or the operation does not exist. The server keeps finished operations for a limited time, so an old operation id also raises this.

Return type:

OperationModel

Examples

operation = await pc.assistants.describe_operation(
    assistant_name="research-assistant",
    operation_id="op-1234-abcd-5678",
)
print(operation.status, operation.percent_complete)

See also

list_operations(): every operation on the assistant, when you did not keep the operation id.

list_operations(*, assistant_name, operation_type=None, status=None, limit=None, pagination_token=None)[source]

List an assistant’s operations with lazy async pagination.

Includes operations still in progress and finished ones, successful or failed. The server keeps finished operations for a limited time.

Parameters:

  • assistant_name (str) – Name of the assistant whose operations to list.

  • operation_type (str | None) – Restrict the listing to one kind of operation. One of "upload_file", "upsert_file", "update_file_metadata" or "delete_file".

  • status (str | None) – Restrict the listing to one status. One of "Processing", "Completed" or "Failed" (case-sensitive).

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

  • pagination_token (str | None) – Token to resume pagination from a previous call.

Returns:

AsyncPaginator over OperationModel objects. Supports async for loops, .to_list(), .pages(), and limit.

Raises:
Return type:

AsyncPaginator[OperationModel]

Examples

async for op in pc.assistants.list_operations(assistant_name="research-assistant"):
    print(op.operation_id, op.status, op.percent_complete)

Filter server-side to narrow the listing, here to uploads that have not finished yet:

pending = await pc.assistants.list_operations(
    assistant_name="research-assistant",
    operation_type="upload_file",
    status="Processing",
).to_list()

See also

async list_operations_page(*, assistant_name, operation_type=None, status=None, page_size=None, pagination_token=None)[source]

List one page of an assistant’s operations with explicit pagination control.

Parameters:

  • assistant_name (str) – Name of the assistant whose operations to list.

  • operation_type (str | None) – Restrict the listing to one kind of operation. One of "upload_file", "upsert_file", "update_file_metadata" or "delete_file".

  • status (str | None) – Restrict the listing to one status. One of "Processing", "Completed" or "Failed" (case-sensitive).

  • page_size (int | None) – Maximum number of operations in this page. Omit it to let the server choose the page size.

  • pagination_token (str | None) – Token from a previous response to fetch the next page.

Returns:

ListOperationsResponse with an operations list and an optional next continuation token.

Raises:
Return type:

ListOperationsResponse

Examples

page = await pc.assistants.list_operations_page(
    assistant_name="research-assistant",
    status="Failed",
    page_size=10,
)
for op in page.operations:
    print(op.operation_id, op.error)
if page.next:
    next_page = await pc.assistants.list_operations_page(
        assistant_name="research-assistant",
        status="Failed",
        page_size=10,
        pagination_token=page.next,
    )

See also

Pagination: the continuation-token loop this method expects you to drive, and the paginator that drives it for you.

async context(*, assistant_name, query=None, messages=None, filter=None, top_k=None, snippet_size=None, multimodal=None, include_binary_content=None)[source]

Retrieve relevant context snippets from a Pinecone assistant.

Returns the snippets from the assistant’s files that match a text query or a conversation, without generating an answer, so you can prompt your own model with them. Provide exactly one of query or messages.

Parameters:

  • assistant_name (str) – Name of the assistant to retrieve context from.

  • query (str | None) – Text query to use for context retrieval. Mutually exclusive with messages. An empty string is treated as not provided.

  • messages (Sequence[Message | Mapping[str, str]] | None) – Conversation messages to use for context retrieval. Mutually exclusive with query. An empty list is treated as not provided. Dicts are converted to Message objects. Each role is "user" or "assistant".

  • filter (dict[str, Any] | None) – Filter on file metadata, such as {"department": "finance"}, restricting which files contribute snippets.

  • top_k (int | None) – Maximum number of snippets to return. Omit it to let the server choose.

  • snippet_size (int | None) – Maximum size of each snippet, in tokens. Omit it to let the server choose.

  • multimodal (bool | None) – Whether to include snippets drawn from images in files uploaded with multimodal=True.

  • include_binary_content (bool | None) – Whether image snippets include base64 image data. Only meaningful when multimodal is True.

Returns:

ContextResponse with snippets (each carrying content, a relevance score, and a reference naming the source file and, for paginated documents, the pages) and usage.

Raises:

  • PineconeTypeError – If assistant_name is not a str.

  • PineconeValueError – If both or neither of query and messages are provided, or if top_k or snippet_size is negative.

  • ApiError – If the assistant has no file in "Available" status yet, for example while uploads are still processing.

Return type:

ContextResponse

Examples

response = await pc.assistants.context(
    assistant_name="research-assistant",
    query="What is Pinecone?",
)
for snippet in response.snippets:
    print(snippet.content)

See also

  • chat(): a generated answer with structured citations, when you want Pinecone to do the generation as well.

  • chat_completions(): a generated answer in OpenAI’s response shape.

async chat(*, assistant_name, messages, model='gpt-4o', stream=False, temperature=None, filter=None, json_response=False, include_highlights=False, context_options=None, timeout=None)[source]

Chat with an assistant and receive citations in Pinecone-native format.

Citations come back as a structured list keyed to character positions in the answer, which is what separates this from chat_completions(). The assistant answers only from the files you uploaded to it, so an assistant with nothing ingested yet errors rather than replying from general knowledge.

Parameters:

  • assistant_name (str) – Name of the assistant to chat with.

  • messages (list[Message | dict[str, str]]) – Conversation messages. Dicts are converted to Message objects; role defaults to "user" when not present. Each role is "user" or "assistant".

  • model (str) – Name of the large language model that generates the answer. Defaults to "gpt-4o". The models the API documents for this endpoint are "gpt-4o", "gpt-4.1", "gpt-5", "o4-mini", "claude-sonnet-4-5", and "gemini-2.5-pro". A name outside that list may be served by a successor model rather than rejected, so the response’s model field, not this argument, says which model answered.

  • stream (bool) – If True, return an AsyncChatStream. Defaults to False.

  • temperature (float | None) – Controls randomness. Lower values produce more deterministic responses.

  • filter (dict[str, Any] | None) – Filter on file metadata, such as {"department": "finance"}, restricting which files the answer draws on.

  • json_response (bool) – If True, instruct the assistant to return a JSON response. Cannot be combined with stream=True.

  • include_highlights (bool) – If True, include highlight snippets from referenced documents in citations.

  • context_options (ContextOptions | dict[str, Any] | None) – Retrieval settings, such as top_k and snippet_size, as a ContextOptions or an equivalent dict.

  • timeout (float | None) – Per-call HTTP timeout in seconds, overriding the client-level default. On a streaming request this bounds the gap between chunks rather than the whole response (see below).

Returns:

ChatResponse for non-streaming requests, carrying message (the answer), citations (each with the position in the answer it supports and the references behind it), model (the model that answered), finish_reason and usage. For streaming requests, an AsyncChatStream.

Raises:

  • PineconeTypeError – If assistant_name is not a str.

  • PineconeValueError – If both stream=True and json_response=True are specified.

  • ApiError – If the assistant has no file in "Available" status yet, for example while uploads are still processing.

Return type:

ChatResponse | AsyncChatStream

Examples

import asyncio
from pinecone import AsyncPinecone

pc = AsyncPinecone(api_key="your-api-key")

async def main() -> None:
    response = await pc.assistants.chat(
        assistant_name="research-assistant",
        messages=[{"content": "What is Pinecone?"}],
    )
    print(response.message.content)
    for citation in response.citations:
        for reference in citation.references:
            print(citation.position, reference.file.name)
asyncio.run(main())

Set stream=True for an AsyncChatStream instead of a single response. Its text() method yields content fragments as they arrive, skipping the start, citation and end chunks:

async def stream_main() -> None:
    stream = await pc.assistants.chat(
        assistant_name="research-assistant",
        messages=[{"content": "What is Pinecone?"}],
        stream=True,
    )
    async for text in stream.text():
        print(text, end="", flush=True)
asyncio.run(stream_main())

See also

  • chat_completions(): the same conversation in OpenAI’s response shape, with citations woven into the message text instead of returned as a structured list.

  • context(): the retrieved snippets on their own, with no generated answer, when you want to prompt your own model.

Note

On a streaming request the timeout applies to the gap between chunks rather than the whole response, and the default is raised so a model that thinks for a while isn’t mistaken for a dead connection. Pass timeout to change it. A stream that exceeds its timeout raises PineconeTimeoutError partway through iteration, after earlier chunks have already been yielded.

async chat_completions(*, assistant_name, messages, model='gpt-4o', stream=False, temperature=None, filter=None, timeout=None)[source]

Chat with an assistant using an OpenAI-compatible interface.

Use it when your code already consumes OpenAI’s chat completion shape. Citations arrive inline in the message text rather than as a structured list, and the include_highlights, context_options and json_response options of chat() are not available.

Parameters:

  • assistant_name (str) – Name of the assistant to chat with.

  • messages (list[Message | dict[str, str]]) – Conversation messages. Dicts are converted to Message objects; role defaults to "user" when not present. Each role is "user" or "assistant".

  • model (str) – Name of the large language model that generates the answer. Defaults to "gpt-4o". The models the API documents for this endpoint are "gpt-4o", "gpt-4.1", "o4-mini", "claude-sonnet-4-5", and "gemini-2.5-pro". A name outside that list may be served by a successor model rather than rejected, so the response’s model field, not this argument, says which model answered.

  • stream (bool) – If True, return an AsyncChatCompletionStream. Defaults to False.

  • temperature (float | None) – Controls randomness. Lower values produce more deterministic responses.

  • filter (dict[str, Any] | None) – Filter on file metadata, such as {"department": "finance"}, restricting which files the answer draws on.

  • timeout (float | None) – Per-call HTTP timeout in seconds, overriding the client-level default. On a streaming request this bounds the gap between chunks rather than the whole response (see below).

Returns:

ChatCompletionResponse for non-streaming requests, carrying choices (read choices[0].message.content for the answer, with citations woven into that text), model (the model that answered), and usage. For streaming requests, an AsyncChatCompletionStream.

Raises:

  • PineconeTypeError – If assistant_name is not a str.

  • ApiError – If the assistant has no file in "Available" status yet, for example while uploads are still processing.

Return type:

ChatCompletionResponse | AsyncChatCompletionStream

Examples

import asyncio
from pinecone import AsyncPinecone

pc = AsyncPinecone(api_key="your-api-key")

async def main() -> None:
    response = await pc.assistants.chat_completions(
        assistant_name="research-assistant",
        messages=[{"content": "Explain quantum entanglement briefly."}],
    )
    print(response.choices[0].message.content)
asyncio.run(main())

Set stream=True for an AsyncChatCompletionStream. Its text() method yields content fragments as they arrive:

async def stream_main() -> None:
    stream = await pc.assistants.chat_completions(
        assistant_name="research-assistant",
        messages=[{"content": "Explain quantum entanglement briefly."}],
        stream=True,
    )
    async for text in stream.text():
        print(text, end="", flush=True)
asyncio.run(stream_main())

See also

  • chat(): the Pinecone-native shape, with a structured citations list.

  • context(): the retrieved snippets on their own, with no generated answer.

Note

On a streaming request the timeout applies to the gap between chunks rather than the whole response, and the default is raised so a model that pauses for longer while reasoning isn’t mistaken for a dead connection. Pass timeout to widen it further. A stream that exceeds its timeout raises PineconeTimeoutError partway through iteration, after earlier chunks have already been yielded.

async evaluate_alignment(*, question, answer, ground_truth_answer)[source]

Evaluate answer alignment against a ground truth answer.

Scores a generated answer, such as one from chat(), against an answer you know is right. Alignment is the harmonic mean of correctness (precision) and completeness (recall).

Parameters:

  • question (str) – The question for which the answer was generated.

  • answer (str) – The generated answer to evaluate.

  • ground_truth_answer (str) – The ground truth answer to compare against.

Returns:

AlignmentResult with scores (correctness, completeness and alignment), facts (the per-fact entailment verdicts behind the scores) and token usage.

Return type:

AlignmentResult

Examples

The answer below contradicts the ground truth on purpose, so the scores come back low and result.facts records where the contradiction is:

result = await pc.assistants.evaluate_alignment(
    question="What is the capital of Spain?",
    answer="Barcelona.",
    ground_truth_answer="Madrid.",
)
print(result.scores.alignment)
for fact in result.facts:
    print(fact.entailment, fact.fact)