Pinecone ¶

Examples

>>> pc.indexes.configure("my-index", deployment={"replicas": 4})
>>> pc.indexes.configure("my-index", tags={"env": "prod"})

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 (2026-07 schema-based API).

An index’s field layout is declared as a schema of named, typed fields. Every field in the schema must be one that gets searched — dense_vector, sparse_vector, or string with full_text_search enabled. 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 after the index is created.

Changed in version 10.0: Replaces the 2025-10 signature. spec=, dimension=, metric=, and vector_type= are deprecated, keyword-only sugar for the current schema=/deployment= arguments (see below). pods=, metadata_config=, source_collection=, source_backup_id=, and spec=IntegratedSpec(...) have no equivalent here; use create_for_model() for integrated embedding.

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": {
        "embedding": {"type": "dense_vector",
                      "dimension": 1536, "metric": "cosine"},
        "body": {"type": "string",
                 "full_text_search": {"language": "en"}},
    }
}
```
Also accepts the dict produced by SchemaBuilder or an IndexSchema. A hybrid index must declare its sparse_vector field explicitly. At 2026-07 a dense field with metric="dotproduct" no longer accepts 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 docs/migration/v10-migration.md. 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 — 1-45 characters, 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 — {"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"}, up to 20 pairs. Pass None (the default) to attach none.
cmek_id (str | None) – ID of a customer-managed encryption key to encrypt the index with.
timeout (int | None) – How long to wait, in seconds, for the index to become ready before returning. None (default) waits indefinitely; -1 returns immediately without waiting.
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.
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.
ApiError – If the API returns another error response.

Return type:

Examples

>>> pc.indexes.create(
...     name="movie-recommendations",
...     schema={"fields": {"embedding": {
...         "type": "dense_vector", "dimension": 1536, "metric": "cosine"}}},
... )

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

Create a backup of an index.

Index-scoped shortcut for Pinecone.backups.create() — pass the same arguments either way.

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

Parameters:

index_name (str) – Name of the index to back up.
name (str | None) – Optional user-defined name for the backup.
description (str | None) – Optional description providing context for the backup.

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:

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

Return type:

Examples

>>> backup = pc.indexes.create_backup("my-index", name="nightly")
>>> backup.status
'Initializing'

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

Create a serverless index with an integrated embedding model.

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.

Parameters:

name (str) – Required name for the index (1-45 characters, ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$).
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" or "disabled".
tags (Mapping[str, str] | None) – Optional key-value tags (same limits as create()).
schema (dict[str, Any] | None) – Optional metadata schema dict for filterable metadata fields, e.g. {"fields": {"genre": {"filterable": True}}}. A bare field map is wrapped in {"fields": ...}.
read_capacity (dict[str, Any] | None) – Optional read capacity dict (see create()).
timeout (int | None) – Readiness polling — same semantics as create().

Returns:

IndexModel describing the created index.

Raises:

PineconeValueError – If name, cloud, region, or embed fail client-side validation.
ApiError – If the API returns an error response.

Return type:

Examples

>>> pc.indexes.create_for_model(
...     name="semantic-search",
...     cloud="aws",
...     region="us-east-1",
...     embed={"model": "multilingual-e5-large",
...            "field_map": {"text": "chunk_text"}},
... )

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

Delete an index by name.

After sending the delete request, removes the cached host URL for the index. By default, polls every 5 seconds until the index disappears with no upper time bound.

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:

PineconeValueError – If name is empty.
NotFoundError – If the index does not exist.
ForbiddenError – If deletion protection is enabled on the index.
PineconeTimeoutError – If the index still exists after timeout seconds.
ApiError – If the API returns another error response.

Return type:

None

Examples

pc.indexes.delete("my-index")

# Wait up to 60 seconds for deletion to complete
pc.indexes.delete("my-index", timeout=60)

describe(name)[source]¶

Get detailed information about a named index.

Caches the index’s host internally, so a later Pinecone.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:

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

Return type:

Examples

>>> desc = pc.indexes.describe("my-index")
>>> desc.host
'https://my-index.svc.pinecone.io'

describe_backup(backup_id)[source]¶

Describe a backup by its ID.

Alias of Pinecone.backups.describe(). Backups are identified independently of any index, so despite living on indexes this takes a backup ID rather than an index name.

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

Parameters:

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

Returns:

BackupModel with the current state of the backup.

Raises:

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

Return type:

Paginator[IndexModel]

Examples

>>> backup = pc.indexes.describe_backup("bkp-123")
>>> backup.status
'Ready'

exists(name)[source]¶

Check whether a named index exists.

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

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

Parameters:

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

Returns:

True if the index exists, False otherwise.

Raises:

PineconeValueError – If name is empty.
ApiError – If the API returns an error response other than a not-found error.

Return type:

bool

Examples

>>> pc.indexes.exists("my-index")
True

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

List all indexes in the project.

The server currently returns every index in one page, so the returned Paginator yields once and stops. It still exposes the paginator interface for consistency with other list methods, and so a future page size increase or signature change isn’t needed if the server starts paginating.

Changed in version 10.0: Returns a Paginator instead of an IndexList. Iteration keeps working; replace pc.indexes.list().names() with [idx.name for idx in pc.indexes.list()].

Parameters:

limit (int | None) – Maximum number of items to yield. Must be a positive integer. None yields all items.
pagination_token (str | None) – Token to resume pagination from a previous call. None starts from the beginning.

Returns:

Paginator over IndexModel instances.

Raises:

PineconeValueError – If limit is zero or negative.
ApiError – If the API returns an error response.

Return type:

Examples

>>> for index in pc.indexes.list():
...     print(index.name)

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

List the backups of one index.

Added in version 10.0: Graduated from pc.preview.indexes.list_backups, and gained include_deleted. For the project-wide listing use Pinecone.backups.list() with no index_name.

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.

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 to resume pagination from a previous call. limit still caps the total yield, but it is not sent alongside a token — see above.
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:

Paginator over BackupModel instances. Iteration stops when the response carries no pagination envelope.

Raises:

PineconeValueError – If index_name is empty or limit is zero or negative.
NotFoundError – If index_name does not resolve to an active index — see above.
ApiError – If the API returns another error response.

Return type:

Paginator[BackupModel]

Examples

>>> for backup in pc.indexes.list_backups("my-index"):
...     print(backup.backup_id, backup.status)

>>> orphans = pc.indexes.list_backups(
...     "my-index", include_deleted=True
... )
>>> [b.backup_id for b in orphans if b.source_index_deleted_at]
['bkp_oldidx']

Collections¶

class pinecone.client.collections.Collections(http)[source]¶

Bases: object

Control-plane operations for Pinecone collections.

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

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

Examples

from pinecone import Pinecone

pc = Pinecone(api_key="your-api-key")
names = [col.name for col in pc.collections.list()]

__init__(http)[source]¶

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

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 = pc.collections.create(name="my-collection", source="my-index")
>>> col.status
'Initializing'

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

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

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 = pc.collections.describe("my-collection")
>>> desc.size
1024

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 = pc.collections.list()
>>> collections.names()
['my-collection']

Backups¶

class pinecone.client.backups.Backups(http)[source]¶

Bases: object

Control-plane operations for Pinecone backups.

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

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

Examples

from pinecone import Pinecone

pc = Pinecone(api_key="your-api-key")
ids = [b.backup_id for b in pc.backups.list()]

__init__(http)[source]¶

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

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

Examples

>>> from pinecone import Pinecone
>>> pc = Pinecone(api_key="your-api-key")
>>> backup = pc.backups.create(index_name="product-search")
>>> backup.backup_id
'bk-abc123'

>>> backup = pc.backups.create(
...     index_name="product-search",
...     name="daily-20240115",
...     description="Scheduled daily backup before reindexing",
... )

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 Pinecone
>>> pc = Pinecone(api_key="your-api-key")
>>> pc.backups.delete(backup_id="bk-daily-20240115")

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:

Examples

>>> from pinecone import Pinecone
>>> pc = Pinecone(api_key="your-api-key")
>>> backup = pc.backups.describe(backup_id="bk-daily-20240115")
>>> backup.status
'Ready'

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:

Examples

>>> from pinecone import Pinecone
>>> pc = Pinecone(api_key="your-api-key")
>>> backup = pc.backups.get(backup_id="bk-daily-20240115")
>>> backup.status
'Ready'

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

>>> from pinecone import Pinecone
>>> pc = Pinecone(api_key="your-api-key")
>>> for backup in pc.backups.list():
...     print(backup.backup_id, backup.name)

>>> for backup in pc.backups.list(index_name="product-search"):
...     print(backup.name)

Recover backups of an index that has since been deleted:

>>> orphaned = pc.backups.list(
...     index_name="product-search", include_deleted=True
... )
>>> [b.backup_id for b in orphaned if b.source_index_deleted_at]
['bk-abc123']

BackupSchedules¶

class pinecone.client.backup_schedules.BackupSchedules(http)[source]¶

Bases: object

Control-plane operations for automatic, time-based backup schedules.

Parameters:: http (HTTPClient) – 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 Pinecone

pc = Pinecone(api_key="your-api-key")
schedule = pc.backup_schedules.create(
    index_name="product-search",
    name="daily-compliance-backup",
    frequency="daily",
    retention_days=90,
)
for run in pc.backup_schedules.iter_history(schedule_id=schedule.schedule_id):
    print(run.backup_id, run.status)

__init__(http)[source]¶

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

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:

Examples

>>> from pinecone import Pinecone
>>> pc = Pinecone(api_key="your-api-key")
>>> schedule = pc.backup_schedules.create(
...     index_name="product-search",
...     name="daily-compliance-backup",
...     frequency="daily",
...     retention_days=90,
... )
>>> schedule.frequency
'daily'

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 Pinecone
>>> pc = Pinecone(api_key="your-api-key")
>>> pc.backup_schedules.delete(
...     schedule_id="e88f7273-42aa-47e9-af73-593827136867"
... )

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:

Examples

>>> from pinecone import Pinecone
>>> pc = Pinecone(api_key="your-api-key")
>>> schedule = pc.backup_schedules.describe(
...     schedule_id="e88f7273-42aa-47e9-af73-593827136867"
... )
>>> schedule.enabled
True

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:

BackupScheduleHistoryList

Examples

>>> from pinecone import Pinecone
>>> pc = Pinecone(api_key="your-api-key")
>>> schedule = pc.backup_schedules.get(
...     schedule_id="e88f7273-42aa-47e9-af73-593827136867"
... )
>>> schedule.frequency
'daily'

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:

Examples

>>> from pinecone import Pinecone
>>> pc = Pinecone(api_key="your-api-key")
>>> runs = pc.backup_schedules.history(
...     schedule_id="e88f7273-42aa-47e9-af73-593827136867"
... )
>>> [r.backup_id for r in runs.scheduled()]
['b2c3d4e5-f6a7-8901-bcde-f12345678901']

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 Paginator 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:

Paginator[BackupScheduleHistoryItem]

Examples

>>> from pinecone import Pinecone
>>> pc = Pinecone(api_key="your-api-key")
>>> 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 Paginator 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:

Paginator[BackupScheduleModel]

Examples

>>> from pinecone import Pinecone
>>> pc = Pinecone(api_key="your-api-key")
>>> for s in pc.backup_schedules.iter_schedules(
...     index_name="my-index"
... ):
...     print(s.schedule_id, s.frequency, s.enabled)

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 Pinecone
>>> pc = Pinecone(api_key="your-api-key")
>>> schedules = pc.backup_schedules.list(index_name="my-index")
>>> schedules.names()
['daily-compliance-backup']
>>> [s.schedule_id for s in schedules.enabled_schedules()]
['e88f7273-42aa-47e9-af73-593827136867']

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: