AsyncPinecone¶

AsyncPinecone is the asynchronous control-plane client — use it inside an async with block to manage indexes, collections, backups, and related resources. Sub-clients for each resource type are accessed as properties (e.g. pc.indexes, pc.collections) and are lazily initialised on first access.

from pinecone import AsyncPinecone

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

Note

Unlike Pinecone, AsyncPinecone.index() cannot auto-resolve an index host by name. Call await pc.indexes.describe(name) first to populate the cache, then create the data-plane client:

desc = await pc.indexes.describe("my-index")
idx = pc.index("my-index")          # uses cached host
# — or —
idx = pc.index(host=desc.host)       # explicit 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)[source]¶

Bases: object

Asynchronous Pinecone client for control-plane operations.

The async entry point for the SDK. Use the indexes, collections, and backups namespace properties to create and manage those resources, and await index() to get a client for reading and writing vectors on a specific index.

Parameters:

api_key (str | None) – Pinecone API key. Falls back to PINECONE_API_KEY env var.
host (str | None) – Control-plane API host. Falls back to PINECONE_CONTROLLER_HOST env var, then defaults to https://api.pinecone.io.
additional_headers (Mapping[str, str] | None) – Extra headers included in every request.
source_tag (str | None) – Tag appended to the User-Agent string for request attribution.
proxy_url (str | None) – HTTP proxy URL for outgoing requests.
proxy_headers (Mapping[str, str] | None) – Not yet supported. Raises NotImplementedError if provided.
ssl_ca_certs (str | None) – Path to a CA certificate bundle for SSL verification.
ssl_verify (bool) – Whether to verify SSL certificates. Defaults to True.
timeout (float) – Request timeout in seconds. Defaults to 30.0.
connection_pool_maxsize (int) – Maximum number of connections to keep in the pool. 0 (default) uses httpx defaults.
retry_config (RetryConfig | None) – Custom retry configuration. When None (default), uses built-in defaults (5 attempts, exponential backoff, retries on 500/502/503/504 for GET/HEAD).

Raises:

PineconeValueError – If no API key can be resolved from arguments or environment variables.
FileNotFoundError – If ssl_ca_certs names a path that does not exist, so a mistyped path cannot leave you silently verifying against the default trust store instead. Unlike the sync client, this is raised on the first request rather than at construction time. A bundle that exists but cannot be parsed as a certificate raises ssl.SSLError at the same point.

Examples

from pinecone import AsyncPinecone

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

Note

Differences from sync Pinecone

index() is a coroutine. Unlike the sync Pinecone client, AsyncPinecone.index() must be awaited: idx = await pc.index(name="my-index"). On cache miss it performs a non-blocking describe call to resolve the host — no manual two-step dance needed.
upsert_from_dataframe() is not supported. AsyncIndex raises NotImplementedError for this method. Use batched upsert() calls instead.
No grpc parameter on index(). Async gRPC transport is not yet available, so the grpc option accepted by the sync client is absent here.

async __aenter__()[source]¶

Enter the async context manager, returning this client.

Returns:: This AsyncPinecone instance.
Return type:: AsyncPinecone

Examples

>>> import asyncio
>>> async def example():
...     async with AsyncPinecone(api_key="your-api-key") as pc:
...         _ = await pc.indexes.list().to_list()
>>> asyncio.run(example())

async __aexit__(*args)[source]¶

Exit the async context manager, closing the client.

Calls close() to release open HTTP connections.

Examples

>>> import asyncio
>>> async def example():
...     async with AsyncPinecone(api_key="your-api-key") as pc:
...         _ = await pc.indexes.list().to_list()
>>> asyncio.run(example())

Parameters:: args (Any)
Return type:: None

__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)[source]¶

Parameters:

api_key (str | None)
host (str | None)
additional_headers (Mapping[str, str] | None)
source_tag (str | None)
proxy_url (str | None)
proxy_headers (Mapping[str, str] | None)
ssl_ca_certs (str | None)
ssl_verify (bool)
timeout (float)
connection_pool_maxsize (int)
retry_config (RetryConfig | None)

Return type:

None

property assistant: _AsyncAssistantNamespaceProxy¶

Access assistants through the singular-form alias for AsyncPinecone.assistants.

AsyncPinecone.assistants is the canonical namespace; this alias exists for ergonomic singular-form access and is not deprecated. It forwards attribute access to that namespace and also supports calling it directly with a name as a shortcut 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

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

property assistants: AsyncAssistants¶

Access the AsyncAssistants namespace for managing Pinecone Assistants.

A Pinecone Assistant is a hosted, retrieval-augmented chat service: upload files to it and it answers questions grounded in their content. Use this namespace to create, list, and configure assistants. Lazily imported and instantiated on first access.

Returns:: AsyncAssistants namespace instance. Call create() to create an assistant, or list() to see existing ones.

Examples

async with AsyncPinecone(api_key="your-api-key") as pc:
    assistants = await pc.assistants.list()

property backup_schedules: AsyncBackupSchedules¶

Access the AsyncBackupSchedules namespace for managing recurring backups.

A backup schedule attaches a recurring cadence (daily, weekly, or monthly) to an index, so Pinecone creates a backup automatically without you having to trigger one each time. Lazily imported and instantiated on first access.

Returns:: AsyncBackupSchedules namespace instance. Call create() to attach a schedule to an index, or list() to see existing ones.

Examples

async with AsyncPinecone(api_key="your-api-key") as pc:
    schedules = await pc.backup_schedules.list(index_name="my-index")

property backups: AsyncBackups¶

Access the AsyncBackups namespace for control-plane backup operations.

Lazily imported and instantiated on first access.

Returns:: AsyncBackups namespace instance.

Examples

async with AsyncPinecone(api_key="your-api-key") as pc:
    for backup in await pc.backups.list():
        print(backup.backup_id)

async close()[source]¶

Close all open HTTP connections.

Closes the main control-plane client and any namespace clients (inference, assistants) that were initialized during this session.

Prefer the async context manager form (async with AsyncPinecone(...) as pc:) which calls close() automatically on exit.

Examples

Close the client explicitly after use:

>>> import asyncio
>>> from pinecone import AsyncPinecone
>>> async def example():
...     client = AsyncPinecone(api_key="your-api-key")
...     await client.close()
>>> asyncio.run(example())

Use AsyncPinecone as a context manager (close is called automatically):

>>> async def example():
...     async with AsyncPinecone(api_key="your-api-key") as pc:
...         _ = await pc.indexes.list().to_list()
>>> asyncio.run(example())

Return type:: None

property collections: AsyncCollections¶

Access the AsyncCollections namespace for control-plane collection operations.

Lazily imported and instantiated on first access.

Returns:: AsyncCollections namespace instance.

Examples

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

property config: PineconeConfig¶

Return the resolved configuration for this client.

Returns:: PineconeConfig containing the resolved API key, host, timeout, and connection settings.

Examples

>>> cfg = pc.config
>>> cfg.timeout
30.0

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: AsyncPinecone.create_index() rejects source_backup_id= with a message pointing here.

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.

Parameters:

name (str) – Name for the new index.
backup_id (str) – Identifier of the backup to restore from. Obtain this from AsyncPinecone.backups.create() or AsyncPinecone.backups.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 for 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:

PineconeValueError – If name or backup_id is empty, or read_capacity is an empty dict.
PineconeTimeoutError – If the index is not ready within the timeout.
IndexInitFailedError – If the index enters InitializationFailed state.
IndexTerminatedError – If the index enters Terminating or Disabled state.
NotFoundError – If backup_id does not match an existing backup.
ConflictError – If an index named name already exists.
ApiError – If the API returns another error response, for example if the backup is not yet complete.

Return type:

CreateIndexFromBackupResponse | IndexModel

Examples

# Restore an index from a backup
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-daily-20240115",
    )

# Restore without waiting (returns restore_job_id)
async with AsyncPinecone(api_key="your-api-key") as pc:
    result = await pc.create_index_from_backup(
        name="product-search-restored",
        backup_id="bk-daily-20240115",
        timeout=-1,
    )
    print(result.restore_job_id)

# Restore directly onto dedicated read nodes
async with AsyncPinecone(api_key="your-api-key") as pc:
    index = await pc.create_index_from_backup(
        name="restored-drn-index",
        backup_id="bk-daily-20240115",
        read_capacity={
            "mode": "Dedicated",
            "dedicated": {
                "node_type": "t1",
                "scaling": "Manual",
                "manual": {"shards": 2, "replicas": 2},
            },
        },
    )

async index(name='', *, host='')[source]¶

Create an async data-plane client targeting a specific index.

Can target by host URL directly (skips the describe call) or by index name (triggers an async describe-index lookup to resolve the host on cache miss).

AsyncIndexes¶

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

Bases: object

Async control-plane operations for Pinecone indexes (2026-07 API).

Provides list, describe, exists, create, create_for_model, delete, and configure methods, plus the index-scoped backup methods create_backup, list_backups, and describe_backup, mirroring Indexes one-for-one.

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

AsyncCollections¶

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

Bases: object

Async control-plane operations for Pinecone collections.

Provides methods to create, list, describe, and delete collections.

Parameters:: http (AsyncHTTPClient) – Async HTTP client for making API requests.

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)

__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. Create one to preserve an index’s contents, then later pass its name as source_collection when creating a new index to restore the data. 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. 1-45 characters, lowercase alphanumeric and hyphens only, and can’t start or end with a hyphen (e.g. "movie-embeddings-snapshot").
source (str) – Name of the pod-based index to copy.

Returns:

A CollectionModel describing the created collection.

Raises:

PineconeValueError – If name or source is empty, or name doesn’t meet the naming rules above.
NotFoundError – If source does not name an index in this project.

Return type:

CollectionModel

Examples

col = await pc.collections.create(name="my-collection", source="my-index")
print(col.status)

async delete(name)[source]¶

Delete a collection permanently.

Parameters:

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

Raises:

PineconeValueError – If name is empty.
NotFoundError – If the collection does not exist.

Return type:

None

Examples

await pc.collections.delete("my-collection")

async describe(name)[source]¶

Get details about a collection.

Parameters:

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

Returns:

A CollectionModel with the collection’s name, status, size, dimension, vector_count, and environment.

Raises:

PineconeValueError – If name is empty.
NotFoundError – If the collection does not exist.

Return type:

CollectionModel

Examples

desc = await pc.collections.describe("my-collection")
print(desc.size)

async list()[source]¶

List every collection in the project.

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

Returns:: A CollectionList supporting 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)

AsyncBackups¶

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

Bases: object

Async control-plane operations for Pinecone backups.

Provides methods to create, list, describe, and delete backups.

Parameters:: http (AsyncHTTPClient) – Async HTTP client for making API requests.

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    for backup in await pc.backups.list():
        print(backup.backup_id)

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

A backup is a stored, point-in-time snapshot of an index’s data and schema. Restore one into a new index with AsyncPinecone.create_index_from_backup(). Only serverless and BYOC indexes can be backed up.

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. The call returns once the backup is initiated; check its status via describe() to see when it’s ready.

Raises:

PineconeValueError – If index_name is empty.
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 the API returns another error response, for example because index_name names a pod-based index.

Return type:

BackupModel

Examples

# Create a backup of an index
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)

# Create a backup with a name and description
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",
    )

async delete(*, backup_id)[source]¶

Delete a backup.

Parameters:

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

Raises:

PineconeValueError – If backup_id is empty.
NotFoundError – If the backup does not exist.
ApiError – If the API returns another error response.

Return type:

None

Examples

from pinecone import AsyncPinecone
async with AsyncPinecone(api_key="your-api-key") as pc:
    await pc.backups.delete(backup_id="bk-daily-20240115")

async describe(*, backup_id)[source]¶

Get detailed information about a backup.

Parameters:

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

Returns:

A BackupModel with full backup details.

Raises:

PineconeValueError – If backup_id is empty.
NotFoundError – If the backup does not exist.
ApiError – If the API returns another error response.

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-daily-20240115",
    )
    print(backup.status)

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 with full backup details.

Raises:

PineconeValueError – If backup_id is empty.
NotFoundError – If the backup does not exist.
ApiError – If the API returns another error response.

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-daily-20240115",
    )
    print(backup.status)

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

List backups.

When index_name is given, lists backups of that index only. Otherwise lists every backup in the project.

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

Note

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

Because paging walks a live result set rather than a fixed snapshot, backups created or deleted between requests can shift later pages. De-duplicate by backup_id rather than relying on page order, and stop once pagination is None.

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. When None, the parameter is omitted and the server applies its own default. Omitted too when pagination_token is given: the token already carries the page size it was minted with, and a different one sent alongside it would skip or repeat rows.
pagination_token (str | None) – Offset token naming the next page, taken from BackupList.pagination.next. Takes precedence over limit — see above.
include_deleted (bool | None) – When True, include backups of every index that has ever used index_name, deleted ones included. When None (the default) the parameter is omitted entirely and the server’s default (false) applies. Only valid together with index_name.

Returns:

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

Raises:

PineconeValueError – If include_deleted is given without index_name.
NotFoundError – If index_name does not resolve to an active index and include_deleted is not True.
ApiError – If the API returns another error response.

Return type:

BackupList

Examples

# List all backups in the project
from pinecone import AsyncPinecone
async with AsyncPinecone(api_key="your-api-key") as pc:
    for backup in await pc.backups.list():
        print(backup.backup_id, backup.name)

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

# Recover backups of an index that has since been deleted
async with AsyncPinecone(api_key="your-api-key") as pc:
    orphaned = await pc.backups.list(
        index_name="product-search",
        include_deleted=True,
    )
    print([b.backup_id for b in orphaned if b.source_index_deleted_at])

AsyncBackupSchedules¶

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

Bases: object

Async control-plane operations for automatic, time-based backup schedules.

Parameters:: http (AsyncHTTPClient) – Async HTTP client for making API requests.

Note

Backups are a plan entitlement. A project without it gets a ForbiddenError rather than a NotFoundError for a schedule that does not exist, and the SDK appends that clarification to the error while keeping the server’s own message as the prefix. On-demand backups are gated on the same entitlement, so they are not a fallback.

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="daily-compliance-backup",
        frequency="daily",
        retention_days=90,
    )
    async for run in pc.backup_schedules.iter_history(
        schedule_id=schedule.schedule_id
    ):
        print(run.backup_id, run.status)

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

A backup schedule runs automatically at a fixed cadence, producing a backup of the index on each run. There is no cron support here — choose one of the three fixed cadences below.

Important

Keep the schedule name short. Each run names its backup "{name}-{run timestamp}", and a long schedule name can push that derived name past the length limit backup names allow.

Parameters:

index_name (str) – Name of the index to attach the schedule to.
name (str) – Name for the schedule. Backups it produces are named "{name}-{run timestamp}" — see the length note above.
frequency (str) – Cadence for the schedule: "daily", "weekly", or "monthly".
retention_days (int) – Number of days to retain each backup this schedule produces. Must be at least 1.

Returns:

A BackupScheduleModel describing the new schedule. It is created enabled, so next_scheduled_run is already populated.

Raises:

PineconeValueError – If index_name or name is empty, if frequency is not a supported cadence, or if retention_days is less than 1.
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 — only one per index is allowed, so disable or delete the existing one first.
ApiError – If the API returns another error response, such as when scheduling is requested for a pod-based index, which does not support it.

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="daily-compliance-backup",
        frequency="daily",
        retention_days=90,
    )
    print(schedule.frequency)

async delete(*, schedule_id)[source]¶

Permanently delete a backup schedule.

Backups the schedule already produced are not deleted; they age out on their own retention window. Deleting the schedule only stops future runs.

Important

This is not safe to retry blindly. A successful delete raises nothing, and a second attempt on the same schedule_id raises NotFoundError – so a retry after a dropped response is indistinguishable from deleting something that was never there. Treat a NotFoundError following a delete attempt as success.

Parameters:

schedule_id (str) – The identifier of the schedule to delete.

Returns:

None. The 204 carries no body, and none is parsed.

Raises:

PineconeValueError – If schedule_id is empty.
ForbiddenError – If the project’s plan does not include scheduled backups.
NotFoundError – If the schedule does not exist – see the retry caveat above.
ApiError – If the API returns another error response.

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

async describe(*, schedule_id)[source]¶

Get detailed information about a backup schedule.

Parameters:

schedule_id (str) – The identifier of the schedule to describe. This is the schedule_id from create() or list(), not the index name.

Returns:

A BackupScheduleModel with the schedule’s current configuration.

Raises:

PineconeValueError – If schedule_id is empty.
ForbiddenError – If the project’s plan does not include scheduled backups.
NotFoundError – If the schedule does not exist.
ApiError – If the API returns another error response.

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)

async get(*, schedule_id)[source]¶

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

Parameters:

schedule_id (str) – The identifier of the schedule.

Returns:

A BackupScheduleModel with the schedule’s current configuration.

Raises:

PineconeValueError – If schedule_id is empty.
NotFoundError – If the schedule does not exist.
ApiError – If the API returns another error response.

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 history(*, schedule_id, limit=None, pagination_token=None)[source]¶

List one page of the backups produced by a schedule.

Rows describe backup snapshots, not the schedule, and a row appears as soon as a run is planned – so the listing mixes runs that have already completed with ones that have not started.

Note

This returns a single page. A daily schedule with a 90-day retention window has many more rows than one page holds, so prefer iter_history() unless you are managing pagination yourself.

Parameters:

schedule_id (str) – The identifier of the schedule whose history to list.
limit (int | None) – Maximum results per page. Defaults to the server’s page size when None. Ignored when a pagination token is given, since the token already carries the page size it was created with.
pagination_token (str | None) – Token naming the next page, taken from the previous page’s pagination.next. Takes precedence over limit — see above.

Returns:

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

Raises:

PineconeValueError – If schedule_id is empty or limit is zero or negative.
ForbiddenError – If the project’s plan does not include scheduled backups.
NotFoundError – If the schedule does not exist.
ApiError – If the API returns another error response.

Return type:

BackupScheduleHistoryList

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    runs = await pc.backup_schedules.history(
        schedule_id="e88f7273-42aa-47e9-af73-593827136867"
    )
    print([r.backup_id for r in runs.scheduled()])

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(). Iteration stops when a response carries no pagination envelope or a null one.

Parameters:

schedule_id (str) – The identifier of the schedule whose history to iterate.
limit (int | None) – Maximum number of rows 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.
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.
ApiError – If the API returns another error response.

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"
    ):
        print(run.backup_id, run.status, run.scheduled_execution_at)

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(). Iteration stops when a response carries no pagination envelope or a null one.

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.
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.
ApiError – If the API returns another error response.

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="my-index"
    ):
        print(s.schedule_id, s.frequency, s.enabled)

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

List one page of an index’s backup schedules.

Schedules are always listed per index; there is no project-wide schedule listing. Disabled schedules are included, so a listing can hold several rows even though at most one may be enabled.

Note

This returns a single page. Use iter_schedules() to walk every page instead of managing the token yourself.

Parameters:

index_name (str) – Name of the index whose schedules to list.
limit (int | None) – Maximum results per page. Defaults to the server’s page size when None. Ignored when a pagination token is given, since the token already carries the page size it was created with.
pagination_token (str | None) – Token naming the next page, taken from the previous page’s pagination.next. Takes precedence over limit — see above.

Returns:

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

Raises:

PineconeValueError – If index_name is empty or limit is zero or negative.
ForbiddenError – If the project’s plan does not include scheduled backups.
NotFoundError – If the index does not exist.
ApiError – If the API returns another error response.

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="my-index")
    print(schedules.names())
    print([s.schedule_id for s in schedules.enabled_schedules()])

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 are sent, so omitted fields are left unchanged rather than reset. The schedule’s name and its index cannot be changed – the API exposes no field for either.

Warning

Passing enabled=True on a disabled schedule immediately enqueues a backup run and recomputes next_scheduled_run from the moment of the update rather than resuming the old slot, so a disable/re-enable cycle shifts the cadence rather than pausing it. Only one schedule per index can be enabled, so re-enabling raises ConflictError if another one already is. On an already-enabled schedule, enabled=True enqueues nothing.

Parameters:

schedule_id (str) – The identifier of the schedule to update.
frequency (str | None) – New cadence, one of "daily", "weekly", "monthly". None leaves it unchanged.
retention_days (int | None) – New retention window in days, at least 1. None leaves it unchanged. Changing it also re-times the pending deletion of backups this schedule has already produced.
enabled (bool | None) – False to disable (clearing next_scheduled_run), True to re-enable – see the warning above. 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.
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.
ApiError – If the API returns another error response.

Return type:

BackupScheduleModel

Note

Calling this with none of frequency, retention_days, or enabled set is a no-op: it returns the schedule unchanged.

Examples

Pause a schedule without losing 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,
    )
    assert paused.next_scheduled_run is None

Move to a weekly cadence with a shorter retention window:

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

AsyncRestoreJobs¶

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

Bases: object

Async control-plane operations for Pinecone restore jobs.

Provides methods to list and describe restore jobs.

Parameters:: http (AsyncHTTPClient) – Async HTTP client for making API requests.

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    for job in await pc.restore_jobs.list():
        print(job.restore_job_id)

__init__(http)[source]¶

Parameters:: http (AsyncHTTPClient)
Return type:: None

async describe(*, job_id)[source]¶

Get detailed information about a restore job.

Parameters:

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

Returns:

A RestoreJobModel with full restore job details. status is one of "Pending", "Completed", "Failed", or "Cancelled". There is no in-progress state: a restore that is actively running reports "Pending", so do not poll for a "Running"-style value. percent_complete is 100 once status is "Completed" and None at every other point — it reports completion, not progress, and cannot be used to draw a progress bar. completed_at is populated on the same condition.

Raises:

PineconeValueError – If job_id is empty.
NotFoundError – If the API answers 404 — which is not the same as “the restore job does not exist”; see the warning below.
ApiError – If the API returns another error response.

Return type:

RestoreJobModel

Warning

A ``404`` from this endpoint cannot be trusted to mean “no such restore job”. Every failure to read the restore-job store, an outage included, is answered with a 404, so NotFoundError here means “could not produce this job”, not “this job does not exist”. Any retry policy or control flow keyed on a 404 from describe is therefore unsafe: giving up, deleting local state, or reporting the job as gone can each be the wrong call on what was really a transient store failure. Treat it as possibly transient unless you have independent evidence the id is bad.

A restore job whose target index has been deleted also answers 404, and the message it carries is not the one a genuinely missing job produces — so do not match on the message text either. Such a job is dropped from list() entirely rather than reported. Tracked in pinecone-io/python-sdk-internal#250.

Examples

from pinecone import AsyncPinecone

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

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

List one page of the project’s restore jobs.

Pagination is offset-based, not cursor-based: the token names a position in the result set rather than a stable cursor. This returns a single page and does not auto-fetch: RestoreJobList carries a pagination token but never follows it, so iterating the return value sees at most one page. Drive the token yourself to walk the rest — see Examples.

Parameters:

limit (int | None) – Maximum number of results per page. When None, the parameter is omitted and the server applies its own default. Omitted too when pagination_token is given: the token already carries the page size it was minted with, and a different one sent alongside it would skip or repeat rows.
pagination_token (str | None) – Offset token naming the next page, taken from RestoreJobList.pagination.next. A malformed or truncated token is rejected with 400 (ApiError) rather than restarting the listing.

Returns:

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

Raises:

ApiError – If the API returns an error response.

Return type:

RestoreJobList

Warning

This listing can silently drop restore jobs, stop paginating early, and repeat rows across pages. The token stream can end while restore jobs remain, and successive pages can overlap, so pages are neither exhaustive nor disjoint. A restore job whose target index has been deleted is dropped from the listing entirely.

What that means for you: treat the result as a best-effort sample rather than an exhaustive inventory, never conclude a restore job does not exist from its absence here, and de-duplicate by restore_job_id while walking pages. The SDK offers no workaround on purpose — the token stream itself ends early, so no client-side code can recover pages the server never points at. Tracked in pinecone-io/python-sdk-internal#250.

Examples

Walk every page the server will hand out:

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    page = await pc.restore_jobs.list(limit=100)
    jobs = list(page)
    while page.pagination and page.pagination.next:
        page = await pc.restore_jobs.list(
            pagination_token=page.pagination.next
        )
        jobs.extend(page)

for job in jobs:
    print(job.restore_job_id, job.status, job.percent_complete)

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

AsyncInference¶

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

Bases: object

Asynchronous operations for Pinecone inference (embed & rerank).

Provides async methods to generate embeddings and rerank documents using Pinecone’s hosted models.

Parameters:: config (PineconeConfig) – SDK configuration used to construct an async HTTP client targeting the inference API version.

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=["Hello, world!"],
    )

class EmbedModel(value)¶

Bases: str, Enum

Known embedding models for integrated indexes.

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

Llama_Text_Embed_V2 = 'llama-text-embed-v2'¶

Multilingual_E5_Large = 'multilingual-e5-large'¶

Pinecone_Sparse_English_V0 = 'pinecone-sparse-english-v0'¶

Pinecone_Sparse_Multilingual_V0 = 'pinecone-sparse-multilingual-v0'¶

class 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

async embed(model, inputs, parameters=None)[source]¶

Generate embeddings for the provided inputs.

Parameters:

model (EmbedModel | str) – Embedding model name.
inputs (str | Sequence[str] | Sequence[Mapping[str, Any]]) – Text inputs. A single string is automatically wrapped. Any Sequence type (list, tuple, etc.) of strings or Mappings is accepted.
parameters (Mapping[str, Any] | None) –
Model-specific parameters (e.g., {"input_type": "passage", "truncate": "END"}). To discover valid parameters for a model, call get_model():
```
info = await pc.inference.get_model(model="multilingual-e5-large")
info.supported_parameters
```

Returns:

An EmbeddingsList with .data, .model, and .usage.

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.
ApiError – If the API returns another error response.
PineconeConnectionError – If a network-level connection fails (DNS, refused, transport error).
PineconeTimeoutError – If the request exceeds the configured timeout.

Return type:

EmbeddingsList

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=["Hello, world!"],
        parameters={"input_type": "passage"},
    )

async get_model(*, model=None, **kwargs)[source]¶

Get detailed information about a specific model.

Parameters:

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

Returns:

A ModelInfo with full model details.

Raises:

PineconeValueError – If model is empty.
NotFoundError – If no model with that name exists.
ApiError – If the API returns another error response.
PineconeConnectionError – If a network-level connection fails (DNS, refused, transport error).
PineconeTimeoutError – If the request exceeds the configured timeout.

Return type:

ModelInfo

Examples

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)

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

List available inference models.

Parameters:

type (str | None) – Filter by model type ("embed" or "rerank").
vector_type (str | None) – Filter by vector type ("dense" or "sparse"). Only relevant when type="embed".

Returns:

A ModelInfoList supporting iteration, len(), and .names().

Raises:

PineconeValueError – If type or vector_type is not a valid value.
ApiError – If the API returns an error response.
PineconeConnectionError – If a network-level connection fails (DNS, refused, transport error).
PineconeTimeoutError – If the request exceeds the configured timeout.

Return type:

ModelInfoList

Examples

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

property model: AsyncModelResource¶

Lazily-initialized resource for listing and getting model info.

Returns:: A AsyncModelResource that exposes .list() and .get() methods.

Examples

from pinecone import AsyncPinecone
async with AsyncPinecone(api_key="your-api-key") as pc:
    models = await pc.inference.model.list()
    info = await pc.inference.model.get("multilingual-e5-large")

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.
query (str) – Query text to rank against.
documents (Sequence[str] | Sequence[Mapping[str, Any]]) – Documents to rank. Strings are auto-wrapped as {"text": ...}. Any Sequence type (list, tuple, etc.) is accepted.
rank_fields (Sequence[str]) – Document fields to rank on. Defaults to ["text"].
return_documents (bool) – Include document text in response. Defaults to True.
top_n (int | None) – Number of top documents to return. None returns all.
parameters (Mapping[str, Any] | None) –
Model-specific parameters. To discover valid parameters for a model, call get_model():
```
info = await pc.inference.get_model(model="bge-reranker-v2-m3")
info.supported_parameters
```

Returns:

A RerankResult with .data and .usage.

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.
ApiError – If the API returns another error response.
PineconeConnectionError – If a network-level connection fails (DNS, refused, transport error).
PineconeTimeoutError – If the request exceeds the configured timeout.

Return type:

RerankResult

Examples

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

Note

The model that serves a request is not always the model named in it — Pinecone may substitute a different one. result.model reports the model that actually served the request, so read it there rather than assuming it echoes model.

AsyncAssistants¶

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

Bases: AsyncAssistantsLegacyNamespaceMixin

Async control-plane operations for Pinecone assistants.

Parameters:: config (PineconeConfig) – SDK configuration used to construct an HTTP client targeting the assistant API version.

Examples

from pinecone import AsyncPinecone

async with AsyncPinecone(api_key="your-api-key") as pc:
    assistants = pc.assistants

__init__(config)[source]¶

Parameters:: config (PineconeConfig)
Return type:: None

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.

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. Roles are case-sensitive "user" or "assistant" and content must be non-blank — see Message. Neither is checked client-side.
model (str) – Name of the large language model to use. Defaults to "gpt-4o". The models the 2026-07 API documents for this endpoint are "gpt-4o", "gpt-4.1", "gpt-5", "o4-mini", "claude-sonnet-4-5", and "gemini-2.5-pro". The removed aliases "claude-3-5-sonnet" and "claude-3-7-sonnet" are still accepted but deprecated — the backend silently remaps them to "claude-sonnet-4-5", so migrate to that name. Not validated client-side; the API rejects an unrecognized name.
stream (bool) – If True, return an AsyncChatStream. Defaults to False.
temperature (float | None) – Controls randomness. Lower values produce more deterministic responses. Omitted from request when None.
filter (dict[str, Any] | None) – Metadata filter restricting which documents are used as context. Omitted from request when None.
json_response (bool) – If True, instruct the assistant to return a JSON response. Cannot be used with streaming.
include_highlights (bool) – If True, include highlight snippets from referenced documents in citations.
context_options (ContextOptions | dict[str, Any] | None) – Options controlling context retrieval. Omitted from request when None.
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, or an AsyncChatStream for streaming requests.

Raises:

PineconeValueError – If both stream=True and json_response=True are specified.
ApiError – If the API returns an error response, for example if the assistant has no processed files yet.

Return type:

ChatResponse | AsyncChatStream

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.

Examples

# Non-streaming chat
import asyncio
from pinecone import AsyncPinecone

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

async def main() -> None:
    response = await pc.assistants.chat(
        assistant_name="my-assistant",
        messages=[{"content": "What is Pinecone?"}],
    )
asyncio.run(main())

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

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.

Returns responses in OpenAI chat completion format. Useful when you need inline citations or OpenAI-compatible responses. Has limited functionality compared to the standard chat() interface — does not support include_highlights, context_options, or json_response parameters.

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. Roles are case-sensitive "user" or "assistant" and content must be non-blank — see Message. Neither is checked client-side.
model (str) – Name of the large language model to use. Defaults to "gpt-4o". The models the 2026-07 API documents for this endpoint are "gpt-4o", "gpt-4.1", "o4-mini", "claude-sonnet-4-5", and "gemini-2.5-pro" — the same list chat() accepts, minus "gpt-5", which the spec documents only on the Pinecone-native chat endpoint. The removed aliases "claude-3-5-sonnet" and "claude-3-7-sonnet" are still accepted but deprecated — the backend silently remaps them to "claude-sonnet-4-5", so migrate to that name. Not validated client-side; the API rejects an unrecognized name.
stream (bool) – If True, return an AsyncChatCompletionStream. Defaults to False.
temperature (float | None) – Controls randomness. Lower values produce more deterministic responses. Omitted from request when None.
filter (dict[str, Any] | None) – Metadata filter restricting which documents are used as context. Omitted from request when None.
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, or an AsyncChatCompletionStream for streaming requests.

Raises:

ApiError – If the API returns an error response, for example if the assistant has no processed files yet.

Return type:

ChatCompletionResponse | AsyncChatCompletionStream

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.

Examples

# Non-streaming chat completion
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())

# Streaming chat completion
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 chunk in stream:
        print(chunk)
asyncio.run(stream_main())

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

Retrieves context snippets matching a text query or a conversation history, without generating a chat response. 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. Roles are case-sensitive "user" or "assistant" and content must be non-blank — see Message.
filter (dict[str, Any] | None) – Metadata filter restricting which documents contribute context. Omitted from the request when None.
top_k (int | None) – Maximum number of context snippets to return. Omitted from the request when None, in which case the API applies its own default.
snippet_size (int | None) – Maximum snippet size in tokens. Omitted from the request when None, in which case the API applies its own default.
multimodal (bool | None) – Whether to include image-related context snippets. Omitted from the request when None.
include_binary_content (bool | None) – Whether image snippets include base64 image data. Only meaningful when multimodal is True. Omitted from the request when None.

Returns:

ContextResponse containing the matching context snippets.

Raises:

PineconeValueError – If both or neither of query and messages are provided, or if top_k or snippet_size is negative.
ApiError – If the API returns an error response.

Return type:

ContextResponse

Examples

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

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

Create a new Pinecone assistant.

A Pinecone assistant is a managed conversational AI service that answers questions grounded in documents you upload to it. This method creates the assistant and, by default, waits until it reaches "Ready" status before returning.

Parameters:

name (str) – Name for the new assistant, e.g. "docs-assistant". Must be unique within the project.
instructions (str | None) – Guidance the assistant applies to every response, e.g. "Always cite the source document.". Maximum 16 KB.
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". EU availability depends on your plan.
environment (str | None) – Advanced override for select internal Pinecone deployments. Most users should leave this unset.
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)

Returns:

AssistantModel describing the created assistant.

Raises:

PineconeValueError – If region is not "us" or "eu".
PineconeTimeoutError – If the assistant does not become ready before the deadline.
ApiError – If the API returns an error response, such as reaching your project’s assistant limit.

Return type:

AssistantModel

Examples

from pinecone import AsyncPinecone
async with AsyncPinecone(api_key="your-api-key") as pc:
    assistant = await pc.assistants.create(name="my-assistant")

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

Delete a Pinecone assistant by name.

By default, waits until the assistant is confirmed gone before returning.

If the assistant enters a terminal failure state while being deleted, waiting stops with PineconeError instead of polling indefinitely for a state that will never arrive.

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) – Accepted for backwards compatibility only. Unknown kwargs raise PineconeValueError.

Returns:

None.

Raises:

PineconeError – If the assistant enters a terminal failure state ("Failed", "InitializationFailed") while being deleted.
PineconeTimeoutError – If the assistant still exists after timeout seconds.
ApiError – If the API returns an error response.

Return type:

None

Examples

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

# Return immediately without waiting for deletion
await pc.assistants.delete(name="my-assistant", timeout=-1)

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:

NotFoundError – If file_id does not name a file on this assistant. Deleting an id that is already gone raises rather than returning silently.
PineconeError – If the deletion operation reports failure.
PineconeTimeoutError – If the deletion has not finished after timeout seconds.
ApiError – If the API returns an error response.

Return type:

None

Examples

await pc.assistants.delete_file(
    assistant_name="my-assistant",
    file_id="file-abc123",
)

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)

Returns:

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

Raises:

NotFoundError – If the assistant does not exist.
ApiError – If the API returns another error response.

Return type:

AssistantModel

Examples

assistant = await pc.assistants.describe(name="my-assistant")
print(assistant.status)

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 file metadata and status.

Raises:

NotFoundError – If the file does not exist.
ApiError – If the API returns an error response.

Return type:

AssistantFileModel

Note

Unlike list_files(), this applies no age filter: a "ProcessingFailed" file whose created_on is more than 7 days old is still returned here after it has dropped out of that listing.

Examples

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

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:

assistant_name (str) – Name of the assistant that owns the operation.
operation_id (str) – Identifier of the operation to describe, as returned by upload_file(), delete_file(), or list_operations().

Returns:

OperationModel with status, operation_type, file_id, percent_complete, created_at, completed_on, ingestion_units and error. status is "Processing", "Completed" or "Failed". Read error only when status is "Failed": a retried operation keeps the previous attempt’s text, so a non-None error is not by itself evidence of failure.

Raises:

NotFoundError – If the assistant or the operation does not exist. A finished operation stays describable until it ages out of the API’s retention window, and 404s from then on.
ApiError – If the API returns an error response.

Return type:

OperationModel

Examples

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

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

Evaluate answer alignment against a ground truth answer.

Measures the correctness and completeness of a generated answer with respect to a ground truth answer. 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 aggregate scores, per-fact entailment results, and token usage statistics.

Raises:

ApiError – If the API returns an error response. This endpoint requires a paid plan.

Return type:

AlignmentResult

Examples

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

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.

Raises:

ApiError – If the API returns an error response.

Return type:

AsyncPaginator[AssistantModel]

Examples

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

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

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

List files for an assistant with lazy async pagination.

Parameters:

assistant_name (str) – Name of the assistant whose files to list.
filter (dict[str, Any] | None) – Optional metadata filter expression. Serialized to a JSON string before being sent to the API.
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:

NotFoundError – If the assistant does not exist.
ApiError – If the API returns an error response.

Return type:

AsyncPaginator[AssistantFileModel]

Note

A "ProcessingFailed" file drops out of this listing once its created_on is more than 7 days old. It is not gone — it stays retrievable by id through describe_file().

Examples

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

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

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, sent as the limit query parameter. Only sent when explicitly provided; omitted, the API chooses the page size. A value outside the range the API accepts comes back as an ApiError naming the bound it broke.
pagination_token (str | None) – Token from a previous response to fetch the next page.
filter (dict[str, Any] | None) – Optional metadata filter expression. Serialized to a JSON string before being sent to the API.
kwargs (Any)

Returns:

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

Raises:

NotFoundError – If the assistant does not exist.
ApiError – If the API returns an error response.

Return type:

ListFilesResponse

Examples

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

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

List an assistant’s operations with lazy async pagination.

Covers operations that are still in progress as well as ones that finished — both successes and failures — until they age out of the API’s retention window.

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:

PineconeValueError – If operation_type or status is not one of the values above.
NotFoundError – If the assistant does not exist.
ApiError – If the API returns an error response.

Return type:

AsyncPaginator[OperationModel]

Examples

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

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

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.

Only the parameters that are explicitly provided are sent in the request. Omitted parameters are not included as query params.

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, sent as the limit query parameter. Only sent when explicitly provided; omitted, the API chooses the page size. A value outside the range the API accepts comes back as an ApiError naming the bound it broke.
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:

PineconeValueError – If operation_type or status is not one of the values above.
NotFoundError – If the assistant does not exist.
ApiError – If the API returns an error response.

Return type:

ListOperationsResponse

Examples

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

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

List one page of assistants with explicit pagination control.

Only the parameters that are explicitly provided are sent in the request. Omitted parameters are not included as query params.

Parameters:

page_size (int | None) – Maximum number of assistants per page. Only sent when explicitly provided; omitted, the API chooses the page size. A value outside the range the API accepts comes back as an ApiError naming the bound it broke.
pagination_token (str | None) – Token from a previous response to fetch the next page.
kwargs (Any)

Returns:

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

Raises:

ApiError – If the API returns an error response.

Return type:

ListAssistantsResponse

Examples

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

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

Update an existing Pinecone assistant.

Updates the specified assistant’s instructions and/or metadata. Metadata is fully replaced (not merged) when provided. At least one of instructions and metadata must be given.

None means “leave this field alone” — it is omitted from the patch body rather than sent as an explicit null, and the server has no way to clear a field from a null. To clear, send the 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)

Returns:

AssistantModel describing the updated assistant.

Raises:

PineconeValueError – If neither instructions nor metadata is provided.
NotFoundError – If the assistant does not exist.
ApiError – If the API returns another error response.

Return type:

AssistantModel

Examples

# Update an assistant's instructions
assistant = await pc.assistants.update(
    name="my-assistant",
    instructions="You are a helpful research assistant.",
)

# Replace an assistant's metadata
assistant = await pc.assistants.update(
    name="my-assistant",
    metadata={"team": "ml", "version": "2"},
)

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.

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 to associate with file_stream. Required when file_stream is used, and must include a supported extension (.txt, .pdf, .json, .md, or .docx), since the extension determines how the file is processed. Ignored when file_path is given, since its basename already supplies the extension.
metadata (dict[str, Any] | None) – Optional metadata to attach to the file, e.g. {"department": "research"}. At most 16 KB once encoded.
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 immediately after upload with one describe call. Raises PineconeTimeoutError if processing is not done before the deadline.

Returns:

AssistantFileModel describing the uploaded file, once processing completes.

Raises:

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

file = await async_pc.assistants.upload_file(
    assistant_name="research-assistant",
    file_path="/data/report.pdf",
)
print(file.status)

with open("report.pdf", "rb") as f:
    file = await async_pc.assistants.upload_file(
        assistant_name="research-assistant",
        file_stream=f,
        file_name="report.pdf",
        metadata={"source": "quarterly-review"},
    )
print(file.status)